實體、屬性和索引鍵

Datastore 中的資料物件又稱為「實體」。實體具有一或多個命名的「屬性」，每個屬性可以有一或多個值。相同種類的實體不需要具有相同屬性，而實體的特定屬性值並不全都需要屬於相同的資料類型 (如有必要，應用程式可在本身的資料模型建立及強制執行這類限制)。

Datastore 支援各種屬性值的資料類型。 包括：

  • 整數
  • 浮點數
  • 字串
  • 日期
  • 二進位資料

如需這些類型的完整清單，請參閱「屬性和值類型」一節。

Datastore 中的每個實體都有專門用來識別該實體的「金鑰」。索引鍵由下列元件組成：

  • 實體的「命名空間」，可允許多租戶架構
  • 實體的「種類」，可將實體分類以便進行 Datastore 查詢
  • 個別實體的「ID」，可以是以下其中一種：
    • 「索引鍵名稱」字串
    • 整數「數字 ID」
  • 選用的祖系路徑，可在 Datastore 階層結構中找到實體的位置

應用程式可使用實體索引鍵從 Datastore 擷取個別實體，或依據實體索引鍵或屬性值發出查詢，以擷取一或多個實體。

Java App Engine SDK 在直接支援 Datastore 功能的 com.google.appengine.api.datastore 套件中提供簡易的 API。本文件中的所有範例均以這個低階 API 為基礎；您可以選擇在應用程式中直接使用這個 API，或以其為基礎來建置自己的資料管理層。

Datastore 本身不會對實體結構強制執行任何限制，例如特定屬性是否具有特定類型的值；此項作業將由應用程式負責。

種類及 ID

每個 Datastore 實體都屬於特定「種類」，可根據查詢目的將實體分類：例如，人力資源應用程式可能會以屬於 Employee 種類的實體代表公司的每位員工。在 Java Datastore API 中，您建立實體時，可透過 Entity() 建構函式的引數來指定實體的種類。 以兩條底線 (__) 開頭的種類名稱均為保留名稱，不得使用。

以下範例會建立 Employee 種類的實體、填入屬性值，並將其儲存至 Datastore：

Entity employee = new Entity("Employee", "asalieri");
employee.setProperty("firstName", "Antonio");
employee.setProperty("lastName", "Salieri");
employee.setProperty("hireDate", new Date());
employee.setProperty("attendedHrTraining", true);

DatastoreService datastore = DatastoreServiceFactory.getDatastoreService();
datastore.put(employee);

除了種類以外，建立每個實體時還會指派實體的「ID」。因為 ID 屬於實體索引鍵的一部分，所以會與實體永久關聯，且無法變更。ID 可利用兩種方式指派：

  • 您的應用程式可以指定自身的實體「索引鍵名稱」字串。
  • 您可以讓 Datastore 自動指派整數的「數字 ID」給實體。

如要指派索引鍵名稱給實體，請在建立實體時，將名稱當做第二個引數提供給建構函式：

Entity employee = new Entity("Employee", "asalieri");

如要讓 Datastore 自動指派數字 ID，請省略這個引數：

Entity employee = new Entity("Employee");

指派 ID

您可以設定 Datastore 透過兩種不同的自動 ID 政策產生自動 ID：

  • default 政策可產生隨機順序的未使用 ID，近乎均勻分佈。每個 ID 最長可達 16 個十進位數字。
  • legacy 政策可建立一系列非連續的較小整數 ID。

如果您要向使用者顯示實體 ID，並/或依據其順序顯示，最理想的方式就是使用手動分配。