Bien démarrer avec Azure Cosmos DB for NoSQL à l’aide de Javascript

  • Article

S’APPLIQUE À : NoSQL

Cet article vous montre comment vous connecter à Azure Cosmos DB for NoSQL à l’aide du SDK JavaScript. Une fois connecté, vous pouvez effectuer des opérations sur des bases de données, des conteneurs et des éléments.

Package (npm) | Exemples | Référence API | Code source de la bibliothèque | Envoyer des commentaires

Prérequis

Configurez votre projet local

  1. Créez un répertoire pour votre projet JavaScript dans un interpréteur de commandes bash.

    mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples

  2. Créez une application JavaScript à l’aide de la commande npm init avec le modèle de console.

    npm init -y

  3. Installez la dépendance requise pour le Kit de développement logiciel (SDK) JavaScript Azure Cosmos DB for NoSQL.

    npm install @azure/cosmos

Se connecter à Azure Cosmos DB for NoSQL

Pour vous connecter à l’API pour NoSQL de Azure Cosmos DB, créez une instance de la classe CosmosClient. Cette classe est le point de départ pour effectuer toutes les opérations sur des bases de données. Il existe trois façons principales de se connecter à un compte d’API pour NoSQL à l’aide de la classe CosmosClient :

Se connecter avec un point de terminaison et une clé

Le constructeur le plus courant pour CosmosClient a deux paramètres :

Paramètre Valeur d'exemple Description
accountEndpoint COSMOS_ENDPOINT variable d’environnement Point de terminaison d’API for NoSQL à utiliser pour toutes les requêtes
authKeyOrResourceToken COSMOS_KEY variable d’environnement Clé de compte ou jeton de ressource à utiliser lors de l’authentification

Récupérer le point de terminaison et la clé de votre compte

  1. Créez une variable d’interpréteur de commandes pour resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-javascript-howto-rg"

  2. Utilisez la commande az cosmosdb list pour récupérer le nom du premier compte Azure Cosmos DB dans votre groupe de ressources et le stocker dans la variable d’interpréteur de commandes accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. Obtenez l’URI de point de terminaison d’API for NoSQL pour le compte à l’aide de la commande az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Recherchez la CLÉ PRIMAIRE dans la liste des clés du compte avec la commande az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Enregistrez les valeurs URI et CLÉ PRIMAIRE. Vous aurez besoin de ces informations d’identification ultérieurement.

Pour utiliser les valeurs URI et CLÉ PRIMAIRE dans votre code, conservez-les dans de nouvelles variables d’environnement sur l’ordinateur local exécutant l’application.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Créer CosmosClient avec un point de terminaison de compte et une clé

Créez une instance de la classe CosmosClient avec les variables d’environnement COSMOS_ENDPOINT et COSMOS_KEY en tant que paramètres.

const client = new CosmosClient({ endpoint, key });

Se connecter avec une chaîne de connexion

Un autre constructeur pour CosmosClient ne contient qu’un seul paramètre :

Paramètre Valeur d'exemple Description
accountEndpoint COSMOS_ENDPOINT variable d’environnement Point de terminaison d’API for NoSQL à utiliser pour toutes les requêtes
connectionString COSMOS_CONNECTION_STRING variable d’environnement Chaîne de connexion au compte d’API for NoSQL

Récupérer votre chaîne de connexion de compte

  1. Utilisez la commande az cosmosdb list pour récupérer le nom du premier compte Azure Cosmos DB dans votre groupe de ressources et le stocker dans la variable d’interpréteur de commandes accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Recherchez la CHAÎNE DE CONNEXION PRIMAIRE dans la liste des chaînes de connexion pour le compte avec la commande az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Pour utiliser la valeur CHAÎNE DE CONNEXION PRIMAIRE dans votre code, conservez-la dans une nouvelle variable d’environnement sur l’ordinateur local exécutant l’application.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Créer CosmosClient avec une chaîne de connexion

Créez une instance de la classe CosmosClient avec les variables d’environnement COSMOS_CONNECTION_STRING en tant que seul paramètre.

// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);

Se connecter à l’aide de la plateforme d’identités Microsoft

Pour vous connecter à votre compte d’API for NoSQL à l’aide de la plateforme d’identités Microsoft et de Microsoft Entra ID, utilisez un principal de sécurité. Le type exact de principal dépend de l’emplacement où vous hébergez votre code d’application. Le tableau ci-dessous sert de guide de référence rapide.

Emplacement d’exécution de l’application Principal de sécurité
Ordinateur local (développement et test) Identité de l’utilisateur ou principal du service
Azure Identité managée
Serveurs ou clients en dehors d’Azure Principal du service

Importez @azure/identity

Le package npm @azure/identity contient les fonctionnalités d’authentification principales partagées entre toutes les bibliothèques du kit de développement logiciel (SDK) Azure.

  1. Importez le package npm @azure/identity à l’aide de la commande npm install.

    npm install @azure/identity

  2. Dans votre éditeur de code, ajoutez les dépendances.

    const { DefaultAzureCredential } = require("@azure/identity");

Créer CosmosClient avec l’implémentation des informations d’identification par défaut

Si vous testez sur une machine locale ou que votre application s’exécute sur des services Azure avec prise en charge directe des identités managées, obtenez un jeton OAuth en créant une instance DefaultAzureCredential. Puis créez une instance de la classe CosmosClient avec la variable d’environnement COSMOS_ENDPOINT et l’objet TokenCredential en tant que paramètres.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Créer CosmosClient avec l’implémentation des informations d’identification par défaut

Si vous prévoyez de déployer l’application en dehors d’Azure, vous pouvez obtenir un jeton OAuth en utilisant d’autres classes de la bibliothèque de client @azure/Identity pour JavaScript. Ces autres classes dérivent également de la classe TokenCredential.

Pour cet exemple, nous créons une instance ClientSecretCredential à l’aide d’identificateurs client et de locataire, ainsi qu’une clé secrète client.

Vous pouvez obtenir l’ID client, l’ID locataire et la clé secrète client lorsque vous inscrivez une application dans Microsoft Entra ID. Pour plus d’informations concernant l’inscription d’applications Microsoft Entra, consultez Inscrire une application auprès de la plateforme d’identités Microsoft.

Créez une instance de la classe CosmosClient avec la variable d’environnement COSMOS_ENDPOINT et l’objet TokenCredential en tant que paramètres.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new ClientSecretCredential(
    tenantId: process.env.AAD_TENANT_ID,
    clientId: process.env.AAD_CLIENT_ID,
    clientSecret: process.env.AAD_CLIENT_SECRET
);

const cosmosClient = new CosmosClient({ 
    endpoint, 
    aadCredentials: credential
});

Générer votre application

À mesure que vous générez votre application, votre code interagit principalement avec quatre types de ressources :

  • Le compte d’API for NoSQL qui est l’unique espace de noms de niveau supérieur pour vos données Azure Cosmos DB.

  • Bases de données, qui organisent les conteneurs dans votre compte.

  • Conteneurs, qui contiennent un ensemble d’éléments individuels dans votre base de données.

  • Éléments, qui représentent un document JSON dans votre conteneur.

Le diagramme suivant montre la relation entre ces ressources.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

Chaque type de ressource est représenté par une ou plusieurs classes associées. Voici une liste des classes les plus courantes :

Classe Description
CosmosClient Cette classe fournit une représentation logique du côté client pour le service Azure Cosmos DB. Ce client est utilisé pour configurer et exécuter des requêtes sur le service.
Database Cette classe est une référence à une base de données qui peut, ou non, exister dans le service. La base de données est validée côté serveur lorsque vous tentez d’y accéder ou d’effectuer une opération sur celle-ci.
Container Cette classe est une référence à un conteneur qui n’existe pas encore dans le service. Le conteneur est validé côté serveur lorsque vous tentez de l’utiliser.

Les guides suivants vous montrent comment utiliser chacune de ces classes pour générer votre application.

Guide Description
Créer une base de données Créer des bases de données
Créer un conteneur Créer des conteneurs
Créer et lire un élément Pointer et lire un élément spécifique
Éléments de requête Interroger plusieurs éléments

Voir aussi

Étapes suivantes

Une fois que vous êtes connecté à un compte d’API pour NoSQL, utilisez le guide suivant pour créer et gérer des bases de données.

Créer une base de données dans Azure Cosmos DB for NoSQL à l’aide de JavaScript