建立及使用實體金鑰

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

  • 實體的「命名空間」,可允許多租戶架構
  • 實體的「種類」,可將實體分類以便進行 Cloud Datastore 查詢
  • 選用的「祖系路徑」,可將實體置於 Cloud Datastore 階層之中。
  • 個別實體的「ID」,可以是以下兩者之一:

    • 「金鑰名稱」字串
    • 整數的「數字 ID」

由於 ID 是實體金鑰的一部分,因此與實體之間具有永久關聯,無法變更。您可以透過兩種方式指派 ID:

  • 針對實體指定您自己的「金鑰名稱」字串。
  • 讓 Cloud Datastore 自動指派一個整數的「數字 ID」給實體。

指定實體的金鑰名稱

如要指派金鑰名稱給實體,請在建立實體時,將名稱當做第二個引數提供給建構函式:

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

如要讓 Cloud Datastore 自動指派數字 ID,請省略此引數:

Entity employee = new Entity("Employee");

指派 ID

您可以進行設定,讓 Cloud Datastore 透過兩種不同的自動 ID 政策產生自動 ID:

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

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

使用祖系路徑

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

實體的父項、父項的父項等以此類推,全都是這個實體的「祖系」;實體的子項、子項的子項等等,則都是其「子系」。 根實體及所有子系都屬於相同的「實體群組」。 從根實體開始,再從父項到子項,最後到指定實體的實體序列,即構成該實體的「祖系路徑」。 完整金鑰代表包含種類-ID 組合的實體,該組合指定其祖系路徑,並且止於實體本身的這類組合:

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

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

[Person:GreatGrandpa]

本概念以下圖說明:

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

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

Java 8

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

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

Java 7

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,藉由實體種類與 ID 等已知元件,為實體建立 Key 物件。如果實體沒有父項,請將種類與 ID (金鑰名稱字串或數字 ID) 傳送至靜態方法 KeyFactory.createKey(),藉以建立金鑰。以下範例會為種類為 Person 且金鑰名稱為 "GreatGrandpa" 或數字 ID 為 74219 的實體建立金鑰:

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

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

Java 8

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

Java 7

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

KeyFactory 類別還包含靜態方法 keyToStringstringToKey,用來在金鑰及其字串表示法之間進行轉換:

Java 8

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);

Java 7

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 或網址中被視為特殊的字元。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Java 適用的 App Engine 標準環境