Démarrage rapide : Créer une application API pour Table avec le kit SDK Python et Azure Cosmos DB
S’APPLIQUE À : 
Table
Ce guide de démarrage rapide montre comment accéder à l’API pour Table Azure Cosmos DB à partir d’une application Python. Azure Cosmos DB for Table est un magasin de données sans schéma qui permet aux applications de stocker des données NoSQL structurées dans le cloud. Étant donné que les données sont stockées dans une conception sans schéma, de nouvelles propriétés (colonnes) sont automatiquement ajoutées à la table lorsqu’un objet doté d’un nouvel attribut est ajouté à la table. Les applications Python peuvent accéder à Azure Cosmos DB for Table à l’aide du package SDK Azure Data Tables pour Python.
Prérequis
L’exemple d’application est écrit en Python 3.7 ou version ultérieure, bien que les principes s’appliquent à toutes les applications Python 3.7+. Vous pouvez utiliser Visual Studio Code comme environnement de développement intégré.
Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.
Exemple d’application
L’exemple d’application de ce tutoriel peut être cloné ou téléchargé à partir du dépôt https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.
git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git
Un dossier d’exemple 1-starter-app et 2-completed-app sont inclus dans l’exemple de dépôt. 1-starter-app laisse quelques fonctionnalités vides, que vous pourrez compléter, avec des lignes marquées « #TODO ». Les extraits de code présentés dans cet article sont les ajouts suggérés pour terminer la 1-starter-app.
L’exemple d’application utilise des données météorologiques comme modèle pour illustrer les fonctionnalités de l’API Table. Les objets représentant les observations météorologiques sont stockés et récupérés à l’aide de l’API Table, entre autres le stockage d’objets avec des propriétés supplémentaires pour mettre en évidence les fonctionnalités sans schéma de l’API Table. L’image suivante montre l’application locale en cours d’exécution dans un navigateur, affichant les données météorologiques stockées dans Azure Cosmos DB for Table.
1 – Créer un compte Azure Cosmos DB
Vous devez d’abord créer un compte API Tables Azure Cosmos DB qui contiendra la ou les tables utilisées dans votre application. Créez un compte avec le Portail Azure, Azure CLI ou Azure PowerShell.
Connectez-vous au portail Azure et suivez ces étapes pour créer un compte Azure Cosmos DB.
| Instructions | Capture d'écran |
|---|---|
Dans le portail Azure :
|
|
| Dans la page Azure Cosmos DB, sélectionnez +Créer. | 
|
| Sur la page Sélectionner l'option API, choisissez l'option Azure Table. | 
|
Dans la page Créer un compte Azure Cosmos DB : tableau Azure, remplissez le formulaire comme suit.
|
|
2 – Créer une table
Ensuite, vous devez créer une table dans votre compte Azure Cosmos DB, qui servira à votre application. Contrairement à une base de données classique, il vous suffit de spécifier le nom de la table, et non les propriétés (colonnes) de la table. À mesure que les données sont chargées dans votre table, les propriétés (colonnes) sont automatiquement créées en fonction des besoins.
Dans le portail Azure, effectuez les étapes suivantes pour créer une table dans votre compte Azure Cosmos DB.
| Instructions | Capture d'écran |
|---|---|
Dans le portail Azure, accédez à la page Vue d’ensemble du compte Azure Cosmos DB.
|
|
| Dans la page Vue d’ensemble, sélectionnez + Ajouter une table. La boîte de dialogue Nouveau tableau sort du côté droit de la page. | 
|
Dans la boîte de dialogue Nouvelle table, remplissez le formulaire comme ci-dessous.
|
|
3 - Obtenir la chaîne de connexion Azure Cosmos DB
Pour accéder à une de vos tables dans Azure Cosmos DB, votre application a besoin de la chaîne de connexion de la table pour le compte de stockage CosmosDB. La chaîne de connexion peut être récupérée à l’aide du portail Azure, de l’interface Azure CLI ou d’Azure PowerShell.
| Instructions | Capture d'écran |
|---|---|
| Sur le côté gauche de la page du compte Azure Cosmos DB, localisez l'élément de menu nommé Chaînes de connexion sous l'en-tête Paramètres et sélectionnez-le. Vous êtes alors dirigé vers une page où vous pouvez récupérer la chaîne de connexion pour le compte Azure Cosmos DB. | 
|
| Copiez la valeur PRIMARY CONNECTION STRING à utiliser dans votre application. | 
|
4 - Installer le kit SDK Azure Data Tables pour Python
Une fois que vous avez créé un compte Azure Cosmos DB, l’étape suivante consiste à installer le kit SDK Azure Data Tables pour Python de Microsoft. Pour plus de détails sur l’installation du SDK, consultez le fichier README.md dans le dépôt SDK Data Tables pour Python sur GitHub.
Installez la bibliothèque de client Azure Tables pour Python avec pip :
pip install azure-data-tables
N’oubliez pas d’installer également le fichier requirements.txt dans les dossiers 1-starter-app ou 2-completed-app .
5 – Configurer le client Table dans le fichier .env
Copiez la chaîne de connexion de votre compte Azure Cosmos DB à partir du portail Azure et créez un objet TableServiceClient en utilisant la chaîne de connexion copiée. Basculez vers le dossier 1-starter-app ou 2-completed-app. Quelle que soit l’application avec laquelle vous commencez, vous devez définir des variables d’environnement dans un fichier .env.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Le kit SDK Azure communique avec Azure à l’aide d’objets de client pour exécuter différentes opérations sur Azure. L’objet TableServiceClient est l’objet utilisé pour communiquer avec Azure Cosmos DB for Table. Une application a généralement un seul TableServiceClient dans l’ensemble, et un TableClient par table.
Par exemple, le code suivant crée un objet TableServiceClient à l’aide de la chaîne de connexion de la variable d’environnement.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 – Mettre en œuvre les opérations de table Azure Cosmos DB
Toutes les opérations de table Azure Cosmos DB pour l’exemple d’application sont implémentées dans la classe TableServiceHelper située dans le fichier helper sous le répertoire webapp. Vous devez importer la classe TableServiceClient en haut de ce fichier pour pouvoir utiliser des objets dans la bibliothèque de client azure.data.tables pour Python.
from azure.data.tables import TableServiceClient
Au début de la classe TableServiceHelper, créez un constructeur et ajoutez une variable membre pour l’objet TableClient afin de permettre l’injection de l’objet TableClient dans la classe.
def __init__(self, table_name=None, conn_str=None):
self.table_name = table_name if table_name else os.getenv("table_name")
self.conn_str = conn_str if conn_str else os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
self.table_client = self.table_service.get_table_client(self.table_name)
Filtrer les lignes retournées à partir d’une table
Pour filtrer les lignes retournées à partir d’une table, vous pouvez transmettre une chaîne de filtre de style OData à la méthode query_entities. Par exemple, si vous souhaitez obtenir tous les relevés météorologiques pour Chicago entre le 1er juillet 2021 et le 2 juillet 2021 (inclus), vous devez passer la chaîne de filtre suivante.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
Vous pouvez afficher les opérateurs de filtre OData associés sur le site web azure-data-tables dans la section Écriture de filtres.
Lorsque le paramètre request.args est transmis à la méthode query_entity dans la classe TableServiceHelper, il crée une chaîne de filtre pour chaque valeur de propriété qui n’est pas Null. Il crée ensuite une chaîne de filtre combinée en joignant toutes les valeurs avec une clause « and ». Cette chaîne de filtre combinée est transmise à la méthode query_entities sur l’objet TableClient, et seules les lignes correspondant à la chaîne de filtre sont retournées. Vous pouvez utiliser une méthode similaire dans votre code pour élaborer des chaînes de filtre appropriées en fonction des besoins de votre application.
def query_entity(self, params):
filters = []
if params.get("partitionKey"):
filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
if params.get("minTemperature"):
filters.append("Temperature ge {}".format(params.get("minTemperature")))
if params.get("maxTemperature"):
filters.append("Temperature le {}".format(params.get("maxTemperature")))
if params.get("minPrecipitation"):
filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
if params.get("maxPrecipitation"):
filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
return list(self.table_client.query_entities(" and ".join(filters)))
Insérer les données à l’aide d’un objet TableEntity
Le moyen le plus simple d’ajouter des données à une table consiste à utiliser un objet TableEntity. Dans cet exemple, les données sont mappées à partir d’un objet de modèle d’entrée sur un objet TableEntity. Les propriétés de l’objet d’entrée représentant le nom de la station météo et la date/l’heure de l’observation sont respectivement mappées aux propriétés PartitionKey et RowKey, formant ensemble une clé unique pour la ligne de la table. Ensuite, les propriétés supplémentaires sur l’objet de modèle d’entrée sont mappées aux propriétés de dictionnaire sur l’objet TableEntity. Enfin, la méthode create_entity sur l’objet TableClient est utilisée pour insérer les données dans la table.
Modifiez la fonction insert_entity de l’exemple d’application pour qu’elle contienne le code suivant.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Faire un upsert des données à l’aide d’un objet TableEntity
Si vous essayez d’insérer une ligne dans une table avec une combinaison clé de partition/clé de ligne qui existe déjà dans cette table, vous recevez une erreur. Ainsi, il est souvent préférable d’utiliser upsert_entity plutôt que la méthode create_entity lors de l’ajout de lignes à une table. Si la combinaison clé de partition/clé de ligne déterminée existe déjà dans la table, la méthode upsert_entity met à jour la ligne existante. Dans le cas contraire, la ligne est ajoutée à la table.
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Insérer ou faire un upsert des données avec des propriétés de variable
Un des avantages de l’utilisation d’Azure Cosmos DB for Table réside dans le fait que si un objet chargé dans une table contient des propriétés nouvelles, ces propriétés sont automatiquement ajoutées à la table, et les valeurs stockées dans Azure Cosmos DB. Il n’est pas nécessaire d’exécuter des instructions DDL, telles que ALTER TABLE, pour ajouter des colonnes, comme c’est le cas dans une base de données classique.
Ce modèle offre de la flexibilité à votre application lors de la gestion de sources de données pouvant ajouter ou modifier des éléments nécessaires aux données pour leur capture au fil du temps, ou lorsque plusieurs entrées fournissent différentes données à votre application. Dans l’exemple d’application, nous pouvons simuler une station météorologique qui envoie non seulement les données météorologiques de base, mais également quelques valeurs supplémentaires. Lorsqu’un objet doté de ces nouvelles propriétés est stocké dans la table pour la première fois, les propriétés correspondantes (colonnes) sont automatiquement ajoutées à la table.
Pour insérer un tel objet ou en faire un upsert à l’aide de l’API pour Table, mappez les propriétés de l’objet extensible dans un objet TableEntity et utilisez les méthodes create_entity ou upsert_entity sur l’objet TableClient, si nécessaire.
Dans l’exemple d’application, la fonction upsert_entity peut également implémenter la fonction d’insertion ou d’upsert de données avec des propriétés variables.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Mise à jour d'une entité
Les entités peuvent être mises à jour en appelant la méthode update_entity sur l’objet TableClient.
Dans l’exemple d’application, cet objet est passé à la méthode upsert_entity dans la classe TableClient. Il met à jour cet objet entité, et utilise la méthode upsert_entity pour enregistrer les mises à jour dans la base de données.
def update_entity(self):
entity = self.update_deserialize()
return self.table_client.update_entity(entity)
@staticmethod
def update_deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = params.pop("ObservationDate")
return params
Supprimer une entité
Pour supprimer une entité d’une table, appelez la méthode delete_entity sur l’objet TableClient avec la clé de partition et la clé de ligne de l’objet.
def delete_entity(self):
partition_key = request.form.get("StationName")
row_key = request.form.get("ObservationDate")
return self.table_client.delete_entity(partition_key, row_key)
7 – Exécuter le code
Exécutez l’exemple d’application pour interagir avec Azure Cosmos DB for Table. Par exemple, à partir du dossier 2-completed-app, avec la configuration requise installée, vous pouvez utiliser :
python3 run.py webapp
Pour plus d’informations sur l’exécution de l’exemple d’application, consultez le fichier README.md à la racine de l’exemple de dépôt.
La première fois que vous exécuterez l’application, il n’y aura aucune donnée affichée, car la table est vide. Utilisez l’un des boutons situés en haut de l’application pour ajouter des données à la table.
En sélectionnant le bouton Insert using Table Entity (Insérer à l’aide d’une entité de table), vous ouvrez une boîte de dialogue dans laquelle vous pouvez insérer une nouvelle ligne ou en faire un upsert en utilisant un objet TableEntity.
La sélection du bouton Insert using Expandable Data (Insérer à l’aide de données extensibles) affiche une boîte de dialogue qui vous permet d’insérer un objet avec des propriétés personnalisées, illustrant ainsi comment Azure Cosmos DB for Table ajoute automatiquement des propriétés (colonnes) à la table, si nécessaire. Utilisez le bouton Add Custom Field (Ajouter un champ personnalisé) pour ajouter une ou plusieurs nouvelles propriétés et illustrer cette fonctionnalité.
Utilisez le bouton Insert Sample Data (Insérer des exemples de données) pour charger des exemples de données dans votre table Azure Cosmos DB.
Pour l’exemple de dossier 1-starter-app, vous devez au moins terminer le code de la fonction
submit_transactionpour que l’exemple d’insertion de données fonctionne.Les exemples de données sont chargés à partir d’un fichier sample_data.json. La variable .env
project_root_pathindique à l’application où trouver ce fichier. Par exemple, si vous exécutez l’application à partir du dossier 1-starter-app ou 2-completed-app, définissezproject_root_pathsur « » (vide).
Sélectionnez l’élément Filter Results (Filtrer les résultats) dans le menu supérieur pour atteindre la page de filtre des résultats. Dans cette page, renseignez les critères de filtre pour démontrer comment une clause de filtre peut être générée et transmise à Azure Cosmos DB for Table.
Nettoyer les ressources
Lorsque vous n’avez plus besoin de l’exemple d’application, supprimez de votre compte Azure toutes les ressources Azure associées à cet article. Vous pouvez supprimer toutes les ressources en supprimant le groupe de ressources.
Il est possible de supprimer un groupe de ressources dans le portail Azure en procédant comme indiqué ici.
| Instructions | Capture d'écran |
|---|---|
| Pour accéder au groupe de ressources, dans la barre de recherche, tapez le nom du groupe de ressources. Ensuite, sous l’onglet Groupes de ressources, sélectionnez le nom du groupe de ressources. | 
|
| Sélectionnez Supprimer un groupe de ressources dans la barre d’outils en haut de la page Groupes de ressources. | 
|
Une boîte de dialogue s’affiche à droite de l’écran vous demandant de confirmer la suppression du groupe de ressources.
|
|
Étapes suivantes
Dans ce guide de démarrage rapide, vous avez appris à créer un compte Azure Cosmos DB, à créer une table à l’aide de l’Explorateur de données, et à exécuter une application. Maintenant, vous pouvez interroger vos données à l’aide de l’API pour Table.