Modul google.appengine.ext.ndb.key

Übersicht

Die Schlüsselklasse und zugehörigen Dienstprogramme.

Ein Schlüssel schließt die folgenden Informationen ein, die zusammen im App Engine-Datenspeicher eine (mögliche) Entität eindeutig kennzeichnen:

  • Eine Anwendungs-ID (String)

  • Einen Namespace (String)

  • Eine Liste mit einem oder mehreren (kind, id)-Paaren, wobei der Typ ein String und die ID ein String oder eine Ganzzahl ist

Die Anwendungs-ID muss immer Teil des Schlüssels sein. Da die meisten Anwendungen jedoch nur auf ihre eigenen Entitäten zugreifen können, wird standardmäßig die aktuelle Anwendungs-ID verwendet, sodass Sie diese nicht explizit angeben müssen. Der Wert darf nur nicht leer sein.

Der Namespace benennt eine Partition der obersten Ebene des Schlüsselbereichs für eine bestimmte Anwendung. Wenn Sie noch nie von Namespaces gehört haben, können Sie diese Funktion einfach ignorieren.

Das Wichtigste sind die (kind, id)-Paare. Ein Schlüssel muss mindestens ein (kind, id)-Paar haben. Das letzte (kind, id)-Paar gibt den Typ und die ID der Entität zurück, auf die der Schlüssel verweist. Die anderen Paare geben nur einen "übergeordneten Schlüssel" an.

Der Typ ist ein String, der den Namen der Modellklasse angibt, mit der die Entität dargestellt wird. In traditionelleren Datenbanken wäre dies der Tabellenname. Eine Modellklasse ist eine Python-Klasse, die von ndb.Model abgeleitet wird. Weitere Informationen finden Sie in der Dokumentation zu ndb/model.py. Als Typ wird nur der Klassenname selbst verwendet. Dies bedeutet, dass alle Modellklassen innerhalb einer Anwendung eindeutige Namen haben müssen. Sie können dies auf Klassenbasis überschreiben.

Die ID ist ein String oder eine Ganzzahl. Wenn die ID ein String ist, steuert die Anwendung, wie IDs zugewiesen werden: Sie legt beispielsweise fest, ob Sie eine E-Mail-Adresse als ID für Account-Entitäten verwenden können.

Damit Sie ganzzahlige IDs verwenden können, muss der Datenspeicher einer Entität beim ersten Einfügen in den Datenspeicher eine eindeutige ID zuweisen können. Sie können die ID auf "None" festlegen, um den Schlüssel für eine Entität darzustellen, die noch nicht in den Datenspeicher eingefügt wurde. Der abschließende Schlüssel wird zusammen mit der zugewiesenen ID zurückgegeben, nachdem die Entität erfolgreich in den Datenspeicher eingefügt wurde.

Ein Schlüssel, für den die ID des letzten (kind, id)-Paares auf "None" gesetzt ist, wird als unvollständiger Schlüssel bezeichnet. Derartige Schlüssel können nur zum Einfügen von Entitäten in den Datenspeicher verwendet werden.

Ein Schlüssel mit genau einem (kind, id)-Paar wird als Schlüssel auf oberster Ebene oder als Stammschlüssel bezeichnet. Schlüssel auf oberster Ebene werden auch als Entitätengruppen verwendet, die bei der Transaktionsverwaltung eine Rolle spielen.

Wenn mehr als ein (kind, id)-Paar vorhanden ist, stellen alle bis auf das letzte Paar den "Ancestor-Pfad" dar. Dies wird auch als der Schlüssel der "übergeordneten Entität" bezeichnet.

Sonstige Einschränkungen:

  • Typ- und String-IDS dürfen nicht leer und müssen maximal 500 Byte lang sein. Bei Python-Unicode-Objekten gilt diese Einschränkung nach der UTF-8-Codierung. HINWEIS: Dies wird als die Konstante _MAX_KEYPART_BYTES auf Modulebene definiert.

  • Ganzzahlige IDs müssen mindestens 1 und weniger als 2**63 sein.

Weitere Informationen zu Namespaces finden Sie unter http://code.google.com/appengine/docs/python/multitenancy/overview.html. Der Namespace verwendet standardmäßig den vom Namespace-Manager ausgewählten Standard-Namespace. Um den leeren Namespace explizit auszuwählen, übergeben Sie namespace=’‘.

Inhalt

Klasse google.appengine.ext.ndb.key.Keysource

Basiert auf: object

Ein unveränderlicher Datenspeicherschlüssel

Aus Gründen der Flexibilität und Benutzerfreundlichkeit werden mehrere Konstruktorsignaturen unterstützt.

Die gängigste Methode zum Erstellen eines Schlüssels sind Positionsargumente: - Key(kind1, id1, kind2, id2, …)

Dies ist die Kurzschreibweise für eine der beiden längeren Formen: - Key(pairs=[(kind1, id1), (kind2, id2), …]) - Key(flat=[kind1, id1, kind2, id2, …])

Jede der oben genannten Konstruktorformen kann mit "parent=<key>" zusätzlich einen weiteren Schlüssel übergeben. Die (kind, id)-Paare des übergeordneten Schlüssels werden vor den explizit übergebenen (kind, id)-Paaren eingefügt.

Sie können auch einen Schlüssel aus einem URL-sicheren Codierstring erstellen: - Key(urlsafe=<string>)

Fortgeschrittene können sich folgender Konstruktoren bedienen: - Key(reference=<reference>): Übergibt ein untergeordnetes Referenzobjekt - Key(serialized=<string>): Übergibt ein serialisiertes untergeordnetes Referenzobjekt - Key(<dict>): Für das Unpickling mit Key(**<dict>) identisch

Der URL-sichere String ist in Wirklichkeit eine mit base64 websicher codierte, serialisierte Referenz. Betrachten Sie ihn jedoch einfach als einen undurchsichtigen eindeutigen String.

Weitere Schlüsselwortargumente für den Konstruktor: - app=<string>: Gibt die Anwendungs-ID an - namespace=<string>: Gibt den Namespace an

Wenn eine Referenz (mit "reference", "serialized" oder "urlsafe") übergeben wird, müssen die Argument- und Namespace-Schlüsselwörter mit denjenigen übereinstimmen, die bereits in der Referenz vorhanden sind (nach einer eventuellen Decodierung). Das übergeordnete Schlüsselwort kann in keiner Weise mit einer Referenz kombiniert werden.

Schlüssel sind unveränderlich. Dies bedeutet, dass ein einmal erstelltes Schlüsselobjekt nicht mehr geändert werden kann. Durchgesetzt wird dies durch die Implementierung sowie Python.

Für den Zugriff auf den Inhalt eines Schlüssels werden folgende Methoden und Vorgänge unterstützt:

  • repr(key), str(key): Gibt eine Stringdarstellung zurück, die der kürzesten Konstruktorschreibweise ähnelt, allerdings ohne Anwendung und Namespace, sofern diese nicht vom Standardwert abweichen

  • key1 == key2, key1 != key2 – Vergleich der Gleichheit zwischen Schlüsseln.

  • hash(key): Hash-Wert, der zum Speichern von Schlüsseln in einem Wörterbuch ausreicht

  • key.pairs(): Tupel von (kind, id)-Paaren

  • key.flat(): Tupel von vereinfachten Typ- und ID-Werten, also (kind1, id1, kind2, id2, …)

  • key.app(): Anwendungs-ID

  • key.id(): String- oder Ganzzahl-ID im letzten (kind, id)-Paar oder "None", falls der Schlüssel unvollständig ist

  • key.string_id(): String-ID im letzten (kind, id)-Paar oder "None", falls der Schlüssel eine Ganzzahl-ID hat oder unvollständig ist

  • key.integer_id(): Ganzzahl-ID im letzten (kind, id)-Paar oder "None", falls der Schlüssel eine String-ID hat oder unvollständig ist

  • key.namespace(): Namespace

  • key.kind(): Kurzschreibweise für key.pairs()[-1][0]

  • key.parent(): Schlüssel, der aus allen (kind, id)-Paaren bis auf das letzte erstellt wurde

  • key.urlsafe(): Mit base64 websicher codierte, serialisierte Referenz

  • key.serialized(): Serialisierte Referenz

  • key.reference(): Referenzobjekt, wobei Aufrufer zusichert, das Objekt nicht zu verändern

Schlüssel unterstützen auch die Interaktion mit dem Datenspeicher. Diese Methoden sind die einzigen, die an irgendeiner Art von E/A-Aktivität beteiligt sind. Informationen zu Future-Objekten finden Sie im Dokument zu "ndb/tasklets.py".

  • key.get(): Gibt die Entität für den Schlüssel zurück

  • key.get_async(): Gibt ein Future-Objekt zurück, dessen Endergebnis die Entität für den Schlüssel ist

  • key.delete(): Löscht die Entität für den Schlüssel

  • key.delete_async(): Löscht die Entität für den Schlüssel asynchron

Für Schlüssel kann ein Pickling ausgeführt werden.

Das Erstellen von abgeleiteten Klassen für Schlüssel sollte vermieden werden, da dies schwer zu bewerkstelligen ist.

app()Quelle

Gibt die Anwendungs-ID zurück

delete(**ctx_options)Quelle

Löscht die Entität für diesen Schlüssel synchron

Wenn eine solche Entität nicht existiert, ist dies ein Leerbefehl.

delete_async(**ctx_options)Quelle

Plant das Löschen der Entität für diesen Schlüssel

Gibt ein Future-Objekt zurück, dessen Ergebnis zur Verfügung steht, sobald der Löschvorgang abgeschlossen ist. Wenn eine solche Entität nicht existiert, wird dennoch ein Future-Objekt zurückgegeben. In allen Fällen ist das Ergebnis des Future-Objekts "None". Es kann also nicht festgestellt werden, ob die Entität existiert hat oder nicht.

flat()Quelle

Gibt ein Tupel alternierender Typ- und ID-Werte zurück

Klassenmethode from_old_key(old_key)Quelle
get(**ctx_options)Quelle

Ruft die Entität für diesen Schlüssel synchron ab

Gibt "None" zurück, wenn eine solche Entität nicht existiert

get_async(**ctx_options)Quelle

Gibt ein Future-Objekt zurück, dessen Ergebnis die Entität für diesen Schlüssel ist.

Wenn eine solche Entität nicht existiert, wird dennoch ein Future-Objekt zurückgegeben, dessen endgültiges Rückgabeergebnis "None" ist.

id()Quelle

Gibt die String- oder Ganzzahl-ID im letzten (kind, id)-Paar zurück, sofern vorhanden

Gibt Folgendes zurück:

Eine String- oder Ganzzahl-ID oder "None", wenn der Schlüssel unvollständig ist

integer_id()Quelle

Gibt die Ganzzahl-ID im letzten (kind, id)-Paar zurück, sofern vorhanden

Gibt Folgendes zurück:

Eine Ganzzahl-ID oder "None", wenn der Schlüssel eine String-ID hat oder unvollständig ist

kind()Quelle

Gibt den Typ der referenzierten Entität zurück.

Dies ist der Typ aus dem letzten (kind, id)-Paar.

namespace()Quelle

Gib den Namespace zurück

pairs()Quelle

Gibt ein Tupel von (kind, id)-Paaren zurück

parent()Quelle

Gibt einen Schlüssel zurück, der aus allen (kind, id)-Paaren bis auf das letzte erstellt wurde.

Wenn nur ein (kind, id)-Paar vorliegt, wird "None" zurückgegeben.

reference()Quelle

Gibt das Referenzobjekt für diesen Schlüssel zurück.

Dies ist eine entity_pb.Reference-Instanz – eine Protokollpufferklasse, die von der Low-Level API für den Datenspeicher verwendet wird.

HINWEIS: Der Aufrufer sollte den Rückgabewert nicht verändern.

root()Quelle

Gibt den Stammschlüssel zurück. Dies ist entweder das Element selbst oder das höchste übergeordnete Element.

serialized()Quelle

Gibt ein serialisiertes Referenzobjekt für diesen Schlüssel zurück

string_id()Quelle

Gibt die String-ID im letzten (kind, id)-Paar zurück, sofern vorhanden

Gibt Folgendes zurück:

Eine String-ID oder "None", wenn der Schlüssel eine Ganzzahl-ID hat oder unvollständig ist

to_old_key()Quelle
urlsafe()Quelle

Gibt einen URL-sicheren String zurück, der die Referenz dieses Schlüssels codiert

Dieser String ist mit anderen APIs und Sprachen sowie mit den Strings kompatibel, die zur Darstellung von Schlüsseln in GQL und in der Admin-Konsole von App Engine verwendet werden.