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 Go 1.12+ 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 um argumento stringID não vazio para datastore.NewKey:

// Create a key with a key name "asalieri".
key := datastore.NewKey(
	ctx,        // context.Context
	"Employee", // Kind
	"asalieri", // String ID; empty means no string ID
	0,          // Integer ID; if 0, generate automatically. Ignored if string ID specified.
	nil,        // Parent Key; nil means no parent
)

Para permitir que o Datastore atribua um ID numérico automaticamente, use um argumento stringID vazio:

// Create a key such as Employee:8261.
key := datastore.NewKey(ctx, "Employee", "", 0, nil)
// This is equivalent:
key = datastore.NewIncompleteKey(ctx, "Employee", nil)

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 a função datastore.AllocateIDs. O gerador de ID automático do Datastore irá monitorar os IDs alocados com essas funções 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 o pai de uma entidade, use o argumento parent para datastore.NewKey. O valor desse argumento precisa ser a chave da entidade pai. O exemplo a seguir cria uma entidade do tipo Address e designa uma entidade Employee como pai:

// Create Employee entity
employee := &Employee{ /* ... */ }
employeeKey, err := datastore.Put(ctx, datastore.NewIncompleteKey(ctx, "Employee", nil), employee)

// Use Employee as Address entity's parent
// and save Address entity to datastore
address := &Address{ /* ... */ }
addressKey := datastore.NewIncompleteKey(ctx, "Address", employeeKey)
_, err = datastore.Put(ctx, addressKey, address)