Observação: o Python 2.7 chegou ao fim do suporte em 31 de janeiro de 2024. Os aplicativos Python 2.7 atuais continuarão a ser executados e a receber tráfego. No entanto, o App Engine pode bloquear a reimplantação de aplicativos que usam ambientes de execução após o término da data de suporte. Recomendamos que você migre para a versão compatível mais recente do Python.

A classe Key

Observação: é altamente recomendável a desenvolvedores que criam novos aplicativos usar a biblioteca de cliente NDB, porque ela oferece diversos benefícios em comparação com esta biblioteca de cliente, como armazenamento em cache automático de entidades por meio da API Memcache. Se você estiver usando a antiga biblioteca de cliente DB, 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.

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

Introdução

Toda instância de modelo tem uma chave, de identificação, que inclui o tipo de entidade da instância com um identificador exclusivo. O identificador pode ser uma string de nome de chave, atribuída explicitamente pelo aplicativo no momento da criação da instância, ou um ID numérico de números inteiros, atribuído automaticamente pelo App Engine no momento em que a instância é gravada (put) no Datastore. O método key() da instância de modelo retorna o objeto Key da instância. Se a instância ainda não tiver recebido uma chave, key() gerará um NotSavedError.

Um aplicativo pode recuperar uma instância de modelo para uma determinada Key usando a função get().

Instâncias de chave podem ser valores para propriedades da entidade do Datastore, incluindo propriedades dinâmicas de Expando e membros de ListProperty. O modelo ReferenceProperty oferece recursos para valores da propriedade Key, como desreferenciamento automático.

Construtor

class Key(encoded=None)

Uma chave exclusiva para um objeto do Datastore.

Uma chave pode ser convertida em uma string ao transmitir o objeto Key para str(). A string é "urlsafe". Ela usa apenas caracteres válidos para uso em URLs. A representação da string da chave pode ser convertida de volta para um objeto Key ao transmiti-la para o construtor Key (o argumento codificado).

Observação: a representação da string de uma chave parece criptografada, mas não é. Ela pode ser convertida de volta para os dados de chave brutos, tanto de tipo quanto de identificador. Se você não quiser expor esses dados aos usuários (e permitir que eles adivinhem facilmente as chaves de outras entidades), criptografe essas sequências ou use outra solução.

codificado: O formulário str de uma instância Key para converter novamente para Key.

Métodos de classe

A classe Key fornece os seguintes métodos de classe:

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

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

Um caminho representa a hierarquia de relacionamentos pai-filho de uma entidade. Cada entidade no caminho é representada pelo tipo da entidade e pelo código numérico ou nome de chave dela. O caminho completo representa a entidade que aparece por último no caminho, com os ancestrais (pais) como entidades precedentes.

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

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

Uma maneira alternativa de criar a mesma Key é 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

path

Uma lista de um ou mais componentes de caminho ancestrais, em que cada componente consiste em um tipo e um identificador:

Tipo: o tipo de entidade. É representado como uma string ou uma string Unicode.
Identificador: o id, especificado como uma string ou longo. não pode ser o número 0.

namespace=None

O namespace a definir apenas para esta Key. Se você fornecer um namespace aqui, ele substituirá o atual definido em namespace_manager. Se None, a API usará o namespace atual de namespace_manager.get_namespace.

parent=None

Chave pai opcional. Se não fornecida, o padrão será None.

Métodos da instância

As instâncias de Key têm os métodos abaixo:

app(): Retorna o nome do aplicativo que armazenou a entidade de dados.
has_id_or_name(): Retornará True se a entidade tiver um nome ou um ID numérico.
id(): Retorna um 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(): Retorna o nome ou o ID numérico da entidade de dados, o que estiver presente, ou None se a entidade não tiver nome nem ID numérico.
kind(): Retorna o tipo da entidade de dados em forma de string.
name(): Retorna o nome da entidade de dados ou None se a entidade não tiver um nome.
namespace(): Retorna o namespace da entidade de dados. Se a entidade não tiver um namespace atual, este método retornará o namespace atual definido em namespace_manager.
parent(): Retorna a Key da entidade pai da entidade de dados ou None se a entidade não tiver pai.