Python 2.7 ha raggiunto la fine del supporto
e verrà ritirato
il 31 gennaio 2026. Dopo il ritiro, non potrai eseguire il deployment di applicazioni Python 2.7, anche se la tua organizzazione ha utilizzato in precedenza un criterio dell'organizzazione per riattivare i deployment di runtime legacy. Le tue applicazioni Python 2.7 esistenti continueranno a essere eseguite e a ricevere traffico dopo la
data di ritiro. Ti consigliamo di eseguire la migrazione all'ultima versione supportata di Python.
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Funzioni
ndb.add_flow_exception(exc)
Specifica che un'eccezione non deve essere registrata, ma fa parte del normale flusso del programma. In genere, l'attivazione di un'eccezione scrive un messaggio di avviso
nei log dell'applicazione.
Argomenti
exc
Classe di eccezione che non deve essere registrata.
Per impostazione predefinita, le seguenti eccezioni non vengono registrate:
webob.exc.HTTPException (e le relative sottoclassi)
ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
Elimina le entità identificate dalla sequenza di chiavi passata.
Decoratore per garantire che una funzione venga eseguita al di fuori di una transazione.
Argomenti:
allow_existing
Se True (il valore predefinito) e se la funzione decorata viene chiamata dal codice in una transazione, la funzione viene eseguita indipendentemente dalla transazione. Se False e se la funzione decorata viene chiamata dal codice in una transazione, viene sollevata un'eccezione.
Restituisce ciò che restituisce la funzione di callback.
Genera qualsiasi callback o un'eccezione TransactionFailedError se la transazione non va a buon fine.
Per passare gli argomenti a una funzione di callback, utilizza una lambda. Ad esempio,
Restituisce un Future.
Il futuro restituisce ciò che restituisce il callback oppure attiva ciò che attiva il callback o un TransactionFailedError se la transazione non va a buon fine.
Per passare gli argomenti a una funzione di callback, utilizza una lambda. Ad esempio,
Le opzioni di contesto ti consentono di eseguire operazioni specifiche del datastore con configurazioni diverse. Ad esempio, potresti voler variare il criterio di lettura
o la scadenza RPC per le singole richieste.
Puoi farlo passando opzioni di contesto a quasi tutte le operazioni.
Alcune funzioni relative alle transazioni accettano opzioni di transazione, che includono opzioni aggiuntive oltre a un insieme di opzioni di contesto.
Ecco alcuni esempi che utilizzano le opzioni di contesto. Per impostare la scadenza RPC su 1 secondo durante la lettura di un'entità,
puoi utilizzare:
key.get(deadline=1)
Per impostare il timeout di memcache su 30 secondi quando scrivi un'entità,
puoi utilizzare:
ent.put(ndb_memcache_timeout=30)
Per eliminare un elemento che è stato memorizzato nella cache e forzarne il ricaricamento, puoi utilizzare:
key.delete(use_datastore=False)
Gli argomenti speciali delle parole chiave options e config
(che hanno significati identici per motivi storici) consentono di specificare
diverse opzioni come oggetto Configuration. Può essere un oggetto
ndb.ContextOptions o
(per le funzioni e il decoratore transazionali) un oggetto
ndb.TransactionOptions.
Ad esempio,
key.get(options=ndb.ContextOptions(use_cache=True))
è equivalente a
key.get(use_cache=True).
Le opzioni impostate in un oggetto di questo tipo possono essere sostituite dai parametri di parola chiave.
Sono disponibili le seguenti opzioni di contesto:
Opzione
Tipo
Descrizione
deadline
float
Scadenza della chiamata al datastore, specificata come numero di secondi.
Per impostazione predefinita, la chiamata viene interrotta solo dalla scadenza del gestore della richiesta.
read_policy
ndb.EVENTUAL_CONSISTENCY
Imposta questo valore su ndb.EVENTUAL_CONSISTENCY se, anziché
attendere che il DataStore finisca di applicare le modifiche a tutti
i risultati restituiti, vuoi ottenere più rapidamente risultati potenzialmente non aggiornati.
force_writes
bool
Specifica se una richiesta di scrittura deve avere esito positivo anche se l'app è di sola lettura.
(Questo vale solo per i periodi di sola lettura controllati dall'utente).
use_cache
bool
Specifica se memorizzare le entità nella cache in-process; sostituisce il criterio della cache in-process per questa operazione.
use_memcache
bool
Specifica se memorizzare le entità in memcache; sostituisce il criterio memcache per questa operazione.
use_datastore
bool
Specifica se archiviare le entità in Datastore. Sostituisce il criterio Datastore per questa operazione.
memcache_timeout
int
Durata massima delle entità in memcache; sostituisce il criterio di timeout di memcache per questa operazione.
max_memcache_items
int
Dimensione massima del batch per la funzionalità di aggregazione automatica dei metodi memcache di Context.
Ad esempio, con la dimensione predefinita di max_memcache_items
(100), fino a 100 operazioni di impostazione memcache verranno combinate in una singola operazione set_multi.
Per alcune funzioni relative alle transazioni,
sono disponibili le seguenti opzioni di transazione
(oltre alle opzioni di contesto ereditate elencate sopra):
Opzione
Tipo
Descrizione
xg
bool
Consenti le transazioni tra gruppi (XG).
False per impostazione predefinita.
propagation
int
NDB fornisce un supporto limitato per le transazioni all'interno di altre transazioni, che
sono note come "transazioni nidificate".
Il parametro di propagazione controlla cosa succede se il codice tenta di avviare una transazione nidificata.
Il criterio di propagazione per @ndb.transactional è ALLOWED per impostazione predefinita.
Il criterio di propagazione per ndb.transaction() è NESTED per impostazione predefinita.
Il criterio NESTED non è supportato da NDB, pertanto il codice genererà un'eccezione BadRequestError. In questo caso, NDB imposta un valore predefinito non supportato in modo che i programmatori siano consapevoli in modo esplicito delle limitazioni delle transazioni nidificate.
Il parametro di propagazione può essere uno dei seguenti valori:
ndb.TransactionOptions.NESTED
Il criterio di propagazione NESTED eseguirà il commit di tutte le modifiche nelle transazioni esterne e interne quando viene eseguito il commit del criterio esterno. Tuttavia, se viene lanciata un'eccezione
nella transazione interna, tutte le modifiche verranno ignorate, ma la transazione
esterna potrà eventualmente recuperare e continuare. Il criterio NESTED non è supportato. Se utilizzi questo criterio, il codice genererà un'eccezione BadRequestError.
ndb.TransactionOptions.MANDATORY
Propaga sempre una transazione esistente; genera un'eccezione se non esiste alcuna transazione.
Se una funzione che utilizza questo criterio genera un'eccezione,
probabilmente non è sicuro intercettare l'eccezione e eseguire il commit
della transazione esterna; la funzione potrebbe aver lasciato la transazione esterna
in uno stato non valido.
ndb.TransactionOptions.ALLOWED
Se esiste già una transazione, propagala.
Se una funzione che utilizza questo criterio genera un'eccezione,
probabilmente non è sicuro intercettare l'eccezione e eseguire il commit
della transazione esterna; la funzione potrebbe aver lasciato la transazione esterna
in uno stato non valido.
ndb.TransactionOptions.INDEPENDENT
Utilizza sempre una nuova transazione, mettendo in "pausa" le transazioni esistenti.
Una funzione che utilizza questo criterio non deve restituire enti
letti nella nuova transazione, poiché le entità
non sono coerentemente transazionali con la transazione
dell'utente chiamante.
retries
int
Il numero di volte in cui riprovare automaticamente in caso di errori di transazione.
Zero significa provare una volta, ma non riprovare.
In alcuni casi, le opzioni vengono ignorate a causa della memorizzazione nella cache.
Ad esempio, se specifichi una scadenza RPC per un'operazione di lettura soddisfatta dalla cache in-context, la scadenza viene ignorata.
D'altra parte,
le opzioni non riconosciute causano l'aumento di TypeError.
Le operazioni con opzioni diverse vengono raggruppate quando viene applicato il raggruppamento automatico. Ad esempio, se utilizzi put_async()
per scrivere alcune entità con
deadline = 5
e altre senza specificare una scadenza, e tutte sono idonee per il
raggruppamento automatico, il raggruppamento automatico effettuerà due chiamate RPC distinta
, una per il gruppo di entità con
deadline = 5
e una per l'altro gruppo, anche se la scadenza RPC predefinita è anche 5.
Questo vale anche se l'opzione specificata è irrilevante per
l'operazione RPC (ad esempio ndb_should_cache).
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Difficile da capire","hardToUnderstand","thumb-down"],["Informazioni o codice di esempio errati","incorrectInformationOrSampleCode","thumb-down"],["Mancano le informazioni o gli esempi di cui ho bisogno","missingTheInformationSamplesINeed","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 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`)."]]
