建立及使用實體金鑰

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

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

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

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

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

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

指定實體的金鑰名稱

如要指派鍵名稱給實體，請將非空白的 stringID 引數提供至 datastore.NewKey：

// Create a key with a key name "asalieri".
key := datastore.NewKey(
	ctx,        // context.Context
	"Employee", // Kind
	"asalieri", // String ID; empty means no string ID
	0,          // Integer ID; if 0, generate automatically. Ignored if string ID specified.
	nil,        // Parent Key; nil means no parent
)

如要讓 Datastore 自動指派數字 ID，請使用空白的 stringID 引數：

// Create a key such as Employee:8261.
key := datastore.NewKey(ctx, "Employee", "", 0, nil)
// This is equivalent:
key = datastore.NewIncompleteKey(ctx, "Employee", nil)

指派 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]

本概念以下圖說明：

如要指定實體的父項，請將 parent 引數用於 datastore.NewKey。這個引數的值應為父系實體的金鑰。以下範例會建立 Address 類型的實體，並指定 Employee 實體做為其父項：

// Create Employee entity
employee := &Employee{ /* ... */ }
employeeKey, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Employee", nil), employee)

// Use Employee as Address entity's parent
// and save Address entity to datastore
address := &Address{ /* ... */ }
addressKey := datastore.NewIncompleteKey(ctx, "Address", employeeKey)
_, err = datastore.Put(ctx, addressKey, address)