Criar e usar chaves de entidades

Esta API é suportada para runtimes de primeira geração e pode ser usada quando atualizar para runtimes de segunda geração correspondentes. Se estiver a fazer a atualização para o tempo de execução do App Engine Java 11/17, consulte o guia de migração para saber mais sobre as suas opções de migração para serviços agrupados antigos.

Cada entidade no Datastore tem uma chave que a identifica de forma exclusiva. A chave é composta pelos seguintes componentes:

• O espaço de nomes da entidade, que permite a multilocação
• O tipo da entidade, que a categoriza para efeitos de consultas do Datastore
• Um caminho de antepassados opcional que localiza a entidade na hierarquia do Datastore.

• Um identificador para a entidade individual, que pode ser

  • Uma string de nome da chave
  • um ID numérico inteiro

Uma vez que o identificador faz parte da chave da entidade, o identificador está associado permanentemente à entidade e não pode ser alterado. Atribui o identificador de uma das seguintes formas:

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

Não atribua o nome "chave" a uma propriedade. Este nome está reservado para uma propriedade especial usada para armazenar a chave do modelo. Embora possa funcionar localmente, uma propriedade com o nome "key" impede a implementação no App Engine.

Especificar um nome de chave para uma entidade

Para atribuir um nome de chave a uma entidade, indique o nome como o segundo argumento do construtor quando criar a entidade:

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

Para permitir que o Datastore atribua um ID numérico automaticamente, omita este argumento:

Entity employee = new Entity("Employee");

Atribuir identificadores

Pode configurar o Datastore para gerar IDs automáticos através de duas políticas de IDs automáticos diferentes:

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

Se quiser apresentar os IDs das entidades ao utilizador e/ou depender da respetiva ordem, a melhor opção é usar a atribuição manual.

Nota: em vez de usar strings de nomes de chaves ou gerar IDs numéricos automaticamente, as aplicações avançadas podem, por vezes, querer atribuir os seus próprios IDs numéricos manualmente às entidades que criam. No entanto, tenha em atenção que não existe nada que impeça o Datastore de atribuir um dos seus IDs numéricos manuais a outra entidade. A única forma de evitar estes conflitos é a sua aplicação obter um bloco de IDs com os métodos DatastoreService.allocateIds() ou AsyncDatastoreService.allocateIds(). O gerador de IDs automático do Datastore acompanha os IDs que foram atribuídos com estes métodos e evita reutilizá-los para outra entidade, pelo que pode usar esses IDs em segurança sem conflitos.

Usar caminhos de ascendentes

As entidades no Cloud Datastore formam um espaço estruturado hierarquicamente semelhante à estrutura de diretórios de um sistema de ficheiros. Quando cria uma entidade, pode, opcionalmente, designar outra entidade como respetiva principal. A nova entidade é uma secundária da entidade principal (tenha em atenção que, ao contrário de um sistema de ficheiros, a entidade principal não tem de existir efetivamente). Uma entidade sem um elemento principal é uma entidade raiz. A associação entre uma entidade e a respetiva entidade principal é permanente e não pode ser alterada depois de a entidade ser criada. O Cloud Datastore nunca atribui o mesmo ID numérico a duas entidades com o mesmo elemento principal ou a duas entidades raiz (as que não têm um elemento principal).

O principal de uma entidade, o principal do principal e assim sucessivamente, são os seus ancestrais; os seus secundários, os secundários dos secundários e assim sucessivamente, são os seus descendentes. Uma entidade raiz e todos os respetivos descendentes pertencem ao mesmo grupo de entidades. A sequência de entidades que começa com uma entidade de raiz e prossegue do elemento principal para o elemento secundário, conduzindo a uma determinada entidade, constitui o caminho do antepassado dessa entidade. A chave completa que identifica a entidade consiste numa sequência de pares de tipo-identificador que especificam o respetivo caminho de antepassados e terminam com os da própria entidade:

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

Para uma entidade raiz, o caminho de antepassados está vazio e a chave consiste apenas no tipo e no identificador da própria entidade:

[Person:GreatGrandpa]

Este conceito é ilustrado pelo diagrama seguinte:

Para designar o elemento principal de uma entidade, forneça a chave do elemento principal como um argumento para o construtor Entity() ao criar a entidade secundária. Pode obter a chave chamando o método getKey() da entidade principal:

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 principal, forneça o nome principal como o segundo argumento para o construtor Entity() e a chave da entidade principal como o terceiro argumento:

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

Gerar chaves

As aplicações 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. Para uma entidade sem principal, transmita o tipo e o identificador (uma string de nome de chave ou um ID numérico) para o método estático KeyFactory.createKey() para criar a chave. Os exemplos seguintes criam uma chave para uma entidade do tipo Person com o nome da 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, pode usar a classe auxiliar KeyFactory.Builder para criar o caminho. O método addChild desta classe adiciona uma única entidade ao caminho e devolve o próprio criador, para que possa encadear uma série de chamadas, começando pela entidade raiz, para criar o caminho uma entidade de cada vez. Depois de criar o caminho completo, chame getKey para obter 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 respetivas representações de strings:

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 a Web": não contém carateres considerados especiais em HTML ou em URLs.

Nota: o método KeyFactory.keyToString é diferente de Key.toString, que devolve uma string legível por humanos adequada para utilização na depuração e no registo. Se precisar de um valor de string que possa ser convertido numa chave utilizável, use KeyFactory.keyToString.

Tenha também em atenção que a representação de string de uma chave não é encriptada: um utilizador pode descodificar a string da chave para extrair os respetivos componentes, incluindo os tipos e os identificadores da entidade e dos respetivos antecessores. Se for importante ocultar estas informações do utilizador, tem de encriptar a string da chave antes de a enviar ao utilizador.