Restez organisé à l'aide des collections
Enregistrez et classez les contenus selon vos préférences.
Fonctions
ndb.add_flow_exception(exc)
Permet de spécifier si une exception ne doit pas être enregistrée, mais fait simplement partie du flux normal du programme. (En temps normal, une exception génère un message d'avertissement dans les journaux de l'application.)
Arguments
exc
Classe d'exception qui ne doit pas être enregistrée dans les journaux.
Par défaut, les exceptions suivantes ne sont pas consignées :
webob.exc.HTTPException (et ses sous-classes)
ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
Supprime les entités identifiées par la séquence de clés transmise.
Renvoie une liste d'objets Future. Le résultat de chaque objet Future correspond à une instance de la classe Model ou à None si la clé est introuvable.
ndb.in_transaction()
Renvoie une valeur booléenne indiquant si une transaction est actuellement active.
Décorateur qui veille à ce qu'une fonction s'exécute en dehors d'une transaction.
Arguments :
allow_existing
La fonction s'exécute indépendamment de la transaction si elle est définie sur True (valeur par défaut) et si la fonction décorée est appelée par le code d'une transaction. Elle génère une exception si elle est définie sur False et si la fonction décorée est appelée par du code dans une transaction.
ndb.put_multi(entities, **ctx_options)
Stocke une séquence d'instances de la classe Model.
Renvoie tout élément renvoyé par le rappel.
Déclenche tout élément déclenché par le rappel ou génère une exception TransactionFailedError en cas d'échec de la transaction.
Pour transmettre des arguments à une fonction de rappel, utilisez un lambda. Exemple :
Renvoie un objet Future.
L'objet Future renvoie tout élément renvoyé par le rappel, ou déclenche tout élément déclenché par le rappel ou une exception TransactionFailedError en cas d'échec de la transaction.
Pour transmettre des arguments à une fonction de rappel, utilisez un lambda. Exemple :
Les options de contexte vous permettent d'exécuter des opérations spécifiques aux datastores avec différentes configurations. Par exemple, vous pouvez modifier la stratégie de lecture ou le délai RPC pour des requêtes individuelles.
Pour ce faire, vous pouvez transmettre des options de contexte à la quasi-totalité des opérations.
Certaines fonctions liées aux transactions utilisent des options de transaction, qui incluent des options supplémentaires par rapport à l'ensemble d'options de contexte.
Voici quelques exemples utilisant les options de contexte. Pour définir le délai RPC à 1 seconde lors de la lecture d'une entité, vous pouvez utiliser :
key.get(deadline=1)
Pour définir le délai d'expiration de Memcache à 30 secondes lors de l'écriture d'une entité, vous pouvez utiliser :
ent.put(ndb_memcache_timeout=30)
Pour supprimer un élément mis en cache et forcer son rechargement, vous pouvez utiliser :
key.delete(use_datastore=False)
Les arguments de mots clés spéciaux options et config (qui ont des significations identiques pour des raisons historiques) permettent de spécifier plusieurs options en tant qu'objet de configuration. Il peut s'agir d'un objet ndb.ContextOptions ou (pour les fonctions transactionnelles et le décorateur) d'un objet ndb.TransactionOptions.
Par exemple, key.get(options=ndb.ContextOptions(use_cache=True)) correspond à key.get(use_cache=True).
Les options définies dans un tel objet options peuvent être remplacées par des paramètres de mot clé.
Les options de contexte suivantes sont disponibles :
Option
Type
Description
deadline
float
Délai d'appel du datastore, exprimé en secondes.
(Par défaut, l'appel n'est interrompu que par le délai du gestionnaire de requêtes.)
read_policy
ndb.EVENTUAL_CONSISTENCY
Définissez ce paramètre sur ndb.EVENTUAL_CONSISTENCY si, au lieu d'attendre que le datastore termine d'appliquer les modifications à tous les résultats renvoyés, vous souhaitez obtenir plus rapidement des résultats qui ne sont pas actuels.
force_writes
bool
Spécifie si une requête d'écriture doit réussir même si l'application est en lecture seule.
(Cette option ne s'applique qu'aux périodes de lecture seule contrôlées par l'utilisateur.)
use_cache
bool
Spécifie si les entités doivent être stockées dans le cache en cours de traitement. Prend le pas sur la stratégie de mise en cache en cours de traitement pour cette opération.
use_memcache
bool
Spécifie si les entités doivent être stockées dans Memcache. Prend le pas sur la stratégie Memcache pour cette opération.
use_datastore
bool
Spécifie si les entités doivent être stockées dans Datastore. Prend le pas sur la stratégie Datastore pour cette opération.
memcache_timeout
int
Durée de vie maximale des entités dans Memcache. Prend le pas sur la stratégie de délai d'expiration Memcache pour cette opération.
max_memcache_items
int
Taille de lot maximale pour la fonctionnalité de mise en lots automatique des méthodes de contexte de Memcache.
Par exemple, avec la taille par défaut de max_memcache_items (100), jusqu'à 100 opérations de définition Memcache seront combinées en une seule opération set_multi.
Pour certaines fonctions liées aux transactions, les options de transaction suivantes sont disponibles (ainsi que les options de contexte héritées répertoriées ci-dessus) :
Option
Type
Description
xg
bool
Autorise les transactions entre groupes (XG).
False par défaut.
propagation
int
NDB fournit une compatibilité limitée pour les transactions au sein de transactions, appelées "transactions imbriquées".
Le paramètre de propagation contrôle ce qui se passe si votre code tente de démarrer une transaction imbriquée.
La stratégie de propagation pour @ndb.transactional est définie par défaut sur ALLOWED.
La stratégie de propagation pour ndb.transaction() est définie par défaut sur NESTED.
La stratégie NESTED n'est pas prise en charge par NDB. Votre code génère donc une exception BadRequestError. Dans ce cas précis, NDB définit une valeur par défaut non compatible afin que les programmeurs prennent explicitement conscience des limites des transactions imbriquées.
Le paramètre de propagation peut prendre l'une des valeurs suivantes :
ndb.TransactionOptions.NESTED
La stratégie de propagation NESTED valide toutes les modifications des transactions externes et internes lors du commit de la stratégie externe. Toutefois, si une exception est générée dans la transaction interne, toutes les modifications de cette transaction sont rejetées, tandis que la transaction externe est autorisée à éventuellement récupérer et continuer. La stratégie NESTED n'est pas compatible. Si vous utilisez cette stratégie, votre code génère une exception BadRequestError.
ndb.TransactionOptions.MANDATORY
Propage toujours une transaction existante, et renvoie une exception s'il n'y a pas de transaction existante.
Si une fonction utilisant cette stratégie génère une exception, il est probablement risqué de capturer l'exception et de valider la transaction externe, car il se peut que la fonction ait laissé la transaction externe dans un état incorrect.
ndb.TransactionOptions.ALLOWED
S'il y a une transaction existante, elle est propagée.
Si une fonction utilisant cette stratégie génère une exception, il est probablement risqué de capturer l'exception et de valider la transaction externe, car il se peut que la fonction ait laissé la transaction externe dans un état incorrect.
ndb.TransactionOptions.INDEPENDENT
Utilise toujours une nouvelle transaction en mettant en pause toute transaction existante.
Une fonction utilisant cette stratégie ne doit renvoyer aucune entité lue dans la nouvelle transaction, car ces entités ne sont pas cohérentes, en termes de transactions, avec la transaction appelante.
retries
int
Nombre de nouvelles tentatives automatiques à effectuer en cas d'échec de la transaction.
Zéro signifie essayer une fois, mais ne pas ré-essayer.
Dans certains cas, les options sont ignorées à cause de la mise en cache.
Par exemple, si vous spécifiez un délai RPC pour une opération de lecture qui est satisfaite à partir du cache contextuel, ce délai est ignoré.
En revanche, les options non reconnues entraînent le renvoi d'une erreur TypeError.
Les opérations ayant des options différentes sont regroupées suivant les options lors de l'application de la mise en lots automatique. Par exemple, si vous utilisez put_async() pour écrire certaines entités avec deadline = 5 et certaines entités sans spécifier de délai, et que toutes sont éligibles pour la mise en lots automatique, le système de mise en lots automatique effectuera deux appels RPC distincts, un pour le groupe d'entités avec deadline = 5 et un pour l'autre groupe, même si le délai RPC par défaut est également de 5.
Cela s'applique même si l'option spécifiée n'est pas pertinente pour l'opération RPC (par exemple, ndb_should_cache).
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/04 (UTC)."],[[["\u003cp\u003eThis page documents the use of legacy bundled services and APIs, which are specifically designed for first-generation runtimes in the App Engine standard environment.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003endb\u003c/code\u003e API provides functions for managing entities, including operations like fetching, deleting, and storing entities, both synchronously and asynchronously.\u003c/p\u003e\n"],["\u003cp\u003eTransactions can be managed through the \u003ccode\u003endb\u003c/code\u003e API, allowing you to run operations in a transactional context, which can be done either directly or using decorators like \u003ccode\u003e@ndb.transactional\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eContext and transaction options are available to configure datastore operations, allowing customization of settings like deadlines, caching behavior, and read policies for individual requests.\u003c/p\u003e\n"],["\u003cp\u003eSpecific exceptions, such as \u003ccode\u003ewebob.exc.HTTPException\u003c/code\u003e and \u003ccode\u003endb.Rollback\u003c/code\u003e, are not logged by default, and users can specify additional exceptions to be excluded from logging via \u003ccode\u003endb.add_flow_exception\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# NDB Functions\n\nFunctions\n---------\n\n| This page describes how to use the legacy bundled services and APIs. This API can only run in first-generation runtimes in the App Engine standard environment. If you are updating to the App Engine Python 3 runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/python-differences) to learn about your migration options for legacy bundled services.\n\nndb.add_flow_exception(exc)\n: Specify that an exception should *not* be logged, but is just part of\n normal program flow. (Normally, raising an exception writes a warning\n message to the application's logs.)\n\n **Arguments**\n\n exc\n\n : Exception class that should not be logged. By default, the following exceptions are not logged:\n\n - `webob.exc.HTTPException` (and its subclasses)\n - `ndb.Rollback`\n\nndb.delete_multi(keys, \\*\\*ctx_options)\n\n: Deletes entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\nndb.delete_multi_async(keys, \\*\\*ctx_options)\n\n: Asynchronously deletes entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects. Each future's result will be `None`.\n\nndb.get_multi(keys, \\*\\*ctx_options)\n\n: Fetches entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list. Each list item is either a\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instance or `None`\n if the key wasn't found.\n\nndb.get_multi_async(keys, \\*\\*ctx_options)\n\n: Asynchronously fetches entities identified by the passed sequence of keys. **Arguments**\n\n keys\n : Sequence of [keys](/appengine/docs/legacy/standard/python/ndb/keyclass)\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects. Each future's result is a\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instance or `None`\n if the key wasn't found.\n\nndb.in_transaction()\n: Returns a Boolean indicating whether a transaction is currently active.\n\n@ndb.non_transactional \n\n@ndb.non_transactional(allow_existing=True)\n: Decorator to ensure that a function runs *outside* a transaction.\n\n **Arguments:**\n\n allow_existing\n : If `True` (the default) and if the decorated function\n is called by code in a transaction, the function runs independent\n of the transaction. If `False` and if the decorated function\n is called by code in a transaction, it raises an exception.\n\nndb.put_multi(entities, \\*\\*ctx_options)\n: Stores a sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances.\n\n **Arguments**\n\n entities\n : Sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list with the stored [keys](/appengine/docs/legacy/standard/python/ndb/keyclass).\n\nndb.put_multi_async(entities, \\*\\*ctx_options)\n: Asynchronously stores a sequence of\n [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances.\n\n **Arguments**\n\n entities\n : Sequence of [Model](/appengine/docs/legacy/standard/python/ndb/modelclass) instances\n\n \\*\\*ctx_options\n : [Context options](#context_options)\n\n Returns a list of [Future](/appengine/docs/legacy/standard/python/ndb/futureclass)\n objects.\n Each future's result will be a stored [key](/appengine/docs/legacy/standard/python/ndb/keyclass).\n\nndb.transaction(callback, \\*\\*ctx_options)\n\n: Run a callback in a transaction. **Arguments**\n\n callback\n : Function or tasklet to be called\n\n \\*\\*ctx_options\n : [Transaction options](#context_options)\n\n Returns whatever callback returns.\n Raises whatever callback raises or a\n `TransactionFailedError` exception if the transaction fails.\n\n To pass arguments to a callback function, use a lambda. For example, \n\n ```python\n def my_callback(key, inc):\n ...\n\n transaction(lambda: my_callback(Key(...), 1))\n ```\n\nndb.transaction_async(callback, \\*\\*ctx_options)\n\n: Asynchronously run a callback in a transaction. **Arguments**\n\n callback\n : Function or tasklet to be called\n\n \\*\\*ctx_options\n : [Transaction options](#context_options)\n\n Returns a [Future](/appengine/docs/legacy/standard/python/ndb/futureclass).\n The future returns whatever callback returns, or\n raises whatever callback raises or a\n `TransactionFailedError` if the\n transaction fails.\n\n To pass arguments to a callback function, use a lambda. For example, \n\n ```python\n def my_callback(key, inc):\n ...\n\n transaction(lambda: my_callback(Key(...), 1))\n ```\n\n@ndb.transactional \n\n@ndb.transactional(\\*\\*ctx_options)\n\n: Decorator to make a function automatically run in a transaction. **Arguments:**\n\n This decorator can have [transaction options](#context_options).\n\nContext Options, Transaction Options\n------------------------------------\n\nContext options allow you to run specific datastore operations with different\nconfigurations. For example, you might want to vary the read policy\nor the RPC deadline for individual requests.\nYou can do this by passing *context options* to almost any operation.\nSome transaction-related functions take *transaction options*, which include additional options\non top of a set of context options.\n\nHere are a few examples using context options. To set the RPC deadline to 1 second when reading an entity,\nyou can use:\n\n```python\nkey.get(deadline=1)\n```\n\nTo set the memcache timeout to 30 seconds when writing an entity,\nyou can use:\n\n```python\nent.put(ndb_memcache_timeout=30)\n```\n\nTo delete an item that has been cached and force its reload, you can use:\n\n```python\nkey.delete(use_datastore=False)\n```\n\nThe special keyword arguments `options` and `config`\n(which have identical meanings for historical reasons) allow one to specify\nseveral options as a Configuration object. This can be an\n`ndb.ContextOptions` object or\n(for the transactional functions and decorator) an\n`ndb.TransactionOptions` object.\nFor example,\n`key.get(options=ndb.ContextOptions(use_cache=True))`\nis equivalent to\n`key.get(use_cache=True)`.\nThe options set in such an options object can be overridden by\nkeyword parameters.\n\nThe following **context options** are available:\n\nIn some cases, options are ignored because of caching.\nFor example, if you specify an RPC deadline for a read\noperation that is satisfied from the in-context cache,\nthe deadline is ignored.\nOn the other hand,\nunrecognized options cause `TypeError` to be raised.\n\nOperations with different options are grouped together when\nauto-batching applies. For example, if you use `put_async()`\nto write some entities with\n`deadline = 5`\nand some without specifying a deadline, and all are eligible for\nauto-batching, the auto-batcher will make two separate RPC\ncalls---one for the group of entities with\n`deadline = 5`\nand one for the other group---even though the default\nRPC deadline is also 5!\nThis applies even if the option specified is irrelevant to\nthe RPC operation (for example, `ndb_should_cache`)."]]
