Créer et utiliser des clés d'entité

Cette API est compatible avec les environnements d'exécution de première génération et peut être utilisée lors de la mise à niveau vers des environnements d'exécution de deuxième génération correspondants. Si vous effectuez une mise à jour vers l'environnement d'exécution Go 1.12+ d'App Engine, consultez le guide de migration pour en savoir plus sur les options de migration des anciens services groupés.

Chaque entité dans Datastore possède une clé qui l'identifie de manière unique. Cette clé comprend les composants suivants :

• L'espace de noms de l'entité, qui permet de définir l'architecture mutualisée.
• Le genre de l'entité, qui permet de classer celle-ci pour les besoins des requêtes Datastore.
• Un chemin d'ancêtre facultatif localisant l'entité dans la hiérarchie Datastore.

• Un identifiant associé à l'entité de manière individuelle, qui peut être :

  • une chaîne de nom de clé ;
  • un ID numérique sous forme d'entier.

Comme il fait partie de la clé de l'entité, l'identifiant est associé de manière permanente à celle-ci et ne peut pas être modifié. Il peut être attribué de deux manières :

• Spécifiez votre propre chaîne de nom de clé pour l'entité.
• Laissez Datastore attribuer automatiquement à l'entité un ID numérique entier.

Ne nommez aucune propriété "key". Ce nom est réservé à une propriété spéciale permettant de stocker la clé de modèle. Bien qu'elle puisse fonctionner en local, une propriété nommée "key" empêche le déploiement sur App Engine.

Spécifier un nom de clé pour une entité

Pour attribuer un nom de clé à une entité, fournissez un argument stringID non vide à 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
)

Pour que Cloud Datastore attribue un ID numérique automatiquement, employez un argument stringID vide :

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

Attribuer des identifiants

Vous pouvez configurer Datastore pour générer des ID automatiques à l'aide de deux règles d'ID automatique différentes :

• La règle default génère une séquence aléatoire d'ID inutilisés distribués d'une manière approximativement uniforme. Chaque ID peut comporter jusqu'à 16 chiffres décimaux.
• La règle legacy crée une séquence d'ID entiers plus petits non consécutifs.

Si vous souhaitez que les ID d'entité soient visibles par l'utilisateur et/ou si vous souhaitez les afficher en fonction de leur ordre, l'allocation manuelle est la meilleure solution.

Remarque : Au lieu d'employer des chaînes de nom de clé ou de générer automatiquement des ID numériques, les applications avancées peuvent parfois souhaiter attribuer manuellement leurs propres ID numériques aux entités créées. Sachez toutefois que rien n'empêche Datastore d'attribuer l'un de vos ID numériques manuels à une autre entité. Le seul moyen d'éviter de tels conflits est que votre application obtienne un bloc d'ID avec la fonction datastore.AllocateIDs. Le générateur automatique d'ID de Cloud Datastore effectue un suivi des ID alloués avec cette fonction et évite de les réutiliser pour une autre entité. Vous pouvez ainsi employer ces ID sans que cela ne génère de conflit.

Utiliser les chemins d'ancêtres

Dans Cloud Datastore, les entités forment un espace structuré de manière hiérarchique, semblable à la structure de répertoires d'un système de fichiers. Lorsque vous créez une entité, vous pouvez éventuellement en désigner une autre comme son parent. La nouvelle entité est alors un enfant de l'entité parente. Contrairement à ce qui se produit dans un système de fichiers, l'entité parente n'a pas besoin d'exister réellement. Une entité sans parent est une entité racine. L'association entre une entité et son parent est permanente, et elle ne peut plus être modifiée une fois l'entité créée. Cloud Datastore n'attribue jamais le même ID numérique à deux entités ayant le même parent ou à deux entités racines (celles sans parent).

Les ancêtres d'une entité correspondent à son parent, au parent de son parent et ainsi de suite, de manière récursive. Ses descendants sont ses enfants, les enfants de ses enfants, etc. Une entité racine et tous ses descendants appartiennent au même groupe d'entités. La séquence d'entités commençant par une entité racine, puis allant du parent à l'enfant et menant à une entité donnée, constitue le chemin d'ancêtre de cette entité. La clé complète identifiant l'entité consiste en une séquence de paires genre/identifiant, qui spécifie son chemin d'ancêtre et se termine par les valeurs de l'entité elle-même :

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

Pour une entité racine, le chemin d'ancêtre est vide, et la clé est constituée uniquement du genre et de l'identifiant de l'entité :

[Person:GreatGrandpa]

Le schéma suivant illustre ce concept :

Pour désigner le parent d'une entité, utilisez l'argument parent pour datastore.NewKey. La valeur de cet argument doit être la clé de l'entité parente. L'exemple suivant crée une entité du genre Address et désigne comme parent une entité Employee :

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