Remarque : Python 2.7 n'est plus compatible à partir du 31 janvier 2024. Vos applications Python 2.7 existantes continueront à fonctionner et à recevoir du trafic. Toutefois, App Engine peut bloquer le redéploiement des applications qui utilisent des environnements d'exécution après leur date de fin de compatibilité. Nous vous recommandons de migrer vers la dernière version compatible de Python.

La classe Key

Remarque : Les développeurs qui créent des applications sont vivement encouragés à utiliser la bibliothèque cliente NDB qui présente plusieurs avantages supplémentaires par rapport à cette bibliothèque cliente, tels que la mise en cache automatique des entités via l'API Memcache. Si vous utilisez actuellement l'ancienne bibliothèque cliente DB, consultez le guide de migration de DB vers NDB.

Une instance de la classe Key représente une clé unique correspondant à une entité Datastore.

La classe Key est fournie par le module google.appengine.ext.db.

Présentation

Chaque instance de modèle possède une clé d'identification, qui inclut le genre d'entité de l'instance ainsi qu'un identifiant unique. L'identifiant peut correspondre à une chaîne de nom de clé, attribuée explicitement par l'application lors de la création de l'instance, ou à un ID numérique entier, attribué automatiquement par App Engine lorsque l'instance est écrite (à l'aide de la méthode put) dans le datastore. La méthode key() de l'instance de modèle renvoie l'objet Key de l'instance. Si aucune clé n'a été attribuée à l'instance, key() génère une erreur NotSavedError.

Une application peut récupérer une instance de modèle associée à un objet Key donné à l'aide de la fonction get().

Les instances de la classe Key peuvent être des valeurs de propriétés d'entités Datastore, y compris des propriétés dynamiques Expando et des membres ListProperty. Le modèle ReferenceProperty propose des fonctionnalités pour les valeurs de propriétés Key, telles que le déréférencement automatique.

Constructeur

class Key(encoded=None)

Clé unique d'un objet Datastore.

Il est possible de convertir une clé en chaîne en transmettant l'objet Key à str(). La chaîne est sécurisée pour les URL : elle n'utilise que des caractères valides dans les URL. Vous pouvez également reconvertir la représentation sous forme de chaîne de la clé en un objet Key en la transmettant au constructeur Key (l'argument encoded).

Remarque : La chaîne d'une clé semble difficile à lire, mais elle n'est pas chiffrée. Elle peut être reconvertie en données de clé brutes, avec le genre et l'identifiant. Si vous ne souhaitez exposer ces données à vos utilisateurs (pour éviter qu'ils devinent facilement les clés d'autres entités), chiffrez ces chaînes ou utilisez une autre méthode.

encoded: Forme str d'une instance de la classe Key à reconvertir en objet Key.

Méthodes des classes

La classe Key fournit la méthode de classe suivante :

Key.from_path(*path, parent=None, namespace=None)

Crée un objet Key à partir d'un chemin d'accès ancêtre facultatif (dans un objet Key existant) et d'un ou plusieurs nouveaux composants de chemin. Chaque composant de chemin comporte un nom de genre (kind) et un identifiant (id_or_name), qui peut être un nombre ou une chaîne de caractères.

Un chemin d'accès représente la hiérarchie des relations parent-enfant d'une entité. Chaque entité du chemin d'accès est représentée par son genre, ainsi que par son ID numérique ou son nom de clé. Le chemin d'accès complet représente l'entité, qui apparaît en dernier dans le chemin d'accès, avec ses ancêtres (parents), qui correspondent aux entités précédentes.

Par exemple, l'appel suivant crée un objet Key pour une entité de genre Address avec l'ID numérique 9876, sous la clé parente User/Boris :

k = Key.from_path('User', 'Boris', 'Address', 9876)

Vous pouvez également créer cet objet Key à l'aide de l'appel suivant :

p1 = Key.from_path('User', 'Boris')
k = Key.from_path('Address', 9876, parent=p1)

Pour en savoir plus sur les chemins d'accès, consultez la page Entités, propriétés et clés.

Arguments

path

Liste des composants de chemin d'ancêtre, chaque composant étant constitué d'un genre et d'un identifiant :

Genre : genre de l'entité, représenté sous forme de chaîne ou de chaîne Unicode
Identifiant : id spécifié sous forme de chaîne ou d'objet long. L'ID ne peut pas correspondre au chiffre 0.

namespace=None

Espace de noms à définir pour cet objet Key uniquement. Si vous fournissez un espace de noms ici, il remplace l'espace de noms actuel défini dans namespace_manager. Si la valeur None est spécifiée, l'API utilise l'espace de noms actuel de namespace_manager.get_namespace.

parent=None

Clé parente facultative. Si vous ne fournissez aucune valeur, la valeur par défaut est None.

Méthodes des instances

Les méthodes des instances de la classe Key sont les suivantes :

app(): Renvoie le nom de l'application qui a stocké l'entité de données.
has_id_or_name(): Renvoie True si l'entité a un nom ou un identifiant numérique.
id(): Renvoie l'identifiant numérique de l'entité de données, sous forme d'entier, ou None si l'entité n'a pas d'identifiant numérique.
id_or_name(): Renvoie le nom ou l'identifiant numérique de l'entité de données, selon le cas, ou None si l'entité ne possède ni nom ni identifiant numérique.
kind(): Renvoie le kind de l'entité de données, sous forme de chaîne.
name(): Renvoie le nom de l'entité de données, ou None si l'entité n'a pas de nom.
namespace(): Renvoie l'espace de noms de l'entité de données. Si l'entité ne dispose d'aucun espace de noms, cette méthode renvoie l'espace de noms actuel défini dans namespace_manager.
parent(): Renvoie l'objet Key de l'entité parente de l'entité de données, ou None si l'entité n'a pas de parent.