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

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

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

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

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

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

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

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

エンティティにキー名を設定するには、エンティティの作成時にコンストラクタの 2 番目の引数として名前を指定します。

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

Datastore が数値 ID を自動的に割り当てるように設定するには、この引数を省略します。

Entity employee = new Entity("Employee");

識別子の割り当て

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

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

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

祖先パスを使用する

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

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

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

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

[Person:GreatGrandpa]

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

エンティティ グループ内のルート エンティティと子エンティティの関係を示す図

エンティティの親を指定するには、子エンティティの作成時に、親エンティティのキーを Entity() コンストラクタの引数として指定します。キーを取得するには、親エンティティの getKey() メソッドを呼び出します。

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

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

作成するエンティティにキー名も指定する場合は、Entity() コンストラクタの 2 番目の引数にそのキー名を指定し、3 番目の引数に親のエンティティのキーを指定します:

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 メソッドでは、1 つのエンティティがパスに追加され、ビルダーそのものが返されます。したがって、これを連続して呼び出すことにより、ルート エンティティから始めて、エンティティを 1 つずつ追加してパスを構築できます。完全なパスを作成した後、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 や URL で特殊文字とみなされる文字は含まれません。