Créer, récupérer, mettre à jour et supprimer des entités

Dans Datastore, les objets de données sont appelés entités. Chacune de ces entités possède un genre spécifique qui la classe dans une catégorie pour les besoins des requêtes. Par exemple, si vous écrivez une application de ressources humaines, vous pouvez représenter chaque employé avec une entité du genre Employee. Sachez que les valeurs de données des entités apparaissent sous la forme de propriétés. Pour en savoir plus sur les entités, consultez la documentation sur les chemins d'accès d'ancêtre et les transactions.

Créer des entités et définir les propriétés

Pour créer et définir une entité, vous devez appeler la méthode constructeur correspondant à sa classe de modèle. Pour en savoir plus sur la création d'une classe de modèle d'entité, consultez Créer et utiliser des classes de modèle d'entité.

L'exemple suivant montre comment appeler un constructeur de classe de modèle à l'aide d'arguments de mot clé :

sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')

Ce code crée un objet dans la mémoire principale de votre programme. Cependant, notez que l'entité disparaît lorsque le processus se termine. Vous devez donc également la faire persister dans Datastore en appelant put(), comme suit :

sandy_key = sandy.put()

Notez que cela renvoie une clé que vous pouvez utiliser pour récupérer l'entité ultérieurement dans Datastore.

Définissez les propriétés en utilisant l'une des options suivantes :

  • Indiquez les propriétés de l'entité au constructeur à l'aide d'arguments de mots clés :
    sandy = Account(
    username='Sandy', userid=123, email='sandy@example.com')
  • Définissez les propriétés manuellement après la création de l'entité :
    sandy = Account()
sandy.username = 'Sandy'
sandy.userid = 123
sandy.email = 'sandy@example.com'
  • Utilisez la méthode pratique populate() pour définir plusieurs propriétés en une seule opération :
    sandy = Account()
sandy.populate(
    username='Sandy',
    userid=123,
    email='sandy@gmail.com')

Quelle que soit la manière dont vous définissez les propriétés de l'entité, les types de propriété (dans ce cas, StringProperty et IntegerProperty) imposent la vérification des types.

Par exemple :

bad = Account(
    username='Sandy', userid='not integer')  # raises an exception
... 
sandy.username = 42  # raises an exception

Récupérer des entités à l'aide des clés

Si vous possédez une clé d'entité, vous pouvez récupérer l'entité à partir de Datastore :

sandy = sandy_key.get()

Les méthodes Key kind() et id() récupèrent le genre et l'identifiant de l'entité à partir de la clé :

kind_string = sandy_key.kind()  # returns 'Account'
ident = sandy_key.id()  # returns '2'

La clé d'une entité peut également vous servir à obtenir une chaîne codée adaptée à l'intégration d'éléments dans une URL :

url_string = sandy_key.urlsafe()

Cette opération produit un résultat semblable à agVoZWxsb3IPCxIHQWNjb3VudBiZiwIM, qui peut ensuite être utilisé pour reconstruire la clé et récupérer l'entité d'origine :

sandy_key = ndb.Key(urlsafe=url_string)
sandy = sandy_key.get()

Vous pouvez constater que la chaîne sécurisée pour les URL semble difficile à déchiffrer, mais elle n'est pas chiffrée ! Elle peut être facilement décodée pour récupérer le genre et l'identifiant de l'entité d'origine :

key = Key(urlsafe=url_string)
kind_string = key.kind()
ident = key.id()

Si vous utilisez des clés sécurisées pour les URL telles que celle-ci, évitez les identifiants basés sur des données sensibles telles que les adresses électroniques. Une solution possible consisterait à utiliser un hachage des données sensibles comme identifiant. Cela empêche les tiers, qui peuvent voir les clés chiffrées, de les utiliser pour collecter des adresses e-mail, mais cela ne les empêche pas de générer indépendamment leur propre hachage d'une adresse e-mail connue pour vérifier ensuite si cette adresse est présente dans Datastore.

Mettre à jour des entités

Pour mettre à jour une entité existante, récupérez-la depuis Datastore, modifiez ses propriétés et stockez-la à nouveau :

sandy = key.get()
sandy.email = 'sandy@example.co.uk'
sandy.put()

Dans ce cas, vous pouvez ignorer la valeur renvoyée par put(), car une clé d'entité ne change pas lorsque vous la mettez à jour.

Supprimer des entités

Lorsqu'une entité n'est plus nécessaire, vous pouvez la supprimer de Datastore avec la méthode delete() de la clé :

sandy.key.delete()

Notez qu'il s'agit d'une opération sur la clé et non pas sur l'entité elle-même. Elle retourne toujours la valeur None.

Suppression groupée d'entités

Si vous devez supprimer un grand nombre d'entités, nous vous recommandons d'utiliser Dataflow pour supprimer ces entités de manière groupée.

Utiliser des opérations par lots

Vous pouvez traiter un ensemble d'entités ou de clés dans un seul appel au lieu de les traiter individuellement dans des appels distincts, par exemple au sein d'une boucle. De cette façon, un seul appel de procédure à distance (RPC) est effectué pour le lot au lieu d'un appel RPC distinct pour chaque entité.

Le code suivant montre comment procéder :

list_of_keys = ndb.put_multi(list_of_entities)
list_of_entities = ndb.get_multi(list_of_keys)
ndb.delete_multi(list_of_keys)

Dans le code ci-dessus, vous transmettez une liste d'objets clés à ndb.get_multi pour récupérer plusieurs entités dans un lot. ndb.get_multi renvoie une liste d'objets d'entité, avec des valeurs None pour les clés qui n'ont pas d'entité correspondante dans Datastore. Cette manière d'obtenir des entités entraîne moins d'appels à Datastore pour l'ensemble du lot. (Le nombre d'appels par lot dépend des paramètres de taille de votre lot.)