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 atualizar para o tempo de execução do App Engine Go 1.12 ou superior, 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, forneça um argumento stringID não vazio a 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 automaticamente um ID numérico, 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)

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 é fazer com que a sua aplicação obtenha um bloco de IDs com a função datastore.AllocateIDs. O gerador de IDs automático do Datastore acompanha os IDs que foram atribuídos com esta função 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 principal de uma entidade, use o argumento parent para datastore.NewKey. O valor deste argumento deve ser a chave da entidade principal. O exemplo seguinte cria uma entidade do tipo Address e designa uma entidade Employee como respetiva principal:

// 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)