Entitätsschlüssel erstellen und verwenden

Diese API wird für Laufzeiten der ersten Generation unterstützt und kann beim Upgrade auf entsprechende Laufzeiten der zweiten Generation verwendet werden. Wenn Sie auf die App Engine Java 11/17-Laufzeit aktualisieren möchten, erfahren Sie in der Migrationsanleitung mehr über Ihre Migrationsoptionen für gebündelte Legacy-Dienste.

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.

Geben Sie einer Property nicht den Namen "key". Dieser Name ist für eine spezielle Property zum Speichern des Schlüssels "Model" reserviert. Lokal würde ein Attribut namens "key" zwar funktionieren, es würde aber die Bereitstellung in App Engine unmöglich machen.

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.

Hinweis: Komplexere Anwendungen versuchen gelegentlich, den von ihnen erstellten Entitäten explizit eigene numerische IDs zuzuweisen, anstatt Schlüsselnamenstrings zu verwenden oder numerische IDs automatisch zu generieren. Dabei ist zu beachten, dass Datastore nicht daran gehindert werden kann, eine Ihrer manuellen numerischen IDs einer anderen Entität zuzuweisen. Derartige Konflikte können nur vermieden werden, wenn die Anwendung einen Block von IDs mit der Methode DatastoreService.allocateIds() oder AsyncDatastoreService.allocateIds() abruft. Der automatische ID-Generator von Datastore verfolgt IDs, die mit diesen Methoden zugewiesen wurden. So wird vermieden, dass diese für eine andere Entität wiederverwendet werden, damit Sie solche IDs ohne Konflikt sicher nutzen können.

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:

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.

Hinweis: Die Methode KeyFactory.keyToString unterscheidet sich von Key.toString, die einen für Menschen lesbaren String zurückgibt, der für die Fehlerbehebung und das Logging geeignet ist. Wenn Sie einen Stringwert benötigen, der in einen verwendbaren Schlüssel konvertiert werden kann, verwenden Sie KeyFactory.keyToString.

Beachten Sie außerdem, dass die Stringdarstellung eines Schlüssels nicht verschlüsselt ist: Ein Nutzer kann den Schlüsselstring decodieren, um seinen zu extrahieren Komponenten, einschließlich der Typen und Kennungen der Entität und ihrer Ancestors. Ist es wichtig, diese Informationen vor dem Nutzer zu verbergen, müssen Sie den Schlüsselstring selbst verschlüsseln, bevor Sie ihn an den Nutzer senden.