Entitätsschlüssel erstellen und verwenden

Jede Entität in Datastore hat einen Schlüssel, der sie eindeutig identifiziert. Der Schlüssel besteht aus den folgenden Komponenten:

  • Namespace der Entität, der die Mehrinstanzenfähigkeit ermöglicht
  • Die Art der Entität, mit der sie für Datastore-Abfragen kategorisiert wird
  • Ein optionaler Ancestor-Pfad, der die Entität in der Datastore-Hierarchie findet.

  • Kennung der einzelnen Entität, entweder

    • ein String mit dem Schlüsselnamen oder
    • eine ganzzahlige numerische ID

Weil die Kennung Teil des Schlüssels der Entität ist, wird sie permanent mit der Entität verknüpft und kann nicht geändert werden. Für die Zuweisung der Kennung haben Sie zwei Möglichkeiten:

  • Sie können einen eigenen Schlüsselnamen-String für die Entität angeben.
  • Datastore kann der Entität automatisch eine ganzzahlige numerische ID zuweisen.

Schlüsselname für eine Entität angeben

Übergeben Sie dem Konstruktor beim Erstellen der Entität den Namen als zweites Argument, um einer Entität einen Schlüsselnamen zuzuweisen:

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

Wenn Datastore automatisch eine numerische ID zuweisen soll, lassen Sie dieses Argument weg:

Entity employee = new Entity("Employee");

Kennungen zuweisen

Sie können Datastore so konfigurieren, dass mithilfe von automatische IDs generiert werden zwei verschiedene Richtlinien für die automatische ID:

  • Die Richtlinie default generiert eine zufällige Abfolge von bisher nicht verwendeten IDs, die näherungsweise gleichmäßig verteilt sind. Jede ID kann maximal 16 Dezimalstellen enthalten.
  • Die Richtlinie legacy erstellt eine Abfolge nicht aufeinanderfolgender IDs aus kleineren Ganzzahlen.

Wenn Sie die Entitäts-IDs für den Nutzer anzeigen möchten und/oder deren Reihenfolge wichtig ist, ist eine manuelle Zuordnung die beste Lösung.

Ancestor-Pfade verwenden

Entitäten in Cloud Datastore bilden einen hierarchisch strukturierten Bereich ähnlich der Verzeichnisstruktur eines Dateisystems. Wenn Sie eine Entität erstellen, können Sie optional eine weitere Entität als übergeordnetes Element angeben. Die neue Entität ist dann ein untergeordnetes Element der übergeordneten Entität. Im Gegensatz zu einem Dateisystem muss die übergeordnete Entität nicht tatsächlich vorhanden sein. Eine Entität ohne übergeordnetes Element wird als Stammentität bezeichnet. Die Verknüpfung zwischen einer Entität und ihrer übergeordneten Entität ist dauerhaft und kann nicht geändert werden, nachdem die Entität erstellt wurde. Cloud Datastore weist zwei Entitäten mit derselben übergeordneten Entität oder zwei Stammentitäten (Entitäten ohne übergeordnete Entität) niemals dieselbe numerische ID zu.

Alle übergeordneten Elemente einer Entität werden als ihre Ancestors bezeichnet und alle untergeordneten Entitäten sind ihre Nachfolger. Eine Stammentität und alle ihre Nachfolger gehören zu derselben Entitätengruppe. Die Abfolge der Entitäten, von einer Stammentität über die untergeordneten Elemente bis zu einer bestimmten Entität, bildet den Ancestor-Pfad. Der vollständige Schlüssel, der die Entität identifiziert, besteht aus einer Abfolge von Art/Kennungs-Paaren, die den Ancestor-Pfad angeben und mit dem Paar der Entität selbst enden:

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

Bei einer Stammentität ist der Ancestor-Pfad leer und der Schlüssel besteht ausschließlich aus der eigenen Art und der eigenen Kennung der Entität:

[Person:GreatGrandpa]

Dieses Konzept wird anhand des folgenden Diagramms veranschaulicht:

Zeigt die Beziehung der Stammentität zu den untergeordneten Entitäten in der Entitätengruppe an

Wenn Sie das übergeordnete Element einer Entität festlegen möchten, geben Sie den Schlüssel der übergeordneten Entität beim Erstellen der untergeordneten Entität als Argument für den Konstruktor Entity() an. Sie können den Schlüssel abrufen, indem Sie die Methode getKey() der übergeordneten Entität aufrufen:

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

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

Hat die neue Entität auch einen Schlüsselnamen, übergeben Sie dem Entity()-Konstruktor beim Erstellen der Entität den Namen als zweites Argument und den Schlüssel der übergeordneten Entität als drittes Argument:

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

Schlüssel generieren

Anwendungen können die Klasse KeyFactory verwenden, um ein Key -Objekt für eine Entität aus bekannten Komponenten wie Typ und ID der Entität zu erstellen. Für eine Entität ohne übergeordnetes Element übergeben Sie den Typ und die ID an die statische Methode KeyFactory.createKey(), um den Schlüssel zu erstellen. In den folgenden Beispielen wird ein Schlüssel für eine Entität vom Typ Person mit dem Schlüsselnamen "GreatGrandpa" oder der numerischen ID 74219 erstellt:

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

Wenn der Schlüssel eine Pfadkomponente enthält, können Sie den Pfad mit der Hilfsklasse KeyFactory.Builder erstellen. Die Methode addChild dieser Klasse fügt dem Pfad eine einzelne Entität hinzu und gibt den Builder selbst zurück, sodass Sie eine Reihe von Aufrufen, beginnend mit der Stammentität, verketten können, um den Pfad eine Entität aufzubauen nacheinander. Rufen Sie nach dem Erstellen des vollständigen Pfads getKey auf, um den resultierenden Schlüssel abzurufen:

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

Die Klasse KeyFactory enthält außerdem die statischen Methoden keyToString und stringToKey für die Konvertierung zwischen Schlüsseln und ihren Stringdarstellungen:

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

Die Stringdarstellung eines Schlüssels ist "websicher". Das bedeutet, dass sie keine Zeichen enthält, die in HTML oder URLs als Sonderzeichen gelten.