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 Java 11/17 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é, indiquez le nom comme deuxième argument du constructeur lors de la création de l'entité :

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

Pour permettre à Datastore d'attribuer automatiquement un ID numérique, omettez cet argument :

Entity employee = new Entity("Employee");

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 les méthodes DatastoreService.allocateIds() ou AsyncDatastoreService.allocateIds(). Le générateur automatique d'ID de Datastore effectue un suivi des ID alloués avec ces méthodes 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é, fournissez la clé de l'entité parente en tant qu'argument au constructeur Entity() lors de la création de l'entité enfant. Vous pouvez obtenir la clé en appelant la méthode getKey() de l'entité parente :

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

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

Si la nouvelle entité possède également un nom de clé, indiquez le nom de clé comme deuxième argument du constructeur Entity() et la clé de l'entité parente comme troisième argument :

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

Générer des clés

Les applications peuvent utiliser la classe KeyFactory afin de créer un objet Key pour une entité à partir de composants connus, tels que le genre et l'identifiant de l'entité. Pour une entité sans parent, transmettez le genre et l'identifiant (chaîne de nom de clé ou ID numérique) à la méthode statique KeyFactory.createKey() pour créer la clé. Les exemples suivants créent une clé pour une entité de genre Person avec le nom de clé "GreatGrandpa" ou l'ID numérique 74219 :

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

Si la clé inclut un composant de chemin, vous pouvez utiliser la classe d'assistance KeyFactory.Builder pour créer le chemin. La méthode addChild de cette classe ajoute une seule entité au chemin et renvoie le générateur lui-même. Vous pouvez ainsi exécuter une série d'appels à la suite, en commençant par l'entité racine, afin de créer le chemin une entité à la fois. Après avoir créé le chemin complet, appelez getKey pour récupérer la clé obtenue :

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

La classe KeyFactory inclut également les méthodes statiques keyToString et stringToKey pour effectuer une conversion entre les clés et leurs représentations sous forme de chaîne :

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

La représentation sous forme de chaîne d'une clé est adaptée au Web : elle ne contient aucun caractère considéré comme spécial en HTML ou dans les URL.

Remarque : La méthode KeyFactory.keyToString est différente de Key.toString, qui renvoie une chaîne lisible adaptée au débogage et à la journalisation. Si vous avez besoin d'une valeur de chaîne pouvant être convertie en clé utilisable, utilisez KeyFactory.keyToString.

Notez également que la représentation de chaîne d'une clé n'est pas chiffrée : un utilisateur peut décoder la chaîne de clé pour en extraire les composants, y compris les genres et les identifiants de l'entité et de ses ancêtres. S'il est important de dissimuler ces informations à l'utilisateur, vous devez chiffrer vous-même la chaîne de clé avant de l'envoyer à l'utilisateur.