Datastore Java API 總覽

「Google 應用服務引擎」資料存放區為您的網路應用程式，提供可擴充的完整資料儲存服務。資料存放區以網路應用程式為設計概要，著重於讀取和查詢的效能表現，可儲存具備屬性的資料實體，並依照應用程式定義種類組織整理。資料存放區可以對相同種類的實體執行查詢，還可以進一步篩選或排序其屬性值和屬性金鑰。為了在龐大資料集中快速取得結果，所有查詢均會預先設定索引。資料存放區使用應用程式所定義的實體分組做為分散式資料網路的交易單位，進而支援交易式更新。

• 資料存放區簡介
• Java 資料介面
• 實體和屬性
• 查詢和索引
• 交易和實體群組
• 配額和限制

資料存放區簡介

「應用服務引擎」的資料存放區會對資料物件 (亦即「實體」) 儲存和執行查詢。實體擁有一或多個「屬性」；而屬性是幾種支援資料類型的其中一種已命名值，且可以是其他實體的參照。

資料存放區可以在單一交易中執行多個操作，並於任何一項操作失敗時，復原整個交易。這對分散式網路應用程式特別有用，因為在此類應用程式中，可能會出現多位使用者同時存取或操縱相同資料物件的情形。

與傳統資料庫不同，資料存放區使用分散式架構來支援非常龐大的資料集。應用服務引擎的應用程式可以透過描述資料物件之間的關聯，以及透過定義查詢的索引，來最佳化資料分散的方式。

「應用服務引擎」資料存放區的一致性十分明顯，卻不是關聯式資料庫。雖然資料存放區介面的許多功能與傳統資料庫相同，但是資料存放區也擁有獨一無二的特性，可透過完全不同的資料設計和管理方式，展現自動調整的優勢。

Java 資料介面

資料存放區實體「沒有結構」：兩個相同種類的實體不需具備相同屬性，而相同屬性也不需使用相同值類型。應用程式必須確保實體在需要時符合結構。Java SDK 包括 Java Data Object (JDO) 和 Java Persistence API (JPA) 介面的實作，適用於資料的模型建立和持續保存。這些標準介面包括特定機制，可用於定義資料物件的類別，以及執行查詢。資料存放區還提供低階 API，可用於實作其他的介面卡，也可直接在應用程式中使用。

本文件將詳細說明 JDO。其他的 JDO 資訊來源多半也適用「應用服務引擎」。請參考本指南的其他文件，以取得實作差異和未實作功能的相關資訊。

此外，「應用服務引擎」也支援 JPA。本文件僅簡短說明 JPA；請參閱「使用 JPA」。

JDO 會使用 Java 類別 (「plain old Java object」或「POJO」) 的註解，描述如何在資料存放區中儲存類別的實例為實體，以及如何在擷取資料存放區實體時，將它們重新建立為實例。下方為簡單資料類別的範例：

Employee.java

import java.util.Date;
import javax.jdo.annotations.IdGeneratorStrategy;
import javax.jdo.annotations.IdentityType;
import javax.jdo.annotations.PersistenceCapable;
import javax.jdo.annotations.Persistent;
import javax.jdo.annotations.PrimaryKey;

@PersistenceCapable(identityType = IdentityType.APPLICATION)
public class Employee {
    @PrimaryKey
    @Persistent(valueStrategy = IdGeneratorStrategy.IDENTITY)
    private Long id;

    @Persistent
    private String firstName;

    @Persistent
    private String lastName;

    @Persistent
    private Date hireDate;

    public Person(String firstName, String lastName, Date hireDate) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.hireDate = hireDate;
    }

    // Accessors for the fields.  JDO doesn't use these, but your application does.

    public Long getId() {
        return id;
    }

    public String getFirstName() {
        return firstName;
    } 

    // ... other accessors...
}

您可以使用 PersistenceManager 物件與資料存放區互動，該物件可以從 PersistenceManagerFactory 物件取得。由於設定 PersistenceManagerFactory 的代價高昂，請務必確認在應用程式的留存期間 (可能橫跨眾多要求)，您只會取得實例一次。一個簡單的確認方法是，將實例包裝在單一類別，如下所示：

PMF.java

import javax.jdo.JDOHelper;
import javax.jdo.PersistenceManagerFactory;

public final class PMF {
    private static final PersistenceManagerFactory pmfInstance =
        JDOHelper.getPersistenceManagerFactory("transactions-optional");

    private PMF() {}

    public static PersistenceManagerFactory get() {
        return pmfInstance;
    }
}

您可以建立資料類別的實例，然後儲存至資料存放區：

import java.util.Date;
import javax.jdo.JDOHelper;
import javax.jdo.PersistenceManager;
import javax.jdo.PersistenceManagerFactory;

import Employee;
import PMF;

// ...
        Employee employee = new Employee("Alfred", "Smith", new Date());

        PersistenceManager pm = PMF.get().getPersistenceManager();

        try {
            pm.makePersistent(employee);
        } finally {
            pm.close();
        }

JDO 包括一個 JDOQL 查詢介面。透過 JDOQL，您可以視實體為此類別的實例以執行擷取，如下所示：

import java.util.List;
import Employee;

// ...
        String query = "select from " + Employee.class.getName() + " where lastName == 'Smith'";
        List<Employee> employees = (List<Employee>) pm.newQuery(query).execute();

實體與屬性

「應用服務引擎」資料存放區中的資料物件稱為「實體」。實體具有一或多個「屬性」；而屬性是幾種支援資料類型的其中一種已命名值，包括整數、浮點值、字串、日期、二進位資料和其他資料。

每個實體也具有可唯一識別該實體的金鑰。最簡單的金鑰有資料存放區所提供的種類和唯一的數字 ID。此 ID 也可以是應用程式所提供的字串。

應用程式可以透過金鑰，或透過比對實體屬性的查詢，從資料存放區擷取實體。查詢可能傳回零或多個實體，可以傳回以屬性值排序的結果。查詢也可以限制資料存放區傳回的結果數量，以節省記憶體和執行時間。

「應用服務引擎」資料存放區不會要求指定種類的所有實體都具有相同的屬性。這一點與關聯式資料庫不同。應用程式可以使用 SDK 所包含的程式庫或自有程式碼，指定或強制資料模型。

屬性可擁有一或多個值。具有多個值的屬性可擁有混合類型的值。查詢具有多個值的屬性，可測試是否有值符合查詢條件。因此，此類屬性在驗證會員資格時十分實用。

查詢和索引

「應用服務引擎」資料存放區查詢會在指定種類 (資料類別) 的每個實體上執行，進而對實體屬性值和屬性金鑰，指定零或多個篩選器以及排序順序。如果查詢篩選器和排序順序所提及的實體屬性均擁有至少一個值 (可能為空值)，且屬性值符合所有篩選條件，則系統會傳回實體做為查詢結果。

每個資料存放區查詢都會使用索引，而索引是一個表格，當中列有依需求排序的查詢結果。「應用服務引擎」應用程式是透過設定檔定義其索引。如果開發網頁伺服器遇到尚未設定索引的查詢，就會自動將建議新增至這個檔案。您可以在上傳應用程式之前編輯該檔案，以手動調整索引。如果應用程式變更了資料存放區實體，資料存放區就會以正確的結果來更新索引。應用程式執行查詢時，資料存放區會直接從相應的索引擷取結果。

此機制支援的查詢種類十分廣泛，因此也適合大部分應用程式。不過，此機制並不支援您在其他資料庫技術所慣用的部分查詢種類。

交易和實體群組

使用「應用服務引擎」資料存放區時，每個嘗試建立、更新或刪除實體的動作都是在「交易」中進行。交易可確保實體的所有變更都儲存在資料存放區，或在操作失敗時復原這些變更，以保證實體中資料的一致性。

您可以使用 Transaction API (交易 API)，在單一交易中對實體執行多項動作。舉例來說，如果您要增加某個物件中的計數器欄位值，您必須讀取計數器的值、計算新的值，再予以儲存。如果沒有交易，其他程序可能會在您讀取和更新的空檔中，增加計數器數值，導致應用程式覆寫已更新的值。在單一交易中執行讀取、計算和寫入可以防止其他程序干擾增加計數的過程。

您可以在單一交易中，對多個實體進行變更。為了支援這項功能，「應用服務引擎」必須事先瞭解哪些實體會同時更新，才能以支援交易的方式儲存這些實體。建立實體時，您必須宣告此實體與其他實體屬於相同的「實體群組」。所有在交易中擷取、建立、更新或刪除的實體，均需屬於相同的實體群組。

實體群組是由實體關聯性的階層所定義。如要在群組中建立實體，您必須宣告實體是群組中另一個實體的「子系」，而另一個實體則是「父系」。沒有父系的已建立實體是「根實體」，而沒有子系的根實體則是單獨存在於某個實體群組中。每個實體與根實體之間，都擁有父子式關聯性路徑 (無父系的實體擁有最短的路徑)。此路徑是實體完整金鑰的重要元素。在路徑中，每個實體的種類與 ID 或金鑰名稱均可代表完整金鑰。

資料存放區使用「開放式同步存取」管理交易。當應用程式的執行個體對實體群組中的實體套用變更時，其他嘗試更新群組實體的動作會立即失敗。應用程式可以再次嘗試交易，以套用更新資料。

配額和限制

對 Datastore API (資料存放區 API) 的每次呼叫會算入「資料存放區 API 呼叫」的配額中。請注意，某些程式庫呼叫程序會造成多次對基礎資料存放區 API 的呼叫。

應用程式傳送至資料存放區的資料會算入「傳送至 (資料存放區) API 的資料」的配額中。應用程式從資料存放區接收的資料會算入「從 (資料存放區) API 接收的資料」的配額中。

儲存在資料存放區的資料總數不得超過「已儲存資料 (可調整)」的配額。這包含實體屬性和金鑰，但是「不包括」索引。

資料存放區作業所使用的 CPU 時間長度則需遵循下列配額：

• CPU 時間 (可調整)
• 資料存放區 CPU 時間

如需瞭解配額的詳細資訊，請參閱「配額」，或參閱「管理控制台」的「配額詳細資訊」一節。

除了配額之外，使用資料存放區時也需遵循下列限制：