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.

Datenspeicherfunktionen

Hinweis: Entwicklern von neuen Anwendungen wird dringend empfohlen, die NDB-Clientbibliothek zu verwenden. Diese bietet im Vergleich zur vorliegenden Clientbibliothek verschiedene Vorteile, z. B. das automatische Caching von Entitäten über die Memcache API. Wenn Sie derzeit die ältere DB-Clientbibliothek verwenden, finden Sie weitere Informationen im Leitfaden zur Migration von DB- zu NDB-Clientbibliotheken.

Die auf dieser Seite erläuterten Funktionen sind im Paket google.appengine.ext.db definiert.

Funktionen

allocate_ids (model, count)

Weist einen ID-Batch im Datenspeicher einer Kombination aus Datenspeicherart und übergeordnetem Element zu.

Auf diese Art zugewiesene IDs werden vom automatischen ID-Sequenzgenerator des Datenspeichers nicht verwendet und können konfliktfrei in Entitätsschlüsseln verwendet werden.

Argumente

model: Der Modellschlüssel, für den ein ID-Batch zugewiesen werden soll. Dies ist ein normaler Schlüssel. Nur das übergeordnete Element und die Art des Schlüssels sind erforderlich, um zu bestimmen, welche ID-Sequenz zu verwenden ist.
count: Die Anzahl der IDs, die zugewiesen werden sollen.

Gibt ein Tupel der ersten und letzten zugewiesenen ID zurück. Wenn Sie beispielsweise zehn IDs mit dieser Funktion zugewiesen haben, erhalten Sie eine Rückgabe im Format (1, 10), also keine vollständige Liste der erstellten IDs.

Beispiel für das Zuweisen und Verwenden von IDs:

# allocate for MyModel without an instance
handmade_key = db.Key.from_path('MyModel', 1)
first_batch = db.allocate_ids(handmade_key, 10)
first_range = range(first_batch[0], first_batch[1] + 1)

# or allocate using an existing key
model_instance = MyModel.all().get()
second_batch = db.allocate_ids(model_instance.key(), 10)
second_range = range(second_batch[0], second_batch[1] + 1)

# and then use them! woo!
my_id = second_range.pop(0)
new_key = db.Key.from_path('MyModel', my_id)
new_instance = MyModel(key=new_key)
new_instance.put()
assert new_instance.key().id() == my_id

# the Datastore will not assign ids in first_batch or second_batch
another_instance = MyModel()
another_instance.put()
assert another_instance.key().id() not in first_range
assert another_instance.key().id() not in second_range

allocate_ids_async (model, count)

Weist einen ID-Batch im Datenspeicher asynchron für eine Kombination aus Datenspeicherart und übergeordnetem Element zu.

Diese Funktion ist mit allocate_ids() identisch. Der einzige Unterschied besteht darin, dass sie ein asynchrones Objekt zurückgibt. Sie können get_result() für den Rückgabewert aufrufen, um den Aufruf zu blockieren und das Ergebnis zurückzugeben.

Argumente

model: Eine db.Model-Instanz, ein Schlüssel oder ein String als Vorlage zur Angabe der ID-Sequenz, in der die IDs zugeordnet werden sollen. Die zurückgegebenen IDs dürfen nur in Entitäten mit dem gleichen übergeordneten Element (falls vorhanden) und mit der gleichen Art wie dieser Schlüssel verwendet werden.
count: Die Anzahl der IDs, die zugewiesen werden sollen.

Gibt ein Tupel der ersten und letzten zugewiesenen ID zurück. Wenn Sie beispielsweise zehn IDs mit dieser Funktion zugewiesen haben, erhalten Sie einen Rückgabewert im Format (1, 10), jedoch keine vollständige Liste der erstellten IDs.

allocate_id_range (model, start, end, **kwargs)

Weist einen Bereich von IDs mit spezifischen Endpunkten zu. Nachdem diese IDs zugeordnet wurden, können Sie sie manuell neu erstellten Entitäten zuweisen.

Der automatische ID-Allocator des Datenspeichers weist niemals einen Schlüssel zu, der bereits zugewiesen wurde (entweder durch automatische ID-Zuweisung oder durch einen expliziten Aufruf von "allocate_ids"). Aus diesem Grund werden Entitäten im angegebenen Schlüsselbereich niemals überschrieben. Allerdings können durch das Schreiben von Entitäten mit manuell zugewiesenen Schlüsseln in diesem Bereich vorhandene Entitäten (oder neue Entitäten, die durch einen separaten Request geschrieben wurden) überschrieben werden, je nach zurückgegebenem Schlüsselbereichszustand.

Verwenden Sie diese Funktion nur, wenn Sie einen vorhandenen numerischen ID-Bereich haben, den Sie reservieren möchten (z. B. zum massenhaften Laden von Entitäten, die bereits IDs haben). Wenn es für Sie nicht relevant ist, welche IDs Sie erhalten, verwenden Sie stattdessen allocate_ids().

Argumente

model: Eine db.Model-Instanz, ein Schlüssel oder ein String als Vorlage zur Angabe der ID-Sequenz, in der die IDs zugeordnet werden sollen. Die zurückgegebenen IDs dürfen nur in Entitäten mit dem gleichen übergeordneten Element (falls vorhanden) und mit der gleichen Art wie dieser Schlüssel verwendet werden.
start: Die erste zuzuweisende ID, eine Zahl.
end: Die letzte zuzuweisende ID, eine Zahl.

Gibt einen Wert (KEY_RANGE_EMPTY, KEY_RANGE_CONTENTION oder KEY_RANGE_COLLISION) zurück. Wenn nicht KEY_RANGE_EMPTY, stellt dies ein mögliches Problem bei der Verwendung des zugewiesenen Schlüsselbereichs dar.

create_transaction_options (**kwargs)

Erstellt ein Transaktionsoptionsobjekt (Klasse TransactionOptions) zur Steuerung der Transaktionsausführung. Sie übergeben das resultierende Objekt als erstes Argument an die run_in_transaction_options()-Funktion.

Argumente

propagation

Wie vorgegangen werden soll, wenn diese Transaktionsfunktion von einer anderen Transaktion aufgerufen wird:

ALLOWED: Wenn bereits eine Transaktion läuft, wird diese weiterhin verwendet. Wenn nicht, wird eine neue Transaktion gestartet.
Hinweis: Wenn eine Funktion, die diese Richtlinie verwendet, eine Ausnahme auslöst, ist das Abfangen der Ausnahme und endgültige Speichern (Commit) der Transaktion nicht sicher. Die Funktion hat die äußere Transaktion möglicherweise in einem fehlerhaften Zustand verlassen.
MANDATORY: Setzt eine vorhandene Transaktion fort. Wenn keine Transaktion vorhanden ist, wird die Ausnahme BadRequestError ausgelöst.
Hinweis: Wenn eine Funktion, die diese Richtlinie verwendet, eine Ausnahme auslöst, ist das Abfangen der Ausnahme und endgültige Speichern (Commit) der Transaktion nicht sicher. Die Funktion hat die äußere Transaktion möglicherweise in einem fehlerhaften Zustand verlassen.
INDEPENDENT: Erstellt eine neue Transaktion und unterbricht die vorhandene Transaktion.
Hinweis: Eine Funktion mit dieser Richtlinie gibt in der Regel keine Entitäten zurück, die in der neuen Transaktion gelesen werden, da die Entitäten nicht mit der äußeren Transaktion konsistent sind.
NESTED: (Noch nicht unterstützt) Erstellt eine verschachtelte Transaktion innerhalb einer vorhandenen Transaktion.

xg

Wenn True, werden gruppenübergreifende Transaktionen {XG} zugelassen. Löst die Ausnahme BadArgumentError aus, wenn ein anderer Wert als ein boolescher Wert festgelegt wird.

retries

Anzahl der Wiederholungen, die bei einem fehlgeschlagenen Commit der Transaktion versucht werden können.

deadline

Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Der Wert kann nicht höher als der Standardwert (60 Sekunden) sein. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise hilfreich sein, wenn eine schnellere Antwort an den Nutzer gesendet, der Vorgang wiederholt, ein anderer Vorgang ausgeführt oder der Vorgang einer Aufgabenwarteschlange hinzugefügt werden soll.

Im folgenden Beispiel werden die Optionen für eine nachfolgende gruppenübergreifende Transaktion (XG) erstellt:

from google.appengine.ext import db

xg_on = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_on, my_txn)

delete (models, deadline=60)

Löscht mindestens eine Modellinstanz aus dem Datenspeicher.

Argumente

models: Eine Modellinstanz, ein Entitätsschlüssel oder eine Liste (bzw. ein anderer iterierbarer Wert) der Modellinstanzen oder Entitätsschlüssel, die gelöscht werden sollen.
deadline: Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Der Wert kann nicht höher als der Standardwert (60 Sekunden) sein. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise hilfreich sein, wenn eine schnellere Antwort an den Nutzer gesendet, der Vorgang wiederholt, ein anderer Vorgang ausgeführt oder der Vorgang einer Aufgabenwarteschlange hinzugefügt werden soll.

Wie bei put() können mehrere Schlüssel angegeben werden, die sich in mehr als einer Entitätengruppe befinden können.

Wenn während des Vorgangs ein Fehler auftritt, wird immer eine Ausnahme ausgegeben, auch wenn einige Entitäten tatsächlich gelöscht wurden. Wenn der Aufruf ohne Ausnahme zurückgegeben wird, wurden alle Entitäten erfolgreich gelöscht.

Achtung: Das Löschen mehrerer Entitäten in einem einzigen Vorgang garantiert nicht, dass der Löschvorgang atomar erfolgt, außer der Vorgang wird innerhalb einer Transaktion ausgeführt. Bei anderen Prozessen, die den Datenspeicher abfragen, werden möglicherweise inkonsistente Ergebnisse ausgegeben, selbst wenn die Abfrage mit Strong Consistency ausgeführt wird.

delete_async (models, deadline=60)

Löscht mindestens eine Modellinstanz asynchron aus dem Datenspeicher.

Diese Funktion ist mit delete() identisch. Der einzige Unterschied besteht darin, dass sie ein asynchrones Objekt zurückgibt. Sie können get_result() für den Rückgabewert aufrufen, um den Aufruf zu blockieren.

Argumente

models: Eine Modellinstanz, ein Entitätsschlüssel oder eine Liste (bzw. ein anderer iterierbarer Wert) der Modellinstanzen oder Entitätsschlüssel, die gelöscht werden sollen.
deadline: Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Der Wert kann nicht höher als der Standardwert (60 Sekunden) sein. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise hilfreich sein, wenn eine schnellere Antwort an den Nutzer gesendet, der Vorgang wiederholt, ein anderer Vorgang ausgeführt oder der Vorgang einer Aufgabenwarteschlange hinzugefügt werden soll.

Wie bei put() können mehrere Schlüssel angegeben werden, die sich in mehr als einer Entitätengruppe befinden können.

Diese Funktion gibt ein Objekt zurück, mit dem Sie das Ergebnis des Aufrufs blockieren können.

get (keys, read_policy=STRONG_CONSISTENCY, deadline=STRONG_CONSISTENCY)

Ruft die spezifische(n) Modellinstanz(en) mit den angegebenen Schlüsseln aus dem Datenspeicher ab.

Argumente

keys

Schlüssel der abzurufenden Entität, eine Stringdarstellung des Schlüssels oder eine Liste von Schlüsseln oder ihrer Stringdarstellungen

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY: Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt.
EVENTUAL_CONSISTENCY: Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

Wenn keys aus einem einzelnen Schlüssel oder dessen Stringdarstellung besteht, gibt diese Funktion die mit dem Schlüssel verknüpfte Modellinstanz zurück, sofern der Schlüssel im Datenspeicher vorhanden ist. Andernfalls wird None zurückgegeben. Wenn keys eine Liste ist, wird die entsprechende Liste der Modellinstanzen zurückgegeben. Schlüssel, für die keine Entität vorhanden ist, erhalten den Wert None.

Siehe auch Model.get()

get_async (keys, read_policy=STRONG_CONSISTENCY, deadline=STRONG_CONSISTENCY)

Ruft asynchron die angegebenen Modellinstanzen aus dem Datenspeicher ab.

Diese Funktion ist mit get() identisch. Der einzige Unterschied besteht darin, dass sie ein asynchrones Objekt zurückgibt. Sie können get_result() für den Rückgabewert aufrufen, um den Aufruf zu blockieren und die Ergebnisse abzurufen.

Argumente

keys

Schlüssel der abzurufenden Entität, eine Stringdarstellung des Schlüssels oder eine Liste von Schlüsseln oder ihrer Stringdarstellungen

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY: Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt.
EVENTUAL_CONSISTENCY: Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

Siehe auch Model.get()

get_indexes ()

Gibt eine Liste der zusammengesetzten Indexe zurück, die zur aufrufenden Anwendung gehören.

Das folgende Beispiel veranschaulicht, wie Indexe abgerufen und verwendet werden:

def get_index_state_as_string(index_state):
  return {db.Index.BUILDING:'BUILDING', db.Index.SERVING:'SERVING',
          db.Index.DELETING:'DELETING', db.Index.ERROR:'ERROR'}[index_state]

def get_sort_direction_as_string(sort_direction):
  return {db.Index.ASCENDING:'ASCENDING',
          db.Index.DESCENDING:'DESCENDING'}[sort_direction]


def dump_indexes():
  for index, state in db.get_indexes():
    print "Kind: %s" % index.kind()
    print "State: %s" % get_index_state_as_string(state)
    print "Is ancestor: %s" % index.has_ancestor()
    for property_name, sort_direction in index.properties():
      print "  %s:%s" % (property_name,
                         get_sort_direction_as_string(sort_direction))

get_indexes_async ()

Gibt asynchron eine Liste zusammengesetzter Indexe zurück, die zur aufrufenden Anwendung gehören.

is_in_transaction ()

Gibt einen booleschen Wert zurück, der angibt, ob der aktuelle Bereich in der Transaktion ausgeführt wird.

model_to_protobuf (model_instance)

Erstellt die Protokollpufferserialisierung einer Model-Instanz. Bei einem Protokollpuffer handelt es sich um das Serialisierungsformat von Google, das bei Remoteprozeduraufrufen verwendet wird. Es kann beim Serialisieren von Datenspeicherobjekten zum Zweck der Sicherung oder Wiederherstellung nützlich sein.

Achtung: Diese Funktion verwendet ein anderes (älteres) Format für Protokollpuffer als das Open-Source-Protokollpufferformat und ist nicht mit der Open-Source-Implementierung kompatibel.

Argument

model_instance: Die Instanz der Klasse Model (oder einer abgeleiteten Klasse), die serialisiert werden soll.

Gibt die Protokollpufferserialisierung des Objekts als Bytestring zurück.

model_from_protobuf (pb)

Erstellt eine Model-Instanz basierend auf einer Protokollpufferserialisierung. Weitere Informationen finden Sie unter model_to_protobuf().

Argument

pb: Die Protokollpufferserialisierung gemäß der Rückgabe durch model_to_protobuf().

Gibt ein Objekt der entsprechenden Klasse "kind" zurück. Wenn die Klasse "kind" nicht vorhanden ist, wird die Ausnahme KindError ausgelöst. Wenn das Objekt gemäß dem Modell ungültig ist, wird die Ausnahme BadValueError ausgelöst.

Sie können das neue Objekt wie jede andere Model-Instanz im Datenspeicher speichern, z. B. durch Aufrufen der put()-Methode. Das Objekt behält den Schlüssel bei, der beim Erstellen des Protokollpuffers vorhanden war. Durch Speichern des deserialisierten Objekts wird das vorhandene Objekt überschrieben, wenn im Datenspeicher bereits ein Objekt mit diesem Schlüssel vorhanden ist.

Achtung: Wenn der Schlüssel des Objekts eine vom System zugewiesene ID verwendet und diese ID nicht bereits für den angegebenen Pfad und die angegebene Art zugeordnet wurde, ist das Speichern zwar erfolgreich, die ID ist jedoch nicht reserviert. Diese ID kann einem Objekt zugeordnet werden, das später erstellt wird. Dabei wird das ältere Objekt überschrieben. Stellen Sie zur Sicherheit Objekte nur in derselben Anwendung wieder her, in der sie bei der Serialisierung vorhanden waren.

model_is_projection (model_instance)

Gibt True zurück, wenn die angegebene Abfrage (model_instance) eine Projektionsabfrage anstelle einer Abfrage für eine vollständige Entität ist.

Argument

model_instance: Die Abfrage, die Sie überprüfen, um zu bestimmen, ob es sich um eine Projektionsabfrage handelt.

Gibt True zurück, wenn die Abfrage eine Projektionsabfrage ist. Andernfalls wird False zurückgegeben.

put (models, deadline=60)

Schreibt mindestens eine Modellinstanz in den Datenspeicher.

Argumente

models: Eine zu speichernde Modellinstanz oder Liste mit Modellinstanzen.
deadline: Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Der Wert kann nicht höher als der Standardwert (60 Sekunden) sein. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise hilfreich sein, wenn eine schnellere Antwort an den Nutzer gesendet, der Vorgang wiederholt, ein anderer Vorgang ausgeführt oder der Vorgang einer Aufgabenwarteschlange hinzugefügt werden soll.

Wenn mehrere Modellinstanzen angegeben sind, können diese in mehreren Entitätengruppen vorliegen.

Wenn während des Vorgangs ein Fehler auftritt, wird immer eine Ausnahme ausgegeben, auch wenn einige der Entitäten tatsächlich geschrieben wurden. Wenn der Aufruf ohne Ausnahme zurückgegeben wird, wurden alle Entitäten erfolgreich geschrieben.

Wenn models aus einer einzelnen Modellinstanz besteht, gibt diese Funktion das entsprechende Schlüsselobjekt zurück. Wenn models eine Liste ist, ist der Rückgabewert eine Liste der entsprechenden Schlüsselobjekte.

Achtung: Das Schreiben mehrerer Entitäten in einem einzigen Vorgang garantiert nicht, dass der Schreibvorgang atomar erfolgt, außer der Vorgang wird innerhalb einer Transaktion ausgeführt. Bei anderen Prozessen, die den Datenspeicher abfragen, werden möglicherweise inkonsistente Ergebnisse ausgegeben, selbst wenn die Abfrage mit Strong Consistency ausgeführt wird.

put_async (models, deadline=60)

Schreibt mindestens eine Modellinstanz in den Datenspeicher.

Diese Funktion ist mit put() identisch. Der einzige Unterschied besteht darin, dass sie ein asynchrones Objekt zurückgibt. Sie können get_result() für den Rückgabewert aufrufen, um den Aufruf zu blockieren und die Ergebnisse abzurufen.

Argumente

models: Eine zu speichernde Modellinstanz oder Liste mit Modellinstanzen.
deadline: Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Der Wert kann nicht höher als der Standardwert (60 Sekunden) sein. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise hilfreich sein, wenn eine schnellere Antwort an den Nutzer gesendet, der Vorgang wiederholt, ein anderer Vorgang ausgeführt oder der Vorgang einer Aufgabenwarteschlange hinzugefügt werden soll.

Wenn mehrere Modellinstanzen angegeben sind, können diese in mehreren Entitätengruppen vorliegen.

Diese Funktion gibt ein asynchrones Objekt zurück, für das get_result() aufgerufen werden kann. Die zurückgegebenen Ergebnisse sind mit jenen für put() identisch.

query_descendants (model_instance)

Gibt eine Abfrage für alle Nachfolgerelemente einer Modellinstanz zurück.

Argument

model_instance: Die Modellinstanz, deren Nachfolgerelemente Sie finden möchten.

run_in_transaction (function, *args, **kwargs)

Führt eine Funktion aus, die Aktualisierungen des Datenspeichers in einer einzigen Transaktion enthält. Wenn während der Transaktion ein Code eine Ausnahme auslöst, werden alle in der Transaktion vorgenommenen Aktualisierungen rückgängig gemacht. Alternativ können Sie den Decorator @db.transactional() verwenden.

Argumente

Funktion: Auszuführende Funktion.
args: Positionsargumente, die an die Funktion übergeben werden sollen.
kwargs: Keyword-Argumente, die an die Funktion übergeben werden sollen.

Wenn die Funktion einen Wert zurückgibt, gibt run_in_transaction() den Wert an den Aufrufer zurück.

Die Transaktion wird zurückgesetzt, wenn die Funktion eine Ausnahme ausgibt. Wenn es sich dabei um die Ausnahme Rollback handelt, wird sie nicht noch einmal ausgegeben. Jede andere Ausnahme wird wiederholt an das aufrufende Element ausgegeben.

Für Transaktionen werden im Datenspeicher optimistische Sperren und Wiederholungen verwendet. Wenn die von der Funktion vorbereitete Transaktion nicht mit Commit bestätigt werden kann, ruft run_in_transaction() die Funktion noch einmal auf und wiederholt die Transaktion bis zu dreimal. Wenn Sie eine andere Anzahl von Wiederholungen möchten, verwenden Sie run_in_transaction_custom_retries(). Da die Transaktionsfunktion bei einer einzelnen Transaktion mehrmals aufgerufen werden kann, sollte es bei der Funktion nicht zu Nebenwirkungen kommen, was auch Änderungen an Argumenten einschließt.

Wenn die Transaktion nicht mit Commit bestätigt werden kann, z. B. aufgrund einer Vielzahl von Konflikten, wird die Ausnahme TransactionFailedError ausgelöst.

from google.appengine.ext import db

class Counter(db.Model):
  name = db.StringProperty()
  count = db.IntegerProperty(default=0)

def decrement(key, amount=1):
  counter = db.get(key)
  counter.count -= amount
  if counter.count < 0:        # Don't let counter go negative
    raise db.Rollback()
  db.put(counter)

q = db.GqlQuery("SELECT * FROM Counter WHERE name = :1", "foo")
counter = q.get()
db.run_in_transaction(decrement, counter.key(), amount=5)

run_in_transaction_custom_retries (retries, function, *args, **kwargs)

Führt eine Funktion aus, die Aktualisierungen des Datenspeichers in einer einzigen Transaktion enthält. Wenn die Transaktion aufgrund eines Konflikts fehlschlägt, findet eine bestimmte Anzahl von Wiederholungen statt. Wenn während der Transaktion ein Code eine Ausnahme auslöst, werden alle in der Transaktion vorgenommenen Aktualisierungen rückgängig gemacht.

Abgesehen von der Möglichkeit, die Anzahl der Wiederholungen anzugeben, verhält sich diese Funktion wie run_in_transaction().

Argumente

retries: Maximale Anzahl der Versuche, die Funktion im Fall eines Konflikts innerhalb der Entitätengruppe aufzurufen (mehrere Nutzer versuchen gleichzeitig, die Gruppe zu ändern).
Funktion: Auszuführende Funktion.
args: Positionsargumente, die an die Funktion übergeben werden sollen.
kwargs: Keyword-Argumente, die an die Funktion übergeben werden sollen.

run_in_transaction_options (options, function, *args, **kwargs)

Führt eine Funktion aus, die Aktualisierungen des Datenspeichers in einer einzigen Transaktion enthält. Dazu werden die Optionen verwendet, die in einem Objekt für Transaktionsoptionen angegeben sind. Wenn während der Transaktion ein Code eine Ausnahme auslöst, werden alle in der Transaktion vorgenommenen Datenspeicheraktualisierungen rückgängig gemacht.

Für gruppenübergreifende Transaktionen (XG) muss für den Parameter xg im Objekt der Transaktionsoptionen der Wert True festgelegt sein.

Argumente

options: Das Objekt der Transaktionsoptionen mit den Einstellungen, die von dieser Transaktion verwendet werden. Wenn Sie XG-Transaktionen ermöglichen möchten, muss der Parameter xg auf True gesetzt sein.
Funktion: Auszuführende Funktion.
args: Positionsargumente, die an die Funktion übergeben werden sollen.
kwargs: Keyword-Argumente, die an die Funktion übergeben werden sollen.

Wenn die Funktion einen Wert zurückgibt, gibt run_in_transaction_options() den Wert an den Aufrufer zurück.

Für Transaktionen werden im Datenspeicher optimistische Sperren und Wiederholungen verwendet. Wenn die Transaktion, die von der Funktion vorbereitet wurde, nicht mit Commit bestätigt werden kann, wird die Funktion durch run_in_transaction_options() noch einmal aufgerufen. Dabei wird die Transaktion bis zu dreimal wiederholt. Da die Transaktionsfunktion bei einer einzelnen Transaktion mehrmals aufgerufen werden kann, sollte es bei der Funktion nicht zu Nebenwirkungen kommen, was auch Änderungen an Argumenten einschließt.

Wenn die Transaktion nicht mit Commit bestätigt werden kann, z. B. aufgrund einer Vielzahl von Konflikten, wird die Ausnahme TransactionFailedError ausgelöst.

Im folgenden Beispiel wird veranschaulicht, wie Sie mit dieser Funktion eine gruppenübergreifende Transaktion ausführen können:

from google.appengine.ext import db

xg_options = db.create_transaction_options(xg=True)

def my_txn():
  x = MyModel(a=3)
  x.put()
  y = MyModel(a=7)
  y.put()

db.run_in_transaction_options(xg_options, my_txn)

to_dict (model_instance, model_instance=None)

Erstellt eine Wörterbuchdarstellung einer Modellinstanz und gibt diese zurück.

Argumente

model_instance: Zu kopierende Modellinstanz.
dictionary: Das Wörterbuch, in das die Daten des Modells eingefügt werden sollen, sofern vorhanden. Werte im Wörterbuch werden von Modellwerten überschrieben. Wörterbucheinträge, die nicht den Feldern in der Modellinstanz entsprechen, bleiben erhalten.

Decorators

@db.transactional (propagation=ALLOWED, xg=False, retries=3, deadline=60)

Ermöglicht die Ausführung einer Funktion in einer db-Transaktion. Auf diese Weise können Sie func() anstelle von run_in_transaction(func) aufrufen.

Argumente

propagation

Wie vorgegangen werden soll, wenn diese Transaktionsfunktion von einer anderen Transaktion aufgerufen wird:

ALLOWED: Wenn bereits eine Transaktion läuft, wird diese weiterhin verwendet. Wenn nicht, wird eine neue Transaktion gestartet.
Hinweis: Wenn eine Funktion, die diese Richtlinie verwendet, eine Ausnahme auslöst, ist das Abfangen der Ausnahme und endgültige Speichern (Commit) der Transaktion nicht sicher. Die Funktion hat die äußere Transaktion möglicherweise in einem fehlerhaften Zustand verlassen.
MANDATORY: Setzt eine vorhandene Transaktion fort. Wenn keine Transaktion vorhanden ist, wird die Ausnahme BadRequestError ausgelöst.
Hinweis: Wenn eine Funktion, die diese Richtlinie verwendet, eine Ausnahme auslöst, ist das Abfangen der Ausnahme und endgültige Speichern (Commit) der Transaktion nicht sicher. Die Funktion hat die äußere Transaktion möglicherweise in einem fehlerhaften Zustand verlassen.
INDEPENDENT: Erstellt eine neue Transaktion und unterbricht die vorhandene Transaktion.
Hinweis: Eine Funktion mit dieser Richtlinie gibt in der Regel keine Entitäten zurück, die in der neuen Transaktion gelesen werden, da die Entitäten nicht mit der äußeren Transaktion konsistent sind.
NESTED: (Noch nicht unterstützt) Erstellt eine verschachtelte Transaktion innerhalb einer vorhandenen Transaktion.

xg

Wenn True, werden gruppenübergreifende Transaktionen {XG} zugelassen. Löst die Ausnahme BadArgumentError aus, wenn ein anderer Wert als ein boolescher Wert festgelegt wird.

retries

Anzahl der Wiederholungen, die bei einem fehlgeschlagenen Commit der Transaktion versucht werden können.

deadline

@db.non_transactional (allow_existing=True)

Sorgt dafür, dass eine Funktion außerhalb einer db-Transaktion ausgeführt wird, selbst wenn sie innerhalb einer Transaktion aufgerufen wird.

Argument

allow_existing: Wenn True, kann die Funktion über eine vorhandene Transaktion aufgerufen werden. Wenn False, wird stattdessen die Ausnahme BadRequestError ausgelöst.