The Key Class

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

Uma instância da classe Key representa uma chave exclusiva para uma entidade do Datastore.

O Key é fornecido pelo módulo google.appengine.ext.db.

Introdução

Cada instância do modelo tem uma chave de identificação, que inclui o tipo de entidade da instância, juntamente com um identificador exclusivo. O identificador pode ser uma string de nome da chave, atribuída explicitamente pela aplicação quando a instância é criada, ou um ID numérico inteiro,atribuído automaticamente pelo App Engine quando a instância é escrita (put) no Datastore. O método key() da instância do modelo devolve o objeto Key para a instância. Se ainda não tiver sido atribuída uma chave à instância, key() gera um erro NotSavedError.

Uma aplicação pode obter uma instância de modelo para uma determinada chave através da função get().

As instâncias de chaves podem ser valores para propriedades de entidades do Datastore, incluindo propriedades dinâmicas Expando e membros ListProperty. O modelo ReferenceProperty oferece funcionalidades para valores de propriedades principais, como a desreferenciação automática.

Construtor

class Key(encoded=None)

Uma chave única para um objeto do Datastore.

Uma chave pode ser convertida numa string transmitindo o objeto Key a str(). A string é "urlsafe" e usa apenas carateres válidos para utilização em URLs. A representação de string da chave pode ser convertida novamente num objeto Key transmitindo-a ao construtor Key (o argumento codificado).

Nota: a representação de string de uma chave parece críptica, mas não está encriptada! Pode ser convertida novamente nos dados da chave não processados, tanto do tipo como do identificador. Se não quiser expor estes dados aos seus utilizadores (e permitir que adivinhem facilmente as chaves de outras entidades), encriptar estas strings ou usar outra coisa.

codificado
O formulário str de uma instância de chave a converter novamente numa chave.

Métodos de classe

A classe Key fornece o seguinte método de classe:

Key.from_path(*path, parent=None, namespace=None)

Cria um novo objeto Key a partir de um caminho de antepassado (opcional) (num objeto Key existente) e de uma ou mais novas componentes do caminho. Cada componente do caminho consiste num nome de tipo (kind) e num identificador (id_or_name), que é um número ou uma string de carateres.

Um caminho representa a hierarquia de relações superior-secundário para uma entidade. Cada entidade no caminho é representada pelo tipo da entidade e pelo respetivo ID numérico ou nome da chave. O caminho completo representa a entidade que aparece por último no caminho, com os respetivos antecessores (superiores) como entidades precedentes.

Por exemplo, a seguinte chamada cria uma chave para uma entidade do tipo Address com o ID numérico 9876, na chave principal User/Boris:

k = Key.from_path('User', 'Boris', 'Address', 9876)

Uma forma alternativa de criar a mesma chave é a seguinte:

p1 = Key.from_path('User', 'Boris')
k = Key.from_path('Address', 9876, parent=p1)

Para mais informações sobre caminhos, consulte a página Entidades, propriedades e chaves.

Argumentos

caminho
Uma lista de um ou mais componentes do caminho de antecessores, em que cada componente consiste num tipo e num identificador:
  • kind: o tipo de entidade, representado como uma string ou uma string Unicode.
  • identifier: o id, especificado como uma string ou um número inteiro longo. Não pode ser o número 0.
namespace=None
O espaço de nomes a definir apenas para esta chave. Se fornecer um espaço de nomes aqui, substitui o espaço de nomes atual definido no namespace_manager. Se None, a API usa o espaço de nomes atual de namespace_manager.get_namespace.
parent=None
Chave principal opcional. Se não for fornecido, o fuso horário predefinido é None.

Métodos de instância

As instâncias principais têm os seguintes métodos:

app()

Devolve o nome da aplicação que armazenou a entidade de dados.

has_id_or_name()

Devolve True se a entidade tiver um nome ou um ID numérico.

id()

Devolve o ID numérico da entidade de dados, como um número inteiro, ou None se a entidade não tiver um ID numérico.

id_or_name()

Devolve o nome ou o ID numérico da entidade de dados, consoante o que tiver, ou None se a entidade não tiver um nome nem um ID numérico.

kind()

Devolve o tipo da entidade de dados como uma string.

name()

Devolve o nome da entidade de dados ou None se a entidade não tiver um nome.

namespace()

Devolve o espaço de nomes da entidade de dados. Se a entidade não tiver um espaço de nomes atual, este método devolve o espaço de nomes atual definido no namespace_manager.

parent()

Devolve a chave da entidade principal da entidade de dados ou None se a entidade não tiver uma entidade principal.