Como criar e usar chaves de entidade

Essa API é compatível com os ambientes de execução de primeira geração e pode ser usada ao fazer upgrade para os ambientes de execução de segunda geração correspondentes. Se você estiver atualizando para o ambiente de execução do Java 11/17 do App Engine, consulte o guia de migração para saber mais sobre as opções de migração para serviços incluídos legados.

Cada entidade no Datastore tem uma chave que a identifica de maneira exclusiva. A chave tem os seguintes componentes:

• O namespace da entidade, que possibilita a multilocação
• O tipo da entidade, que a categoriza para as consultas do Datastore
• Um caminho ancestral opcional que localiza a entidade na hierarquia do Datastore.

• Um identificador da entidade individual, que pode ser:

  • uma string de nome da chave;
  • um código numérico inteiro

Como o identificador é parte da chave da entidade, ele é associado permanentemente à entidade e não pode ser alterado. Atribua o identificador de uma dessas maneiras:

• Especifique sua própria string de nome de chave para a entidade.
• Deixe o Datastore atribuir automaticamente à entidade um ID numérico inteiro.

Não dê o nome "key" a uma propriedade. Esse nome é reservado para uma propriedade especial usada para armazenar a chave do modelo. Ela pode funcionar localmente, mas uma propriedade chamada "key" impedirá a implantação do App Engine.

Como especificar um nome de chave para uma entidade

Para atribuir um nome de chave a uma entidade, forneça o nome como o segundo argumento para o construtor quando criar a entidade:

Entity employee = new Entity("Employee", "asalieri");

Para que o Datastore atribua um código numérico automaticamente, omita esse argumento:

Entity employee = new Entity("Employee");

Como atribuir identificadores

É possível configurar o Datastore para gerar IDs automáticos usando duas políticas de ID automático diferentes:

• A política default gera uma sequência aleatória de IDs não utilizados que são aproximadamente distribuídos de maneira uniforme. Cada ID pode ter até 16 dígitos decimais.
• A política legacy cria uma sequência de IDs inteiros menores e não consecutivos.

Para exibir os IDs de entidade para o usuário e/ou depender da ordem deles, use a alocação manual.

Observação: em vez de usar strings de nomes de chave ou gerar IDs numéricos automaticamente, os aplicativos avançados às vezes podem atribuir os próprios IDs numéricos manualmente às entidades criadas por eles. No entanto, não há nada que impeça o Datastore de atribuir um dos IDs numéricos manuais a outra entidade. A única maneira de evitar esse tipo de conflito é fazer com que o aplicativo receba um bloco de IDs com os métodos DatastoreService.allocateIds() ou AsyncDatastoreService.allocateIds(). O gerador de ID automático do Datastore irá monitorar os IDs alocados com esses métodos e evitará reutilizá-los para outra entidade. Assim, será possível usá-los com segurança e sem conflitos.

Como usar caminhos ancestrais

As entidades no Cloud Datastore formam um espaço hierarquicamente estruturado, semelhante à estrutura de diretórios de um sistema de arquivos. Ao criar uma entidade, é possível designar outra entidade como mãe e a nova como filha. Ao contrário do que ocorre em um sistema de arquivos, a entidade mãe não precisa existir de verdade. Uma entidade sem mãe é uma entidade raiz. A associação entre uma entidade e a mãe é permanente e não pode ser alterada depois que a entidade é criada. O Cloud Datastore nunca atribuirá o mesmo ID numérico a duas entidades com a mesma mãe ou a duas entidades raiz (sem mãe).

A mãe de uma entidade, a mãe da mãe, e assim por diante são ancestrais dela. A filha, a filha da filha, e assim por diante são descendentes dela. Uma entidade raiz e todos os descendentes pertencem ao mesmo grupo de entidades. A sequência de entidades começando com uma entidade raiz e prosseguindo de pai para filho, levando a uma determinada entidade, constitui o caminho do ancestral dessa entidade. A chave completa que identifica a entidade consiste em uma sequência de pares de identificadores de tipo que especifica o caminho ancestral e termina com os da própria entidade:

[Person:GreatGrandpa, Person:Grandpa, Person:Dad, Person:Me]

Para uma entidade raiz, o caminho ancestral está vazio, e a chave consiste unicamente no próprio tipo e identificador da entidade:

[Person:GreatGrandpa]

Esse conceito é ilustrado pelo seguinte diagrama:

Para designar a mãe de uma entidade, informe a chave da entidade pai como argumento do construtor Entity() ao criar a entidade filho. Para receber a chave, chame o método getKey() da entidade pai:

Entity employee = new Entity("Employee");
datastore.put(employee);

Entity address = new Entity("Address", employee.getKey());
datastore.put(address);

Se a nova entidade também tiver um nome de chave, forneça esse nome como o segundo argumento para o construtor Entity() e a chave da entidade pai como o terceiro argumento:

Entity address = new Entity("Address", "addr1", employee.getKey());

Como gerar chaves

Os aplicativos podem usar a classe KeyFactory para criar um objeto Key para uma entidade a partir de componentes conhecidos, como o tipo e o identificador da entidade. No caso de uma entidade sem pai, transmita o tipo e o identificador (que podem ser uma string de nome de chave ou um ID numérico) ao método estático KeyFactory.createKey() para criar a chave. Os exemplos a seguir criam uma chave para uma entidade do tipo Person com o nome de chave "GreatGrandpa" ou o ID numérico 74219:

Key k1 = KeyFactory.createKey("Person", "GreatGrandpa");
Key k2 = KeyFactory.createKey("Person", 74219);

Se a chave incluir um componente de caminho, use a classe auxiliar KeyFactory.Builder para criar o caminho. Com o método addChild dessa classe, uma única entidade é adicionada ao caminho e o próprio criador é retornado. Assim, é possível encadear uma série de chamadas, começando com a entidade raiz, para criar o caminho com uma entidade por vez. Depois de criar o caminho completo, chame getKey para recuperar a chave resultante:

Key k =
    new KeyFactory.Builder("Person", "GreatGrandpa")
        .addChild("Person", "Grandpa")
        .addChild("Person", "Dad")
        .addChild("Person", "Me")
        .getKey();

A classe KeyFactory também inclui os métodos estáticos keyToString e stringToKey para a conversão entre chaves e as respectivas representações de string:

String personKeyStr = KeyFactory.keyToString(k);

// Some time later (for example, after using personKeyStr in a link).
Key personKey = KeyFactory.stringToKey(personKeyStr);
Entity person = datastore.get(personKey);

A representação de string de uma chave é "segura para Web": não contém caracteres considerados especiais em HTML nem em URLs.

Observação: o método KeyFactory.keyToString é diferente do Key.toString, que retorna uma string legível e adequada para uso em depuração e na geração de registros. Se você precisar de um valor de string que possa ser convertido em uma chave utilizável, use KeyFactory.keyToString.

Observe também que a representação de string de uma chave não é criptografada: um usuário pode decodificar a string da chave para extrair os componentes, incluindo os tipos e identificadores da entidade e seus ancestrais. Se for importante esconder essa informação do usuário, criptografe a string da chave você mesmo antes de enviá-la para ele.