Démarrage rapide : Bibliothèque Azure Cosmos DB for NoSQL pour .Node.js

S’APPLIQUE À : NoSQL

Démarrage avec la bibliothèque de client Azure Cosmos DB for NoSQL pour .Node.js afin d’interroger des données dans vos conteneurs et d’effectuer des opérations courantes sur des éléments individuels. Suivez ces étapes pour déployer une solution minimale dans votre environnement à l’aide d’Azure Developer CLI.

Documentation de référence sur l’API | Code source de la bibliothèque | Package (npm) | Azure Developer CLI

Prérequis

Configuration

Déployez le conteneur de développement de ce projet dans votre environnement. Utilisez ensuite Azure Developer CLI (azd) pour créer un compte Azure Cosmos DB for NoSQL et déployer un exemple d’application conteneurisé. L’exemple d’application utilise la bibliothèque de client pour gérer, créer, lire et interroger des exemples de données.

Open in GitHub Codespaces

Open in Dev Container

Important

Les comptes GitHub incluent un droit de stockage et des heures cœur sans coût supplémentaire. Pour plus d’informations, consultez Stockage et heures cœur inclus dans les comptes GitHub.

  1. Ouvrez un terminal dans le répertoire racine du projet.

  2. Authentifiez-vous auprès d’Azure Developer CLI à l’aide de azd auth login. Suivez les étapes spécifiées par l’outil pour vous authentifier auprès de l’interface CLI à l’aide de vos informations d’identification Azure préférées.

    azd auth login
    
  3. Utilisez azd init pour initialiser le projet.

    azd init
    
  4. Lors de l’initialisation, configurez un nom d’environnement unique.

    Conseil

    Le nom de l’environnement sera également utilisé comme nom du groupe de ressources cible. Pour ce démarrage rapide, envisagez d’utiliser msdocs-cosmos-db-nosql.

  5. Déployez le compte Azure Cosmos DB for NoSQL à l’aide de azd up. Les modèles Bicep déploient également un exemple d’application web.

    azd up
    
  6. Pendant le processus d’approvisionnement, sélectionnez votre abonnement et l’emplacement souhaité. Attendez la fin du processus de provisionnement. Le processus peut prendre environ cinq minutes.

  7. Une fois l’approvisionnement de vos ressources Azure terminée, une URL vers l’application web en cours d’exécution est incluse dans la sortie.

    Deploying services (azd deploy)
    
      (✓) Done: Deploying service web
    - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io>
    
    SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
    
  8. Utilisez l’URL dans la console pour accéder à votre application web dans le navigateur. Observez la sortie de l’application en cours d’exécution.

    Screenshot of the running web application.

Installer la bibliothèque de client

La bibliothèque de client est disponible via le gestionnaire de package Node, en tant que package @azure/cosmos.

  1. Depuis un terminal, accédez au dossier /src.

    cd ./src
    
  2. S’il n’est pas déjà installé, installez le package @azure/cosmos à l’aide de npm install.

    npm install --save @azure/cosmos
    
  3. Installez également le package @azure/identity s’il n’est pas déjà installé.

    npm install --save @azure/identity
    
  4. Ouvrez et évaluez le fichier src/package.json pour vérifier que les entrées azure-cosmos et azure-identity existent.

Modèle objet

Nom Description
CosmosClient Cette classe est la classe cliente principale utilisée pour gérer les métadonnées ou bases de données à l’échelle du compte.
Database Cette classe représente une base de données dans le compte.
Container Cette classe est principalement utilisée pour effectuer des opérations de lecture, de mise à jour et de suppression sur le conteneur ou les éléments stockés dans le conteneur.
PartitionKey Cette classe représente une clé de partition logique. Cette classe est requise dans de nombreuses opérations et requêtes courantes.
SqlQuerySpec Cette interface représente une requête SQL et tous les paramètres de requête.

Exemples de code

L’exemple de code du modèle utilise une base de données nommée cosmicworks et un conteneur nommé products. Le conteneur products contient des détails tels que le nom, la catégorie, la quantité, un identificateur unique et un indicateur de vente pour chaque produit. Le conteneur utilise la propriété /category comme clé de partition logique.

Authentifier le client

Les requêtes d’application vers les Services Azure doivent être autorisées. Utilisez le type DefaultAzureCredential comme moyen préféré d’implémenter une connexion sans mot de passe entre vos applications et Azure Cosmos DB for NoSQL. DefaultAzureCredential prend en charge plusieurs méthodes d’authentification et détermine quelle méthode doit être utilisée au moment de l’exécution.

Important

Vous pouvez également autoriser directement les requêtes adressées aux services Azure à l’aide de mots de passe, de chaînes de connexion ou d’autres informations d’identification. Toutefois, cette approche doit être utilisée avec prudence. Les développeurs doivent être vigilants pour ne jamais exposer les secrets dans un emplacement non sécurisé. Toute personne ayant accès au mot de passe ou à la clé secrète peut s’authentifier auprès du service de base de données. DefaultAzureCredential offre des avantages de gestion et de sécurité améliorés sur la clé de compte pour autoriser l’authentification sans mot de passe sans risque de stocker des clés.

Cet exemple crée une instance de type CosmosClient et s’authentifie à l’aide d’une instance DefaultAzureCredential.

const credential = new DefaultAzureCredential();

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

Obtenir une base de données

Utilisez client.database pour récupérer la base de données existante nommée cosmicworks.

const database = client.database('cosmicworks');

Obtenir un conteneur

Récupérez le conteneur products existant à l’aide de database.container.

const container = database.container('products');

Créer un élément

Générez un objet avec tous les membres que vous souhaitez sérialiser dans JSON. Dans cet exemple, le type a un identificateur unique et des champs pour la catégorie, le nom, la quantité, le prix et la vente. Créez un élément dans le conteneur à l’aide de container.items.upsert. Cette méthode fait un « upsert » de l’élément efficacement en le remplaçant s’il existe déjà.

var item = {
    'id': '70b63682-b93a-4c77-aad2-65501347265f',
    'category': 'gear-surf-surfboards',
    'name': 'Yamba Surfboard',
    'quantity': 12,
    'price': 850.00,
    'clearance': false
};

var response = await container.items.upsert(item);

Lire un élément

Effectuez une opération de lecture de point à l’aide des champs d’identificateur unique (id) et de clé de partition. Utilisez container.item pour obtenir un pointeur vers un élément et item.read pour récupérer efficacement l’élément spécifique.

var id = '70b63682-b93a-4c77-aad2-65501347265f';
var partitionKey = 'gear-surf-surfboards';

var response = await container.item(id, partitionKey).read();
var read_item = response.resource;

Éléments de requête

Effectuez une requête sur plusieurs éléments d’un conteneur à l’aide de container.items.query. Recherchez tous les éléments d’une catégorie spécifiée à l’aide de cette requête paramétrable :

SELECT * FROM products p WHERE p.category = @category

Récupérez (fetch) tous les résultats de la requête à l’aide de query.fetchAll. Effectuez une boucle dans les résultats de la requête.

const querySpec = {
    query: 'SELECT * FROM products p WHERE p.category = @category',
    parameters: [
        {
            name: '@category',
            value: 'gear-surf-surfboards'
        }
    ]
};

var response = await container.items.query(querySpec).fetchAll();
for (var item of response.resources) {

}

Étape suivante