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 Laufzeit von App Engine Go 1.12 oder höher aktualisieren, finden Sie in der Migrationsanleitung Informationen zu Ihren 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

Wenn Sie einer Entität einen Schlüsselnamen zuweisen möchten, müssen Sie für datastore.NewKey ein nicht leeres Argument stringID angeben:

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

Wenn Datastore automatisch eine numerische ID zuweisen soll, verwenden Sie ein leeres stringID-Argument:

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

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, indem die Anwendung einen Block von IDs mit der Methode datastore.AllocateIDs abruft. Der automatische ID-Generator von Datastore verfolgt IDs, die mit dieser Funktion 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

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:

Das übergeordnete Element einer Entität wird mithilfe des Arguments parent für datastore.NewKey festgelegt. Der Wert dieses Arguments sollte der Schlüssel der übergeordneten Entität sein. Im folgenden Beispiel wird eine Entität der Art Address erstellt und eine Employee-Entität als deren übergeordnetes Element bestimmt:

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