建立及使用實體金鑰

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

  • 實體的「命名空間」，可允許多租戶架構
  • 實體的類型，可將實體分類以便進行 Datastore 查詢
  • 選用的祖系路徑，可將實體置於 Datastore 階層之中。

  • 個別實體的ID，可以是以下兩者之一：

    • 「金鑰名稱」字串
    • 整數的「數字 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，並/或依據其順序顯示，最理想的方式就是使用手動分配。

使用祖系路徑

Cloud Datastore 中的實體會形成與檔案系統目錄結構類似的階層結構空間。建立實體時，可選擇將其他實體指定為「父項」；新實體則為父系實體的「子項」(請注意，不同於檔案系統，父項實體不需要實際存在)。沒有父項的實體則是「根實體」。實體與父項實體之間具有永久關聯性，一旦實體建立後就無法變更。Cloud Datastore 絕對不會將相同的數字 ID 指派給父項相同的兩個實體，也不會指派給兩個根實體 (即沒有父項的實體)。

實體的父項、父項的父項等以此類推，全都是這個實體的「祖系」；實體的子項、子項的子項等等，則都是其「子系」。根實體及其所有子系都屬於相同的「實體群組」。從根實體開始，再從父項到子項，最後到指定實體的實體序列，即構成該實體的「祖系路徑」。識別實體的完整索引鍵，包含連串種類-ID 組合序列，其中指定了實體的祖系路徑，最後則以該實體本身的種類-ID 組合做為結尾：

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

根實體的祖系路徑是空白路徑，其金鑰只包含實體本身的種類與 ID。

[Person:GreatGrandpa]

本概念以下圖說明：

顯示實體群組中根實體與子實體的關係

如要指定實體的父項，請在建立子系實體時，提供父系實體的金鑰做為 Entity() 建構函式的引數。您可以呼叫父系實體的 getKey() 方法來取得金鑰：

Entity employee = new Entity("Employee");
datastore.put(employee);

Entity address = new Entity("Address", employee.getKey());
datastore.put(address);

如果新實體也擁有索引鍵名稱，請提供索引鍵名稱做為 Entity() 建構函式的第二個引數，並提供父系實體的索引鍵做為第三個引數：

Entity address = new Entity("Address", "addr1", employee.getKey());

產生金鑰

應用程式可以使用 KeyFactory 類別，為實體建立 Key 物件，這些實體來自已知的元件，例如實體的類型和 ID。如果實體沒有父項，請將種類與 ID (金鑰名稱字串或數字 ID) 傳送至靜態方法 KeyFactory.createKey()，藉以建立金鑰。以下範例會為種類為 Person 且金鑰名稱為 "GreatGrandpa" 或數字 ID 為 74219 的實體建立金鑰：

Key k1 = KeyFactory.createKey("Person", "GreatGrandpa");
Key k2 = KeyFactory.createKey("Person", 74219);

如果金鑰包含路徑元件，您可以使用輔助類別 KeyFactory.Builder 建立路徑。這個類別的 addChild 方法可將單一實體新增至路徑，並傳回建構函式本身，讓您可以將一系列呼叫鏈結在一起，進從根實體開始，一次為一個實體建構路徑。建構完整路徑之後，請呼叫 getKey 以擷取產生的金鑰：

Key k =
    new KeyFactory.Builder("Person", "GreatGrandpa")
        .addChild("Person", "Grandpa")
        .addChild("Person", "Dad")
        .addChild("Person", "Me")
        .getKey();

KeyFactory 類別也包含靜態方法 keyToString 和 stringToKey，用於在金鑰及其字串表示法之間進行轉換：

String personKeyStr = KeyFactory.keyToString(k);

// Some time later (for example, after using personKeyStr in a link).
Key personKey = KeyFactory.stringToKey(personKeyStr);
Entity person = datastore.get(personKey);

金鑰的字串表示法為「可在網路上安全使用」：這種表示法並不包含在 HTML 或網址中被視為特殊的字元。