Funções NDB

Funções

Esta página descreve como usar os serviços e as APIs agrupados antigos. Esta API só pode ser executada em runtimes de primeira geração no ambiente padrão do App Engine. Se estiver a fazer a atualização para o runtime do App Engine Python 3, consulte o guia de migração para saber mais sobre as suas opções de migração para serviços agrupados antigos.

ndb.add_flow_exception(exc)

Especifique que uma exceção não deve ser registada, mas faz apenas parte do fluxo normal do programa. (Normalmente, gerar uma exceção escreve uma mensagem de aviso nos registos da aplicação.)

Argumentos

exc

Classe de exceção que não deve ser registada.

Por predefinição, as seguintes exceções não são registadas:

• webob.exc.HTTPException (e as respetivas subclasses)
• ndb.Rollback

ndb.delete_multi(keys, **ctx_options)

Elimina as entidades identificadas pela sequência de chaves transmitida.

Argumentos

chaves

Sequência de teclas

**ctx_options

Opções de contexto

ndb.delete_multi_async(keys, **ctx_options)

Elimina de forma assíncrona as entidades identificadas pela sequência de chaves transmitida.

Argumentos

chaves

Sequência de teclas

**ctx_options

Opções de contexto

Devolve uma lista de objetos Future. O resultado de cada contrato futuro é None.

ndb.get_multi(keys, **ctx_options)

Obtém as entidades identificadas pela sequência de chaves transmitida.

Argumentos

chaves

Sequência de teclas

**ctx_options

Opções de contexto

Devolve uma lista. Cada item da lista é uma instância de Model ou None, se a chave não tiver sido encontrada.

ndb.get_multi_async(keys, **ctx_options)

Obtém de forma assíncrona as entidades identificadas pela sequência de chaves transmitida.

Argumentos

chaves

Sequência de teclas

**ctx_options

Opções de contexto

Devolve uma lista de objetos Future. Cada resultado futuro é uma instância de Model ou None se a chave não tiver sido encontrada.

ndb.in_transaction()

Devolve um valor booleano que indica se uma transação está atualmente ativa.

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

Decorador para garantir que uma função é executada fora de uma transação.

Argumentos:

allow_existing

Se True (a predefinição) e se a função decorada for chamada por código numa transação, a função é executada independentemente da transação. Se False e se a função decorada for chamada por código numa transação, gera uma exceção.

ndb.put_multi(entities, **ctx_options)

Armazena uma sequência de instâncias de Model.

Argumentos

entidades

Sequência de instâncias do modelo

**ctx_options

Opções de contexto

Devolve uma lista com as chaves armazenadas.

ndb.put_multi_async(entities, **ctx_options)

Armazena de forma assíncrona uma sequência de instâncias de Model.

Argumentos

entidades

Sequência de instâncias do modelo

**ctx_options

Opções de contexto

Devolve uma lista de objetos Future. O resultado de cada futuro é uma chave armazenada.

ndb.transaction(callback, **ctx_options)

Execute uma chamada de retorno numa transação.

Argumentos

callback

Função ou tarefa a ser chamada

**ctx_options

Opções de transação

Devolve o que quer que callback devolva. Gera o que quer que o callback gere ou uma exceção TransactionFailedError se a transação falhar.

Para transmitir argumentos a uma função de chamada de retorno, use uma função lambda. Por exemplo,

def my_callback(key, inc):
  ...

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

ndb.transaction_async(callback, **ctx_options)

Execute de forma assíncrona uma chamada de retorno numa transação.

Argumentos

callback

Função ou tarefa a ser chamada

**ctx_options

Opções de transação

Devolve um Future. O futuro devolve o que callback devolve ou gera o que callback gera ou um TransactionFailedError se a transação falhar.

Para transmitir argumentos a uma função de chamada de retorno, use uma função lambda. Por exemplo,

def my_callback(key, inc):
  ...

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

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

Decorador para executar automaticamente uma função numa transação.

Argumentos:

Este decorador pode ter opções de transação.

Opções de contexto, opções de transação

As opções de contexto permitem-lhe executar operações específicas da base de dados com diferentes configurações. Por exemplo, pode querer variar a política de leitura ou o prazo de RPC para pedidos individuais. Pode fazê-lo transmitindo opções de contexto a quase todas as operações. Algumas funções relacionadas com transações usam opções de transação, que incluem opções adicionais além de um conjunto de opções de contexto.

Seguem-se alguns exemplos que usam opções de contexto. Para definir o prazo RPC para 1 segundo ao ler uma entidade, pode usar:

key.get(deadline=1)

Para definir o limite de tempo da memcache para 30 segundos ao escrever uma entidade, pode usar:

ent.put(ndb_memcache_timeout=30)

Para eliminar um item que foi colocado em cache e forçar a respetiva recarga, pode usar:

key.delete(use_datastore=False)

Os argumentos de palavras-chave especiais options e config (que têm significados idênticos por motivos históricos) permitem especificar várias opções como um objeto de configuração. Pode ser um objeto ndb.ContextOptions ou (para as funções transacionais e o decorador) um objeto ndb.TransactionOptions. Por exemplo, key.get(options=ndb.ContextOptions(use_cache=True)) é equivalente a key.get(use_cache=True). As opções definidas num objeto de opções deste tipo podem ser substituídas por parâmetros de palavras-chave.

Estão disponíveis as seguintes opções de contexto:

Opção	Tipo	Descrição
deadline	float	Prazo da chamada ao armazenamento de dados, especificado como um número de segundos. (Por predefinição, a chamada só é interrompida pelo prazo do controlador de pedidos.)
read_policy	ndb.EVENTUAL_CONSISTENCY	Defina este valor como ndb.EVENTUAL_CONSISTENCY se, em vez de aguardar que o Datastore termine de aplicar as alterações a todos os resultados devolvidos, quiser obter resultados possivelmente não atuais mais rapidamente.
force_writes	bool	Especifica se um pedido de escrita deve ser bem-sucedido mesmo que a app seja só de leitura. (Isto só se aplica a períodos só de leitura controlados pelo utilizador.)
use_cache	bool	Especifica se as entidades devem ser armazenadas na cache no processo; substitui a política de cache no processo para esta operação.
use_memcache	bool	Especifica se as entidades devem ser armazenadas na cache de memória; substitui a política de cache de memória para esta operação.
use_datastore	bool	Especifica se as entidades devem ser armazenadas no Datastore; substitui a política do Datastore para esta operação.
memcache_timeout	int	Duração total máxima das entidades na cache de memória; substitui a política de tempo limite da cache de memória para esta operação.
max_memcache_items	int	Tamanho máximo do lote para a funcionalidade de agrupamento automático dos métodos de memcache de Context. Por exemplo, com o tamanho predefinido de max_memcache_items (100), são combinadas até 100 operações de definição de memcache numa única operação set_multi.
Para algumas funções relacionadas com transações, estão disponíveis as seguintes opções de transação (juntamente com as opções de contexto herdadas indicadas acima):
Opção	Tipo	Descrição
xg	bool	Permita transações entre grupos (XG). False por predefinição.
propagation	int	O NDB oferece suporte limitado para transações dentro de transações, que são conhecidas como "transações aninhadas". O parâmetro de propagação controla o que acontece se o seu código tentar iniciar uma transação aninhada. A política de propagação para @ndb.transactional é predefinida como ALLOWED. A política de propagação para ndb.transaction() é predefinida como NESTED. A política de NESTED não é suportada pelo NDB, pelo que o seu código vai gerar uma exceção BadRequestError. O NDB define um valor predefinido não suportado, neste caso, para que os programadores tenham conhecimento explícito das limitações das transações aninhadas. O parâmetro de propagação pode ter um dos seguintes valores: ndb.TransactionOptions.NESTED A política de propagação NESTED consolidaria todas as alterações nas transações externas e internas em conjunto quando a política externa fosse consolidada. No entanto, se for gerada uma exceção na transação interna, todas as alterações aí são rejeitadas, mas a transação externa pode, opcionalmente, ser recuperada e continuar. A política NESTED não é suportada. Se usar esta política, o seu código vai gerar uma exceção BadRequestError. ndb.TransactionOptions.MANDATORY Propague sempre uma transação existente; lance uma exceção se não existir nenhuma transação. Se uma função que usa esta política gerar uma exceção, provavelmente, não é seguro captar a exceção e confirmar a transação externa. A função pode ter deixado a transação externa num estado incorreto. ndb.TransactionOptions.ALLOWED Se existir uma transação, propague-a. Se uma função que usa esta política gerar uma exceção, provavelmente, não é seguro captar a exceção e confirmar a transação externa. A função pode ter deixado a transação externa num estado incorreto. ndb.TransactionOptions.INDEPENDENT Use sempre uma nova transação, "pausando" as transações existentes. Uma função que usa esta política não deve devolver entidades lidas na nova transação, uma vez que as entidades não são transacionalmente consistentes com a transação do autor da chamada.
retries	int	O número de vezes que deve tentar novamente automaticamente em caso de falhas de transação. Zero significa tentar uma vez, mas não re-tentar.

Em alguns casos, as opções são ignoradas devido ao armazenamento em cache. Por exemplo, se especificar um prazo de RPC para uma operação de leitura que seja satisfeita a partir da cache no contexto, o prazo é ignorado. Por outro lado, as opções não reconhecidas fazem com que seja gerado um erro TypeError.

As operações com opções diferentes são agrupadas quando a funcionalidade de processamento em lote automático se aplica. Por exemplo, se usar put_async() para escrever algumas entidades com deadline = 5 e algumas sem especificar um prazo, e todas forem elegíveis para o processamento em lote automático, o processador em lote automático faz duas chamadas RPC separadas: uma para o grupo de entidades com deadline = 5 e outra para o outro grupo, mesmo que o prazo RPC predefinido também seja 5! Isto aplica-se mesmo que a opção especificada seja irrelevante para a operação RPC (por exemplo, ndb_should_cache).