Nota: il 31 gennaio 2024 è stato raggiunto il termine del supporto di Python 2.7. Le applicazioni Python 2.7 esistenti continueranno a essere eseguite e a ricevere traffico. Tuttavia, App Engine potrebbe bloccare il nuovo deployment delle applicazioni che utilizzano i runtime dopo la data di fine del supporto. Ti consigliamo di eseguire la migrazione alla versione più recente di Python supportata.

Questa pagina è stata tradotta dall'API Cloud Translation.

Funzioni NDB

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'eccezione genera 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.

Argomenti

keys: Sequenza di chiavi
**ctx_options: Opzioni di contesto

ndb.delete_multi_async(keys, **ctx_options)

Elimina in modo asincrono le entità identificate dalla sequenza di chiavi passata.

Argomenti

keys: Sequenza di chiavi
**ctx_options: Opzioni di contesto

ndb.get_multi(keys, **ctx_options)

Recupero delle entità identificate dalla sequenza di chiavi passata.

Argomenti

keys: Sequenza di chiavi
**ctx_options: Opzioni di contesto

ndb.get_multi_async(keys, **ctx_options)

Recupero asincrono delle entità identificate dalla sequenza di chiavi passata.

Argomenti

keys: Sequenza di chiavi
**ctx_options: Opzioni di contesto

ndb.in_transaction()

Restituisce un valore booleano che indica se una transazione è attualmente attiva.

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

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.

ndb.put_multi(entities, **ctx_options)

Memorizza una sequenza di istanze Model.

Argomenti

entities: Sequenza di istanze Model
**ctx_options: Opzioni di contesto

ndb.put_multi_async(entities, **ctx_options)

Archivia in modo asincrono una sequenza di Model.

Argomenti

entities: Sequenza di istanze Model
**ctx_options: Opzioni di contesto

ndb.transaction(callback, **ctx_options)

Esegui un callback in una transazione.

Argomenti

callback: Funzione o tasklet da chiamare
**ctx_options: Opzioni di transazione

ndb.transaction_async(callback, **ctx_options)

Esegui un callback in modo asincrono in una transazione.

Argomenti

callback: Funzione o tasklet da chiamare
**ctx_options: Opzioni di transazione

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,

def my_callback(key, inc):
  ...

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

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

Decoratore per eseguire automaticamente una funzione in una transazione.

Argomenti:

Questo decoratore può avere opzioni di transazione.

Opzioni di contesto, Opzioni di transazione

Le opzioni di contesto ti consentono di eseguire operazioni specifiche del datastore con configurazioni diverse. Ad esempio, potresti voler variare il criterio per la 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 delle richieste.
`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 un'unica 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 compatibili con la transazione del chiamante.
`retries`	`int`	Il numero di volte per 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).