O Python 2.7 atingiu o fim do suporte e vai ser descontinuado a 31 de janeiro de 2026. Após a descontinuação, não vai poder implementar aplicações Python 2.7, mesmo que a sua organização tenha usado anteriormente uma política organizacional para reativar as implementações de runtimes antigos. As suas aplicações Python 2.7 existentes vão continuar a ser executadas e a receber tráfego após a data de descontinuação. Recomendamos que migre para a versão suportada mais recente do Python.

Esta página foi traduzida pela API Cloud Translation.

Funções do Datastore

Nota: os programadores que criam novas aplicações são fortemente aconselhados a usar a biblioteca de cliente NDB, que tem várias vantagens em comparação com esta biblioteca de cliente, como o armazenamento em cache automático de entidades através da API Memcache. Se estiver a usar atualmente a biblioteca cliente DB mais antiga, leia o guia de migração de DB para NDB

As funções descritas nesta página estão definidas no pacote google.appengine.ext.db.

Funções

allocate_ids (model, count)

Atribui um lote de IDs no Datastore para uma combinação de tipo e principal do Datastore.

Os IDs atribuídos desta forma não são usados pelo gerador de sequência de IDs automático do Datastore e podem ser usados em chaves de entidades sem conflitos.

Argumentos

model: A chave do modelo para a qual atribuir um lote de IDs. Esta é uma chave normal, mas apenas o elemento principal e o tipo da chave são necessários para determinar que sequência de IDs usar.
count: O número de IDs a atribuir.

Devolve uma tupla dos primeiros e últimos IDs que atribui. Por exemplo, se tiver atribuído 10 IDs através desta função, recebe um retorno no formato (1, 10) e não uma lista completa dos IDs criados.

Exemplo de atribuição e utilização de 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)

Aloca de forma assíncrona um lote de IDs no Datastore para um tipo do Datastore e uma combinação principal.

Esta função é idêntica a allocate_ids() , exceto que devolve um objeto assíncrono. Pode chamar get_result() no valor de devolução para bloquear a chamada e devolver o resultado.

Argumentos

model: A db.Model instance, key, or string to serve as a template specifying the ID sequence in which to allocate IDs. Os IDs devolvidos só devem ser usados em entidades com o mesmo elemento principal (se existir) e tipo que esta chave.
count: O número de IDs a atribuir.

Devolve uma tupla dos primeiros e últimos IDs que atribui. Por exemplo, se tiver atribuído 10 IDs através desta função, recebe um valor de retorno no formato (1, 10) e não uma lista completa dos IDs criados.

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

Atribui um intervalo de IDs com pontos finais específicos. Depois de estes IDs terem sido atribuídos, pode atribuí-los manualmente a entidades recém-criadas.

O alocador de IDs automático do Datastore nunca atribui uma chave que já tenha sido atribuída (através da atribuição de IDs automática ou de uma chamada `allocate_ids` explícita). Como resultado, as entidades escritas no intervalo de chaves indicado nunca são substituídas. No entanto, a escrita de entidades com chaves atribuídas manualmente neste intervalo pode substituir as entidades existentes (ou novas entidades escritas por um pedido separado), consoante o estado do intervalo de chaves devolvido.

Use esta função apenas se tiver um intervalo de IDs numéricos existente que queira reservar (por exemplo, carregar em massa entidades que já tenham IDs). Se não se importar com os IDs que recebe, use allocate_ids() em alternativa.

Argumentos

model: A db.Model instance, key, or string to serve as a template specifying the ID sequence in which to allocate IDs. Os IDs devolvidos só devem ser usados em entidades com o mesmo elemento principal (se existir) e tipo que esta chave.
start: O primeiro ID a atribuir, um número.
end: O último ID a atribuir, um número.

Devolve um dos seguintes valores: (KEY_RANGE_EMPTY, KEY_RANGE_CONTENTION, KEY_RANGE_COLLISION). Se não for KEY_RANGE_EMPTY, isto representa um potencial problema com a utilização do intervalo de chaves atribuído.

create_transaction_options (**kwargs)

Cria um objeto de opções de transação (class TransactionOptions) para controlar a execução de transações. Passa o objeto resultante como o primeiro argumento para a função run_in_transaction_options().

Argumentos

propagação

O que fazer se esta função transacional for chamada a partir de outra transação:

PERMITIDO: Se já estiver numa transação, continue a usá-lo; caso contrário, inicie uma.
Nota: 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.
OBRIGATÓRIO: Continuar na transação existente, se houver; caso contrário, lançar uma exceção.BadRequestError
Nota: 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.
INDEPENDENTE: Criar uma nova transação, pausando qualquer transação existente.
Nota: uma função que use esta política não deve devolver nenhuma entidade lida na nova transação, uma vez que as entidades não são transacionalmente consistentes com a transação externa.
ANINHADO: (Ainda não suportado) Crie uma transação aninhada numa transação existente.

xg

Se True, permitir transações entre grupos (XG). Gera uma exceção se for definido como um valor não booleano.BadArgumentError

retries

Número de novas tentativas a efetuar em caso de falha da confirmação da transação.

deadline

Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

O exemplo seguinte cria as opções para uma transação entre grupos (XG) subsequente:

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)

Elimina uma ou mais instâncias de modelos do Datastore.

Argumentos

modelos: Uma instância do modelo, uma chave de entidade, ou uma lista (ou outro iterável) de instâncias do modelo ou chaves de entidades a eliminar.
deadline: Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

Tal como com put(), se forem fornecidas várias chaves, podem estar em mais do que um grupo de entidades.

É sempre gerada uma exceção se ocorrer algum erro durante a operação, mesmo que algumas das entidades tenham sido eliminadas. Se a chamada for devolvida sem gerar uma exceção, significa que todas as entidades foram eliminadas com êxito.

Atenção: a eliminação de várias entidades numa única operação não garante que as eliminações ocorram de forma atómica, a menos que a operação seja realizada numa transação. Outros processos que consultam o Datastore podem ver resultados inconsistentes, mesmo quando a consulta é realizada com consistência forte.

delete_async (models, deadline=60)

Elimina de forma assíncrona uma ou mais instâncias do modelo do Datastore.

Esta função é idêntica a delete() , exceto que devolve um objeto assíncrono. Pode chamar get_result() no valor de devolução para bloquear na chamada.

Argumentos

modelos: Uma instância do modelo, uma chave de entidade, ou uma lista (ou outro iterável) de instâncias do modelo ou chaves de entidades a eliminar.
deadline: Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

Tal como com put(), se forem fornecidas várias chaves, podem estar em mais do que um grupo de entidades.

Esta função devolve um objeto que lhe permite bloquear o resultado da chamada.

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

Obtenha as instâncias do modelo específicas com as chaves fornecidas do Datastore.

Argumentos

chaves

Chave da entidade a obter, uma representação de string da chave ou uma lista de chaves ou das respetivas representações de string.

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

Se keys consistir numa única chave (ou na respetiva representação de string), esta função devolve a instância do modelo associada à chave se a chave existir no Datastore. Caso contrário, devolve None. Se keys for uma lista, o valor de retorno é uma lista correspondente de instâncias do modelo, com valores None onde não existe nenhuma entidade para uma determinada chave.

Veja também Model.get().

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

Obtém de forma assíncrona as instâncias do modelo especificadas a partir do armazenamento de dados.

Esta função é idêntica a get() , exceto que devolve um objeto assíncrono. Pode chamar get_result() no valor de retorno para bloquear a chamada e obter os resultados.

Argumentos

chaves

Chave da entidade a obter, uma representação de string da chave ou uma lista de chaves ou das respetivas representações de string.

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

Veja também Model.get().

get_indexes ()

Devolve uma lista de índices compostos pertencentes à aplicação de chamada.

O exemplo seguinte ilustra como obter e usar os índices:

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 ()

Devolve de forma assíncrona uma lista de índices compostos pertencentes à aplicação de chamada.

is_in_transaction ()

Devolve um valor booleano que indica se o âmbito atual está a ser executado numa transação.

model_to_protobuf (model_instance)

Cria a serialização do buffer do protocolo de uma instância de Model. Um buffer de protocolo é o formato de serialização da Google usado para chamadas de procedimentos remotos e pode ser útil para serializar objetos do Datastore para fins de cópia de segurança e restauro.

Aviso: esta função usa um formato de buffers de protocolo diferente (mais antigo) do formato de buffers de protocolo de código aberto e não é compatível com a implementação de código aberto.

Argumento

model_instance: A instância da classe Model (ou uma subclasse) a serializar.

Devolve a serialização do buffer de protocolo do objeto como uma string de bytes.

model_from_protobuf (pb)

Cria uma instância Model com base numa serialização de protocolo buffer; consulte model_to_protobuf() para mais informações.

Argumento

pb: A serialização do buffer do protocolo, conforme devolvida por model_to_protobuf().

Devolve um objeto da classe de tipo adequada. Se a classe kind não existir, gera uma exceção KindError Se o objeto não for válido de acordo com o modelo, gera uma exceção BadValueError.

Pode guardar o novo objeto no Datastore tal como qualquer outra instância, por exemplo, chamando o respetivo método put() .Model O objeto retém a chave que tinha quando o protocolo buffer foi criado. Se já existir um objeto com essa chave no Datastore, a gravação do objeto desserializado substitui o objeto existente.

Atenção: se a chave do objeto usar um ID atribuído pelo sistema e esse ID ainda não tiver sido atribuído para o caminho e o tipo especificados, a gravação é bem-sucedida, mas o ID não é reservado. Um objeto criado no futuro pode ser-lhe atribuído esse ID e substituiria o objeto anterior. Por motivos de segurança, restaure objetos apenas na mesma aplicação em que existiam quando foram serializados.

model_is_projection (model_instance)

Devolve True se a consulta especificada (model_instance) for uma consulta de projeção em vez de uma consulta para uma entidade completa.

Argumento

model_instance: A consulta que está a verificar para determinar se é uma consulta de projeção.

Devolve True se a consulta for uma consulta de projeção, False se não for.

put (models, deadline=60)

Escreve uma ou mais instâncias de modelos no Datastore.

Argumentos

modelos: Uma instância de modelo ou uma lista de instâncias de modelo a armazenar.
deadline: Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

Se forem fornecidas várias instâncias de modelos, estas podem estar em mais do que um grupo de entidades.

É sempre gerada uma exceção se ocorrer algum erro durante a operação, mesmo que algumas das entidades tenham sido escritas. Se a chamada for devolvida sem gerar uma exceção, significa que todas as entidades foram escritas com êxito.

Se models consistir numa única instância do modelo, esta função devolve o objeto Key correspondente. Se models for uma lista, o valor de retorno é uma lista de objetos Key correspondentes.

Atenção: a escrita de várias entidades numa única operação não garante que as escritas ocorram de forma atómica, a menos que a operação seja realizada numa transação. Outros processos que consultam o Datastore podem ver resultados inconsistentes, mesmo quando a consulta é realizada com consistência forte.

put_async (models, deadline=60)

Escreve uma ou mais instâncias de modelos no Datastore.

Esta função é idêntica a put() , exceto que devolve um objeto assíncrono. Pode chamar get_result() no valor de retorno para bloquear a chamada e obter os resultados.

Argumentos

modelos: Uma instância de modelo ou uma lista de instâncias de modelo a armazenar.
deadline: Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

Se forem fornecidas várias instâncias de modelos, estas podem estar em mais do que um grupo de entidades.

Esta função devolve um objeto assíncrono no qual get_result() pode ser chamado. Os resultados devolvidos são os mesmos que para put().

query_descendants (model_instance)

Devolve uma consulta para todos os descendentes de uma instância do modelo.

Argumento

model_instance: A instância do modelo cujos descendentes quer encontrar.

run_in_transaction (function, *args, **kwargs)

Executa uma função que contém atualizações do Datastore numa única transação. Se algum código gerar uma exceção durante a transação, todas as atualizações feitas na transação são revertidas. Em alternativa, pode usar o decorador @db.transactional().

Argumentos

função: Função a executar.
args: Argumentos posicionais a transmitir para a função.
kwargs: Argumentos de palavras-chave a transmitir à função.

Se a função devolver um valor, run_in_transaction() devolve o valor ao autor da chamada.

Se a função gerar uma exceção, a transação é revertida. Se a exceção for uma exceção Rollback, não é gerada novamente. Qualquer outra exceção é gerada novamente para o autor da chamada.

O Datastore usa o bloqueio otimista e tenta novamente as transações. Se a transação preparada pela função não puder ser confirmada, run_in_transaction() chama a função novamente, repetindo a transação até 3 vezes. (Para usar um número diferente de novas tentativas, use run_in_transaction_custom_retries().) Uma vez que a função de transação pode ser chamada mais do que uma vez para uma única transação, a função não deve ter efeitos secundários, incluindo modificações nos argumentos.

Se não for possível confirmar a transação, por exemplo, devido a uma taxa elevada de concorrência, é gerada uma exceção TransactionFailedError.

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)

Executa uma função que contém atualizações do Datastore numa única transação, repetindo a transação um número especificado de vezes em caso de concorrência. Se algum código gerar uma exceção durante a transação, todas as atualizações feitas na transação são revertidas.

Além da capacidade de especificar o número de novas tentativas, esta função comporta-se de forma idêntica a run_in_transaction().

Argumentos

retries: Número máximo de vezes para chamar a função no caso de conflito no grupo de entidades (mais do que um utilizador a tentar modificar o grupo em simultâneo).
função: Função a executar.
args: Argumentos posicionais a transmitir para a função.
kwargs: Argumentos de palavras-chave a transmitir à função.

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

Executa uma função que contém atualizações do Datastore numa única transação usando as opções especificadas num objeto de opções de transação. Se algum código gerar uma exceção durante a transação, todas as atualizações do Datastore feitas na transação são revertidas.

Para transações entre grupos (XG), o parâmetro xg no objeto de opções de transação tem de ser definido como True.

Argumentos

options: O objeto de opções de transação que contém as definições usadas por esta transação. Para ativar as transações XG, o respetivo parâmetro xg tem de estar definido como True.
função: Função a executar.
args: Argumentos posicionais a transmitir para a função.
kwargs: Argumentos de palavras-chave a transmitir à função.

Se a função devolver um valor, run_in_transaction_options() devolve o valor ao autor da chamada.

O Datastore usa o bloqueio otimista e tenta novamente as transações. Se a transação preparada pela função não puder ser confirmada, run_in_transaction_options() chama a função novamente, repetindo a transação até ao número de repetições especificado no objeto de opções de transação. Uma vez que a função de transação pode ser chamada mais do que uma vez para uma única transação, a função não deve ter efeitos secundários, incluindo modificações nos argumentos.

Se não for possível confirmar a transação, por exemplo, devido a uma taxa elevada de concorrência, é gerada uma exceção TransactionFailedError.

O exemplo seguinte mostra como usar esta função para executar uma transação entre grupos:

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, dictionary=None)

Cria e devolve uma representação de dicionário de uma instância de modelo.

Argumentos

model_instance: Instância do modelo a copiar.
dicionário: Se estiver presente, dicionário no qual unir os dados do modelo. Os valores do modelo substituem os valores no dicionário; as entradas do dicionário que não correspondam a campos na instância do modelo são preservadas.

Decoradores

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

Faz com que uma função seja executada numa transação db. Assim, em vez de chamar run_in_transaction(func), pode chamar func().

Argumentos

propagação

O que fazer se esta função transacional for chamada a partir de outra transação:

PERMITIDO: Se já estiver numa transação, continue a usá-lo; caso contrário, inicie uma.
Nota: 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.
OBRIGATÓRIO: Continuar na transação existente, se houver; caso contrário, lançar uma exceção.BadRequestError
Nota: 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.
INDEPENDENTE: Criar uma nova transação, pausando qualquer transação existente.
Nota: uma função que use esta política não deve devolver nenhuma entidade lida na nova transação, uma vez que as entidades não são transacionalmente consistentes com a transação externa.
ANINHADO: (Ainda não suportado) Crie uma transação aninhada numa transação existente.

xg

Se True, permitir transações entre grupos (XG). Gera uma exceção se for definido como um valor não booleano.BadArgumentError

retries

Número de novas tentativas a efetuar em caso de falha da confirmação da transação.

deadline

@db.non_transactional (allow_existing=True)

Garante que uma função é executada fora de uma transação db, mesmo que seja chamada a partir de uma transação.

Argumento

allow_existing: Se True, permite que a função seja chamada a partir de uma transação existente; se False, gera uma exceção BadRequestError.

Funções do Datastore Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Funções

Decoradores

Funções do Datastore