エンティティ キーの作成と使用

この API は第 1 世代ランタイムでサポートされており、対応する第 2 世代ランタイムへのアップグレード時に使用できます。App Engine Go 1.12+ ランタイムに更新する場合は、移行ガイドを参照して、以前のバンドル サービスの移行オプションを確認してください。

Datastore 内の各エンティティは、キーによって一意に識別されます。キーは次のコンポーネントで構成されています。

• エンティティの名前空間。マルチテナンシーを可能にします。
• エンティティの種類。Datastore クエリ用にエンティティを分類します。
• オプションの祖先パス。Datastore 階層内のエンティティの位置を指定します

• 個々のエンティティの識別子。次のいずれかになります。

  • キー名の文字列
  • 整数の数値 ID

識別子はエンティティ キーの構成要素です。エンティティに永続的に割り当てられるため、変更できません。識別子は、次のいずれかの方法で割り当てます。

• エンティティに固有のキー名文字列を指定する。
• Datastore がエンティティに整数の数値 ID を自動的に割り当てる。

プロパティに「key」という名前を付けないでください。この名前は、Model キーを保存する特別なプロパティのために予約されています。「key」という名前のプロパティがある場合、ローカルでは問題なく機能しても、App Engine にデプロイできません。

エンティティにキー名を指定する

エンティティにキー名を割り当てるには、空でない 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)

識別子の割り当て

2 つの異なる自動 ID ポリシーを使用して自動 ID を生成するように、Datastore を構成できます。

• default ポリシーは、ほぼ均等に分布する未使用の ID をランダムに生成します。各 ID は最大 16 桁の 10 進数になります。
• legacy ポリシーは、連続しない小さい整数の ID を作成します。

エンティティの ID をユーザーに表示する場合や、ID の順序に従ってなんらかの処理を行う場合は、手動で割り当てることをおすすめします。

注: 高度なアプリケーションでは、キー名の文字列を使用するか数値 ID を自動生成する代わりに、作成したエンティティに独自の数値 ID を手動で割り当てる場合があります。ただし、手動で作成した数値 ID が別のエンティティに割り当てられないようにする方法はない点に注意してください。このような競合を回避する唯一の方法は、アプリケーションで datastore.AllocateIDs 関数を使用して ID のブロックを取得することです。Datastore の自動 ID 生成ツールは、この関数によって割り当てられた ID を追跡し、同じ ID が別のエンティティで使用されないようにします。競合を心配せずに、このような ID を安全に使用できます。

祖先パスを使用する

Cloud Datastore 内のエンティティは、ファイル システムのディレクトリ構造と同様に、階層的に構造化された空間を形成します。エンティティを作成するときに、別のエンティティを親として設定することもできます。新しいエンティティは、この親エンティティの子になります（ファイル システムとは異なり、親エンティティが実際に存在している必要はありません）。親を持たないエンティティは「ルート エンティティ」となります。エンティティと親との割り当ては永続的であり、エンティティの作成後は変更できません。同じ親を持つ 2 つのエンティティ、または 2 つのルート エンティティ（親を持たないエンティティ）に同じ数値 ID が割り当てられることはありません。

エンティティの親、親の親、さらにその親などは順に「祖先」として位置付けられ、エンティティの子、子の子、さらにその子などは順に「子孫」として位置付けられます。ルート エンティティとその子孫のエンティティは、すべて同じエンティティ グループに属します。ルート エンティティから始まり、親から子を経由して対象のエンティティに至るまでのエンティティの連なりのことを、エンティティの「祖先パス」といいます。エンティティを識別する完全なキーは、エンティティの祖先パスから始まってそのエンティティ自身で終わる一連の「種類と識別子のペア」で構成されています。

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

ルート エンティティの場合は祖先パスが空で、エンティティ自身の種類と識別子だけでキーが構成されています。

[Person:GreatGrandpa]

このコンセプトを次の図に示します。

エンティティの親を指定するには、datastore.NewKey に対して parent 引数を使用します。この引数の値は、親エンティティのキーである必要があります。次の例では、種類が 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)