Hinweis: Python 2.7 hat am 31. Januar 2024 das Ende des Supports erreicht. Ihre vorhandenen Python 2.7-Anwendungen werden weiterhin ausgeführt und erhalten Traffic. App Engine kann die erneute Bereitstellung von Anwendungen, die Laufzeiten verwenden, jedoch nach dem Enddatum des Supports blockieren. Wir empfehlen die Migration zur neuesten unterstützten Version von Python.

NDB-Funktionen

Functions

ndb.add_flow_exception(exc)

Gibt an, dass eine Ausnahme nicht protokolliert werden soll, sondern einfach Teil des normalen Programmablaufs ist. (Normalerweise wird beim Auslösen einer Ausnahme eine Warnmeldung in die Logs der Anwendung geschrieben.)

Argumente

exc

Ausnahmeklasse, die nicht protokolliert werden soll.

Standardmäßig werden die folgenden Ausnahmen nicht protokolliert:

webob.exc.HTTPException (und abgeleitete Klassen)
ndb.Rollback

ndb.delete_multi(keys, **ctx_options)

Löscht Entitäten, die durch die übergebene Schlüsselsequenz identifiziert wurden.

Argumente

keys: Reihenfolge der keys
**ctx_options: Kontextoptionen

ndb.delete_multi_async(keys, **ctx_options)

Löscht asynchron Entitäten, die durch die übergebene Schlüsselsequenz identifiziert wurden.

Argumente

keys: Reihenfolge der keys
**ctx_options: Kontextoptionen

Gibt eine Liste von Future-Objekten zurück. Alle Future-Objekte liefern als Ergebnis None.

ndb.get_multi(keys, **ctx_options)

Ruft Entitäten ab, die durch die übergebene Schlüsselsequenz identifiziert wurden.

Argumente

keys: Reihenfolge der keys
**ctx_options: Kontextoptionen

Liefert eine Liste. Jedes Listenelement ist entweder eine Modellinstanz oder None, wenn der Schlüssel nicht gefunden wurde.

ndb.get_multi_async(keys, **ctx_options)

Ruft asynchron Entitäten ab, die durch die übergebene Schlüsselsequenz identifiziert wurden.

Argumente

keys: Reihenfolge der keys
**ctx_options: Kontextoptionen

Gibt eine Liste von Future-Objekten zurück. Alle Future-Objekte liefern als Ergebnis eine Modellinstanz oder None, wenn der Schlüssel nicht gefunden wurde.

ndb.in_transaction()

Liefert einen booleschen Wert, der angibt, ob eine Transaktion gerade aktiv ist.

@ndb.non_transactional @ndb.non_transactional(allow_existing=True)

Decorator, der dafür sorgt, dass eine Funktion außerhalb einer Transaktion ausgeführt wird.

Argumente:

allow_existing: Die Funktion wird unabhängig von der Transaktion ausgeführt, wenn True (der Standardwert) eingestellt ist und die dekorierte Funktion in einer Transaktion durch Code aufgerufen wird. Eine Ausnahme wird ausgelöst, wenn False und die dekorierte Funktion in einer Transaktion durch Code aufgerufen wird.

ndb.put_multi(entities, **ctx_options)

Speichert eine Abfolge von Modellinstanzen.

Argumente

Entitäten: Sequenz von Modellinstanzen
**ctx_options: Kontextoptionen

Liefert eine Liste mit den gespeicherten keys.

ndb.put_multi_async(entities, **ctx_options)

Speichert asynchron eine Sequenz von Modellinstanzen.

Argumente

Entitäten: Sequenz von Modellinstanzen
**ctx_options: Kontextoptionen

Gibt eine Liste von Future-Objekten zurück. Alle Future-Objekte liefern als Ergebnis einen gespeicherten key.

ndb.transaction(callback, **ctx_options)

Führt einen Callback in einer Transaktion aus.

Argumente

callback: Funktion oder Tasklet, die/das aufgerufen werden soll
**ctx_options: Transaktionsoptionen

Gibt zurück, was immer der Callback zurückgibt. Löst aus, was immer der Callback auslöst, oder eine TransactionFailedError-Ausnahme, wenn die Transaktion fehlschlägt.

Verwenden Sie zur Übergabe von Argumenten an eine Callback-Funktion ein Lambda. Beispiel:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))

ndb.transaction_async(callback, **ctx_options)

Führt einen Callback in einer Transaktion asynchron aus.

Argumente

callback: Funktion oder Tasklet, die/das aufgerufen werden soll
**ctx_options: Transaktionsoptionen

Gibt Future zurück. Future gibt zurück, was immer der Callback zurückgibt, oder löst aus, was immer der Callback auslöst – oder TransactionFailedError, wenn die Transaktion fehlschlägt.

Verwenden Sie zur Übergabe von Argumenten an eine Callback-Funktion ein Lambda. Beispiel:

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))

@ndb.transactional
@ndb.transactional(**ctx_options)

Decorator, der dafür sorgt, dass eine Funktion in einer Transaktion automatisch ausgeführt wird.

Argumente:

Dieser Decorator kann Transaktionsoptionen aufweisen.

Kontextoptionen, Transaktionsoptionen

Mit Kontextoptionen können Sie bestimmte Datenspeichervorgänge mit unterschiedlichen Konfigurationen ausführen. Beispielsweise möchten Sie vielleicht die Leserichtlinie oder das RPC-Zeitlimit für einzelne Requests variieren. Übergeben Sie dazu Kontextoptionen an fast alle Vorgänge. Einige transaktionsbezogene Funktionen verwenden Transaktionsoptionen, die neben einer Reihe von Kontextoptionen zusätzliche Optionen enthalten.

Hier einige Beispiele, die Kontextoptionen verwenden. Sie können Folgendes verwenden, um das RPC-Zeitlimit beim Lesen einer Entität auf 1 Sekunde festzulegen:

key.get(deadline=1)

Sie können Folgendes verwenden, um das Memcache-Zeitlimit beim Schreiben einer Entität auf 30 Sekunden festzulegen:

ent.put(ndb_memcache_timeout=30)

Sie können Folgendes verwenden, um ein Element zu löschen, das zwischengespeichert wurde, und sein erneutes Laden zu erzwingen:

key.delete(use_datastore=False)

Die speziellen Schlüsselwortargumente options und config (die aus historischen Gründen identische Bedeutungen haben) erlauben es, mehrere Optionen als ein Konfigurationsobjekt anzugeben. Dies kann ein ndb.ContextOptions-Objekt oder (für die transaktionalen Funktionen und den Decorator) ein ndb.TransactionOptions-Objekt sein. key.get(options=ndb.ContextOptions(use_cache=True)) entspricht beispielsweise key.get(use_cache=True). Die in einem solchen Optionsobjekt festgelegten Optionen können durch Schlüsselwortparameter überschrieben werden.

Folgende Kontextoptionen sind verfügbar:

Option	Typ	Beschreibung
`deadline`	`float`	Datenspeicher-Aufrufzeitlimit, angegeben in Sekunden. (Standardmäßig wird der Aufruf nur durch das Request-Handler-Zeitlimit unterbrochen.)
`read_policy`	`ndb.EVENTUAL_CONSISTENCY`	Setzen Sie diesen Wert auf `ndb.EVENTUAL_CONSISTENCY`, wenn Sie lieber schneller Ergebnisse erhalten möchten, die möglicherweise nicht aktuell sind, anstatt zu warten, bis der Datenspeicher mit dem Anwenden der Änderungen auf alle gelieferten Ergebnisse fertig ist.
`force_writes`	`bool`	Gibt an, ob ein Schreib-Request erfolgreich sein soll, auch wenn die Anwendung schreibgeschützt ist. (Gilt nur für vom Nutzer gesteuerte schreibgeschützte Zeiträume.)
`use_cache`	`bool`	Gibt an, ob Entitäten im Prozesscache gespeichert werden sollen; überschreibt die Prozesscacherichtlinie für diesen Vorgang.
`use_memcache`	`bool`	Gibt an, ob Entitäten in Memcache gespeichert werden sollen; überschreibt die Memcache-Richtlinie für diesen Vorgang.
`use_datastore`	`bool`	Gibt an, ob Entitäten im Datenspeicher gespeichert werden sollen; überschreibt die Datenspeicherrichtlinie für diesen Vorgang.
`memcache_timeout`	`int`	Maximale Lebensdauer von Entitäten in Memcache; überschreibt die Richtlinie für das Memcache-Zeitlimit für diesen Vorgang.
`max_memcache_items`	`int`	Maximale Batchgröße für die Funktion zur automatischen Batchverarbeitung der Context-Memcache-Methoden. Bei der Standardgröße von `max_memcache_items` (100) werden beispielsweise bis zu 100 Memcache-Vorgänge in einem einzigen `set_multi`-Vorgang kombiniert.
Für einige transaktionsbezogene Funktionen stehen die folgenden Transaktionsoptionen zur Verfügung (zusammen mit den oben genannten übernommenen Kontextoptionen):
Option	Typ	Beschreibung
`xg`	`bool`	Lässt gruppenübergreifende (`XG`) Transaktionen zu. `False` standardmäßig.
`propagation`	`int`	NDB bietet eingeschränkte Unterstützung für Transaktionen innerhalb von Transaktionen, die als "verschachtelte Transaktionen" bezeichnet werden. Der Verteilungsparameter steuert, was passiert, wenn der Code versucht, eine verschachtelte Transaktion zu starten. Die Verteilungsrichtlinie für `@ndb.transactional` ist standardmäßig `ALLOWED`. Die Verteilungsrichtlinie für `ndb.transaction()` ist standardmäßig `NESTED`. Die `NESTED`-Richtlinie wird von NDB nicht unterstützt, daher löst Ihr Code eine `BadRequestError`-Ausnahme aus. NDB legt in diesem Fall einen nicht unterstützten Standardwert fest, sodass Programmierer explizit auf die Beschränkungen verschachtelter Transaktionen hingewiesen werden. Der Verteilungsparameter kann einen der folgenden Werte haben: `ndb.TransactionOptions.NESTED` Die `NESTED`-Verteilungsrichtlinie führt für alle Änderungen an den äußeren und inneren Transaktionen zusammen das Commit durch, wenn das Commit der äußeren Richtlinie erfolgt. Wenn jedoch eine Ausnahme in der inneren Transaktion ausgelöst wird, werden alle dort vorgenommenen Änderungen verworfen. Die äußere Transaktion kann jedoch optional wiederhergestellt und fortgesetzt werden. Die `NESTED`-Richtlinie wird nicht unterstützt. Wenn Sie diese Richtlinie verwenden, löst Ihr Code eine `BadRequestError`-Ausnahme aus. `ndb.TransactionOptions.MANDATORY` Eine vorhandene Transaktion wird immer verteilt; wenn keine Transaktion vorhanden ist, wird eine Ausnahme ausgelöst. Wenn eine Funktion, die diese Richtlinie verwendet, eine Ausnahme auslöst, empfiehlt es sich wahrscheinlich nicht, die Ausnahme abzufangen und das Commit für die äußere Transaktion durchzuführen. Die Funktion hat die äußere Transaktion möglicherweise in einem fehlerhaften Zustand zurückgelassen. `ndb.TransactionOptions.ALLOWED` Wenn es eine vorhandene Transaktion gibt, wird sie verteilt. Wenn eine Funktion, die diese Richtlinie verwendet, eine Ausnahme auslöst, empfiehlt es sich wahrscheinlich nicht, die Ausnahme abzufangen und das Commit für die äußere Transaktion durchzuführen. Die Funktion hat die äußere Transaktion möglicherweise in einem fehlerhaften Zustand zurückgelassen. `ndb.TransactionOptions.INDEPENDENT` Es wird immer eine neue Transaktion verwendet und alle bestehenden Transaktionen werden "angehalten". Eine Funktion, die diese Richtlinie nutzt, gibt in der Regel keine Entitäten zurück, die in der neuen Transaktion gelesen werden, da die Entitäten mit der Transaktion des Aufrufers transaktional nicht konsistent sind.
`retries`	`int`	Gibt an, wie häufig Transaktionen nach einem Fehlschlagen automatisch wiederholt werden sollen. Null bedeutet einen Versuch, aber keine Wiederholung.

In manchen Fällen werden Optionen aufgrund von Caching ignoriert. Wenn Sie beispielsweise ein RPC-Zeitlimit für einen Lesevorgang angeben, der aus dem Kontextcache erfüllt wird, wird das Zeitlimit ignoriert. Andererseits lösen nicht erkannte Optionen TypeError aus.

Vorgänge mit verschiedenen Optionen werden zusammen gruppiert, wenn automatische Batchverarbeitung gilt. Wenn Sie beispielsweise put_async() verwenden, um einige Entitäten mit deadline = 5 und einige ohne Angabe eines Zeitlimits zu schreiben, und alle für automatische Batchverarbeitung geeignet sind, führt die automatische Batchverarbeitung zwei separate RPC-Aufrufe aus – einen für die Gruppe der Entitäten mit deadline = 5 und einen für die andere Gruppe – obwohl das Standard-RPC-Zeitlimit ebenfalls 5 ist! Dies gilt auch dann, wenn die angegebene Option für den RPC-Vorgang irrelevant ist (z. B. ndb_should_cache).