Démarrage rapide : Créer une API pour une application Table avec Node.js et Azure Cosmos DB
S’APPLIQUE À : 
Table
Dans ce guide de démarrage rapide, vous allez créer un compte Azure Cosmos DB for Table, puis utiliser l’Explorateur de données et une application Node.js clonée à partir de GitHub pour créer des tables et des entités. Azure Cosmos DB est un service de base de données multimodèle qui vous permet de créer et d’interroger rapidement des bases de données de documents, de tables, de paires clé/valeur et de graphes avec des capacités de distribution mondiale et de mise à l’échelle horizontale.
Prérequis
- Compte Azure avec un abonnement actif. Créez-en un gratuitement.
- Node.js 0.10.29+.
- Git.
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-data-tables-sdk-js. Une application de démarrage et une application terminée sont incluses dans l’exemple de dépôt.
git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-js
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.
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. Pour cela, utilisez 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. Vous pouvez accéder à la page Vue d’ensemble de votre compte Azure Cosmos DB en tapant son nom (cosmos-msdocs-tables-sdk-demo-XYZ) dans la barre de recherche supérieure et en regardant sous l’en-tête des ressources. Sélectionnez le nom de votre compte Azure Cosmos DB pour accéder à la page Vue d’ensemble correspondante. | 
|
| 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îne 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 de développement logiciel (SDK) Azure Data Tables pour JS
Pour accéder à Azure Cosmos DB for Table à partir d’une application nodejs, installez le package Azure Data Tables SDK.
npm install @azure/data-tables
5 – Configurer le client Table dans le fichier env.js
Copiez la chaîne de connexion de votre compte Azure Cosmos DB ou Stockage à partir du portail Azure et créez un objet TableServiceClient à l’aide de la chaîne de connexion copiée. Basculez vers le dossier 1-strater-app ou 2-completed-app. Ajoutez ensuite la valeur des variables d’environnement correspondantes dans le fichier configure/env.js.
const env = {
connectionString:"A connection string to an Azure Storage or Azure Cosmos DB account.",
tableName: "WeatherData",
};
Le kit SDK Azure communique avec Azure à l’aide d’objets de client pour exécuter différentes opérations sur Azure. La classe TableClient est la classe utilisée pour communiquer avec Azure Cosmos DB for Table. En général, une application crée un seul objet serviceClient par table à utiliser dans toute l’application.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
6 – Mettre en œuvre les opérations de table Azure Cosmos DB
Toutes les opérations de table Azure Cosmos DB de l’exemple d’application sont implémentées dans l’objet serviceClient situé dans le fichier tableClient.js, sous le répertoire service.
const { TableClient } = require("@azure/data-tables");
const env = require("../configure/env");
const serviceClient = TableClient.fromConnectionString(
env.connectionString,
env.tableName
);
Obtenir les lignes d’une table
L’objet serviceClient contient une méthode nommée listEntities qui vous permet de sélectionner des lignes de la table. Dans cet exemple, étant donné qu’aucun paramètre n’est passé à la méthode, toutes les lignes sont sélectionnées dans la table.
const allRowsEntities = serviceClient.listEntities();
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 listEntities. 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' and RowKey le '2021-07-02 12:00'
Vous pouvez consulter tous les opérateurs de filtre OData sur le site web OData à la section Filter System Query Option (Filtrer dans l’option de requête système).
Lorsque le paramètre request.args est transmis à la méthode listEntities dans la classe serviceClient, 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 listEntities sur l’objet serviceClient, 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.
const filterEntities = async function (option) {
/*
You can query data according to existing fields
option provides some conditions to query,eg partitionKey, rowKeyDateTimeStart, rowKeyDateTimeEnd
minTemperature, maxTemperature, minPrecipitation, maxPrecipitation
*/
const filterEntitiesArray = [];
const filters = [];
if (option.partitionKey) {
filters.push(`PartitionKey eq '${option.partitionKey}'`);
}
if (option.rowKeyDateTimeStart) {
filters.push(`RowKey ge '${option.rowKeyDateTimeStart}'`);
}
if (option.rowKeyDateTimeEnd) {
filters.push(`RowKey le '${option.rowKeyDateTimeEnd}'`);
}
if (option.minTemperature !== null) {
filters.push(`Temperature ge ${option.minTemperature}`);
}
if (option.maxTemperature !== null) {
filters.push(`Temperature le ${option.maxTemperature}`);
}
if (option.minPrecipitation !== null) {
filters.push(`Precipitation ge ${option.minPrecipitation}`);
}
if (option.maxPrecipitation !== null) {
filters.push(`Precipitation le ${option.maxPrecipitation}`);
}
const res = serviceClient.listEntities({
queryOptions: {
filter: filters.join(" and "),
},
});
for await (const entity of res) {
filterEntitiesArray.push(entity);
}
return filterEntitiesArray;
};
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 mappées aux propriétés PartitionKey et RowKey respectivement, 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 createEntity sur l’objet serviceClient est utilisée pour insérer les données dans la table.
Modifiez la fonction insertEntity de l’exemple d’application pour qu’elle contienne le code suivant.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
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 recevrez une erreur. Ainsi, il est souvent préférable d’utiliser upsertEntity plutôt que la méthode createEntity 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 upsertEntity met à jour la ligne existante. Dans le cas contraire, la ligne est ajoutée à la table.
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
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 createEntity ou upsertEntity sur l’objet serviceClient, si nécessaire.
Dans l’exemple d’application, la fonction upsertEntity peut également implémenter la fonction d’insertion ou d’upsert de données avec des propriétés variables.
const insertEntity = async function (entity) {
await serviceClient.createEntity(entity);
};
const upsertEntity = async function (entity) {
await serviceClient.upsertEntity(entity, "Merge");
};
Mise à jour d'une entité
Les entités peuvent être mises à jour en appelant la méthode updateEntity sur l’objet serviceClient.
Dans l’exemple d’application, cet objet est transmis à la méthode upsertEntity dans l’objet serviceClient. Il met à jour cet objet entité, et utilise la méthode upsertEntity pour enregistrer les mises à jour dans la base de données.
const updateEntity = async function (entity) {
await serviceClient.updateEntity(entity, "Replace");
};
7 – Exécuter le code
Exécutez l’exemple d’application pour interagir avec Azure Cosmos DB for Table. 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.
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 effectuez cette opération 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.