Criar, obter, atualizar e eliminar entidades

Os objetos de dados no Datastore são conhecidos como entidades, cada uma das quais é categorizada num tipo específico para fins de consultas. Por exemplo, se estiver a escrever uma aplicação de recursos humanos, pode representar cada funcionário com uma entidade do tipo Employee. Tenha em atenção que os valores dos dados das entidades estão sob a forma de propriedades. Para mais informações sobre entidades, consulte a documentação sobre caminhos de ascendentes e transações.

Criar entidades e definir propriedades

Cria uma entidade e um conjunto chamando o método do construtor para a respetiva classe de modelo. Consulte o artigo Criar e usar classes de modelos de entidades para obter informações sobre como criar uma classe de modelo de entidade.

O exemplo seguinte mostra como invocar um construtor de classe de modelo com argumentos de palavras-chave:

sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')

Este código cria um objeto na memória principal do seu programa. No entanto, tenha em atenção que a entidade desaparece quando o processo termina. Por isso, também tem de persistir a entidade no Datastore chamando put(), da seguinte forma:

sandy_key = sandy.put()

Tenha em atenção que esta ação devolve uma chave que pode usar para obter a entidade do Datastore mais tarde.

Defina propriedades através de uma das seguintes opções:

  • Especifique as propriedades da entidade para o construtor com argumentos de palavras-chave: 
    sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')
  • Defina propriedades manualmente após a criação da entidade: 
    sandy = Account()
sandy.username = 'Sandy'
sandy.userid = 123
sandy.email = 'sandy@example.com'
  • Use o método prático populate() para definir várias propriedades numa operação: 
    sandy = Account()
sandy.populate(
    username='Sandy',
    userid=123,
    email='sandy@gmail.com')

No entanto, independentemente da forma como optar por definir as propriedades da entidade, os tipos de propriedades (neste caso, StringProperty e IntegerProperty) aplicam a verificação de tipos.

Por exemplo:

bad = Account(
    username='Sandy', userid='not integer')  # raises an exception
... 
sandy.username = 42  # raises an exception

Obter entidades a partir de chaves

Se tiver a chave de uma entidade, pode obtê-la a partir do Datastore:

sandy = sandy_key.get()

Os métodos Key kind() e id() recuperam o tipo e o identificador da entidade da chave:

kind_string = sandy_key.kind()  # returns 'Account'
ident = sandy_key.id()  # returns '2'

Também pode usar a chave de uma entidade para obter uma string codificada adequada para incorporação num URL:

url_string = sandy_key.urlsafe()

Isto produz um resultado como agVoZWxsb3IPCxIHQWNjb3VudBiZiwIM, que pode ser usado posteriormente para reconstruir a chave e obter a entidade original:

sandy_key = ndb.Key(urlsafe=url_string)
sandy = sandy_key.get()

Tenha em atenção que a string segura para URLs parece enigmática, mas não está encriptada! Pode ser facilmente descodificado para recuperar o tipo e o identificador da entidade original:

key = Key(urlsafe=url_string)
kind_string = key.kind()
ident = key.id()

Se usar chaves seguras para URLs, não use dados confidenciais, como endereços de email, como identificadores de entidades. Uma possível solução seria usar um hash dos dados confidenciais como identificador. Isto impede que terceiros, que podem ver as chaves encriptadas, as usem para recolher endereços de email, embora não os impeça de gerar independentemente o seu próprio hash de um endereço de email conhecido e usá-lo para verificar se esse endereço está presente no Datastore.

A atualizar entidades

Para atualizar uma entidade existente, obtenha-a a partir do Datastore, modifique as respetivas propriedades e armazene-a novamente:

sandy = key.get()
sandy.email = 'sandy@example.co.uk'
sandy.put()

Neste caso, pode ignorar o valor devolvido por put(), uma vez que uma chave de entidade não se altera quando a atualiza.

Eliminar entidades

Quando uma entidade já não é necessária, pode removê-la do Datastore com o método delete() da chave:

sandy.key.delete()

Tenha em atenção que esta é uma operação na chave e não na própria entidade. Devolve sempre None.

Eliminar entidades em massa

Se precisar de eliminar um grande número de entidades, recomendamos que use o Dataflow para eliminar entidades em massa.

Usar operações em lote

Pode processar uma coleção de entidades ou chaves numa única chamada em vez de o fazer individualmente em chamadas separadas, por exemplo, dentro de um ciclo. Isto resulta numa única chamada de procedimento remoto (RPC) para o lote, em vez de uma chamada RPC separada para cada entidade.

O código seguinte mostra como o fazer:

list_of_keys = ndb.put_multi(list_of_entities)
list_of_entities = ndb.get_multi(list_of_keys)
ndb.delete_multi(list_of_keys)

No código acima, passa uma lista de objetos de chave para ndb.get_multi para obter várias entidades num lote; ndb.get_multi devolve uma lista de objetos de entidade, com valores None para chaves que não têm uma entidade correspondente no Datastore. A obtenção das entidades desta forma resulta em menos chamadas para o Datastore para todo o lote. (O número de chamadas por lote depende das definições de tamanho do lote.)