Démarrage rapide : Bibliothèque de client Azure Cosmos DB pour Apache Cassandra pour Node.js

S’applique à: ✅ Apache Cassanda

Prise en main de la bibliothèque cliente Azure Cosmos DB pour Apache Cassandra pour Node.js stocker, gérer et interroger des données non structurées. Suivez les étapes décrites dans ce guide pour créer un compte, installer une bibliothèque cliente Node.js, vous connecter au compte, effectuer des opérations courantes et interroger vos exemples de données finaux.

Documentation de référence sur les API | Code source de la bibliothèque | Package (npm)

Conditions préalables

Un abonnement Azure
- Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Dernière version d’Azure CLI dans Azure Cloud Shell.
- Si vous préférez exécuter des commandes de référence CLI localement, connectez-vous à Azure CLI à l’aide de la az login commande.

Node.js 22 ou version ultérieure

Configuration

Tout d’abord, configurez l’environnement de compte et de développement pour ce guide. Cette section vous guide tout au long du processus de création d’un compte, de l’obtention de ses informations d’identification, puis de la préparation de votre environnement de développement.

Créer un compte

Commencez par créer une API pour un compte Apache Cassandra. Après la création du compte, créez l’espace de clés et les ressources de table.

Azure CLI
portail Azure

Si vous n’avez pas encore de groupe de ressources cible, utilisez la az group create commande pour créer un groupe de ressources dans votre abonnement.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Utilisez la az cosmosdb create commande pour créer un compte Azure Cosmos DB pour Apache Cassandra avec les paramètres par défaut.

az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

Créez un nouveau keyspace en utilisant az cosmosdb cassandra keyspace create nommé cosmicworks.

az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

Créez un objet JSON pour représenter votre schéma à l’aide d’une commande Bash multiligne. Ensuite, utilisez la az cosmosdb cassandra table create commande pour créer une table nommée products.

schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Connectez-vous au portail Azure (https://portal.azure.com).
Entrez Azure Cosmos DB dans la barre de recherche globale.
Dans Services, sélectionnez Azure Cosmos DB.
Dans le volet Azure Cosmos DB , sélectionnez Créer, puis Azure Cosmos DB pour Apache Cassandra dans l’onglet Autres .
Sélectionnez le compte de base de données d’unité de requête (RU) pour le type de compte.

Dans le volet Informations de base, configurez les options suivantes, puis sélectionnez Avis+ créer :

	Valeur
Type de charge de travail	Apprentissage
Abonnement	Sélectionnez votre abonnement Azure.
Groupe de ressources	Créer un groupe de ressources ou en sélectionner un
Nom du compte	Fournir un nom globalement unique
Zones de disponibilité	Désactiver
Lieu	Sélectionnez une région Azure prise en charge pour votre abonnement

Conseil / Astuce

Vous pouvez laisser les options non spécifiées à leur valeur par défaut. Vous pouvez également configurer le compte pour limiter le débit total du compte à 1 000 unités de requête par seconde (RU/s) ou activer le niveau gratuit pour réduire vos coûts.

Dans le volet Avis+ créer, attendez que la validation de votre compte se termine avec succès, puis sélectionnez Créer.
Le portail accède automatiquement au panneau Déploiement. Attendez que le déploiement se termine.
Une fois le déploiement terminé, sélectionnez Accéder à la ressource pour accéder à la nouvelle API pour le compte Apache Cassandra.
Dans le menu de la ressource, sélectionnez l’option Explorateur de données .
Dans l’Explorateur de données, sélectionnez + Nouvelle table.

Dans la boîte de dialogue Ajouter un tableau , configurez les options suivantes, puis sélectionnez OK :

	Valeur
Keyspace	Créer
Nom de l’espace de clés	`cosmicworks`
Nom de la table	`product`
Schéma de table	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Conseil / Astuce

Vous pouvez laisser les options non spécifiées à leur valeur par défaut.

Obtenir les informations d’identification

À présent, obtenez le mot de passe de la bibliothèque cliente à utiliser pour créer une connexion au compte récemment créé.

Azure CLI
portail Azure

Utilisez az cosmosdb show pour obtenir le point de contact et le nom d'utilisateur du compte.

az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

Enregistrez la valeur des propriétés contactPoint et username de la sortie des commandes précédentes. Ces valeurs de propriétés sont le point de contact et le nom d’utilisateur que vous utilisez plus loin dans ce guide pour vous connecter au compte avec la bibliothèque.

Utilisez az cosmosdb keys list pour obtenir les clés du compte.

az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

Enregistrez la valeur de la primaryMasterKey propriété à partir de la sortie des commandes précédentes. La valeur de cette propriété est le mot de passe que vous utilisez plus loin dans ce guide pour vous connecter au compte avec la bibliothèque.

Préparer l’environnement de développement

Ensuite, configurez votre environnement de développement avec un nouveau projet et la bibliothèque cliente. Cette étape est la dernière condition requise avant de passer au reste de ce guide.

Commencez par un dossier vide.
Initialisez un nouveau module.
```
npm init es6 --yes
```
Installez le cassandra-driver package à partir du Gestionnaire de package node (npm).
```
npm install --save cassandra-driver
```
Créez le fichier index.js .

Démarrez dans un répertoire vide.
Initialisez un nouveau module.
```
npm init es6 --yes
```
Installez le typescript package à partir du Gestionnaire de package node (npm).
```
npm install --save-dev typescript
```
Installez le tsx package à partir de npm.
```
npm install --save-dev tsx
```
Installez le cassandra-driver package à partir de npm.
```
npm install --save cassandra-driver
```

Initialisez le projet TypeScript à l’aide du compilateur (tsc).

npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

Créez le fichier index.ts .

Modèle d'objet

	Descriptif
`Client`	Représente une connexion spécifique à un cluster
`Mapper`	Client CQL (Cassandra Query Language) utilisé pour exécuter des requêtes

Authentifier le client

Commencez par authentifier le client à l’aide des informations d’identification collectées précédemment dans ce guide.

Ouvrez le fichier index.js dans votre environnement de développement intégré (IDE).

Importez les types suivants à partir du cassandra-driver module :

cassandra
cassandra.Client
cassandra.mapping.Mapper
cassandra.auth.PlainTextAuthProvider

import cassandra from 'cassandra-driver';

const { Client } = cassandra;
const { Mapper } = cassandra.mapping;
const { PlainTextAuthProvider } = cassandra.auth;

Créez des variables de constante de chaîne pour les informations d’identification collectées précédemment dans ce guide. Nommez les variables username, passwordet contactPoint.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Créez une autre variable de chaîne pour la région où vous avez créé votre compte Azure Cosmos DB pour Apache Cassandra. Nommez cette variable region.
```
const region = '<azure-region>';
```
Créez un PlainTextAuthProvider objet avec les informations d’identification spécifiées dans les étapes précédentes.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```

Créez un Client objet à l’aide des informations d’identification et des variables de configuration créées dans les étapes précédentes.

let client = new Client({
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: {
        secureProtocol: 'TLSv1_2_method'
    },
});

Connectez-vous de façon asynchrone au cluster.
```
await client.connect();
```

Créez un nouveau mappeur ciblant l’espace de clés cosmicworks et la table product. Nommez le mappeur Product.

const mapper = new Mapper(client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

Générez une instance de mappeur à l’aide de la forModel fonction et du nom du Product mappeur.
```
const productMapper = mapper.forModel('Product');
```

Ouvrez le fichier index.ts dans votre environnement de développement intégré (IDE).
Importez les types suivants à partir du cassandra-driver module :
- cassandra.auth
- cassandra.mapping
- cassandra.types
- cassandra.Client
- cassandra.ClientOptions
- cassandra.mapping.Mapper
- cassandra.auth.PlainTextAuthProvider
```
import { auth, mapping, types, Client, ClientOptions } from 'cassandra-driver';

const { Mapper } = mapping;
const { PlainTextAuthProvider } = auth;
```
Créez des variables de constante de chaîne pour les informations d’identification collectées précédemment dans ce guide. Nommez les variables username, passwordet contactPoint.
```
const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';
```
Créez une autre variable de chaîne pour la région où vous avez créé votre compte Azure Cosmos DB pour Apache Cassandra. Nommez cette variable region.
```
const region: string = '<azure-region>';
```
Créez un PlainTextAuthProvider objet avec les informations d’identification spécifiées dans les étapes précédentes.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```
Créez un objet anonyme avec des options qui garantissent que vous utilisez le protocole TLS (Transport Layer Security) 1.2.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```

Créez un ClientOptions objet à l’aide des informations d’identification et des variables de configuration créées dans les étapes précédentes.

let clientOptions: ClientOptions = {
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: sslOptions
};

Créez un Client objet à l’aide de la clientOptions variable dans le constructeur.
```
let client = new Client(clientOptions);
```
Connectez-vous de façon asynchrone au cluster.
```
await client.connect();
```

Créez un nouveau mappeur ciblant l’espace de clés cosmicworks et la table product. Nommez le mappeur Product.

const mapper = new Mapper( client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

Générez une instance de mappeur à l’aide de la forModel fonction et du nom du Product mappeur.
```
const productMapper = mapper.forModel('Product');
```

Avertissement

La validation TLS (Transport Layer Security) complète est désactivée dans ce guide pour simplifier l’authentification. Pour les déploiements de production, activez entièrement la validation.

Effectuer un upsert de données

Ensuite, insérer ou mettre à jour de nouvelles données dans une table. Upserting garantit que les données sont créées ou remplacées de manière appropriée selon que les mêmes données existent déjà dans la table.

Créez un objet dans une variable nommée product.

const product = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    name: 'Yamba Surfboard',
    category: 'gear-surf-surfboards',
    quantity: 12,
    price: 850.00,
    clearance: false
};

Appelez de façon asynchrone la insert fonction en passant la product variable créée à l’étape précédente.
```
await productMapper.insert(product);
```

Définissez une nouvelle interface nommée Product avec des champs correspondant à la table créée précédemment dans ce guide.

Type

Id string

Name string

Category string

Quantity int

Price decimal

Clearance bool
```
interface Product {
    id: string;
    name: string;
    category: string;
    quantity: number;
    price: number;
    clearance: boolean;
}
```
Conseil / Astuce

Dans Node.js, vous pouvez créer ce type dans un autre fichier ou le créer à la fin du fichier existant.

	Type
`Id`	`string`
`Name`	`string`
`Category`	`string`
`Quantity`	`int`
`Price`	`decimal`
`Clearance`	`bool`

Créez un objet de type Product. Stockez l’objet dans une variable nommée product.

const product: Product = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    name: 'Yamba Surfboard',
    category: 'gear-surf-surfboards',
    quantity: 12,
    price: 850.00,
    clearance: false
};

Appelez de façon asynchrone la insert fonction en passant la product variable créée à l’étape précédente.
```
await productMapper.insert(product);
```

Lire les données

Lisez ensuite les données qui ayant précédemment fait l’objet d’un upsert dans la table.

Créez un objet anonyme nommé filter. Dans cet objet, incluez une propriété nommée id avec la même valeur que le produit créé précédemment dans ce guide.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Appelez la get fonction du mappeur en passant la filter variable. Stockez le résultat dans une variable nommée matchedProduct.
```
let matchedProduct = await productMapper.get(filter);
```

Créez un objet anonyme nommé filter. Dans cet objet, incluez une propriété nommée id avec la même valeur que le produit créé précédemment dans ce guide.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Appelez la get fonction du mappeur en passant la filter variable. Stockez le résultat dans une variable nommée matchedProduct de type Product.
```
let matchedProduct: Product = await productMapper.get(filter);
```

Rechercher des données

Enfin, utilisez une requête pour rechercher toutes les données qui correspondent à un filtre spécifique dans la table.

Créez une variable de chaîne nommée query avec une requête CQL qui correspond aux éléments avec le même category champ.
```
const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Créez un objet anonyme nommé params. Dans cet objet, incluez une propriété nommée category avec la même valeur que le produit créé précédemment dans ce guide.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Appelez la fonction execute de façon asynchrone en passant les variables query et params en tant qu’arguments. Stockez la propriété du rows résultat sous la forme d’une variable nommée matchedProducts.
```
let { rows: matchedProducts } = await client.execute(query, params);
```
Itérer sur les résultats de la requête en appelant la foreach méthode sur le tableau de produits.
```
matchedProducts.forEach(product => {
    // Do something here with each result
});
```

Créez une variable de chaîne nommée query avec une requête CQL qui correspond aux éléments avec le même category champ.
```
const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Créez un objet anonyme nommé params. Dans cet objet, incluez une propriété nommée category avec la même valeur que le produit créé précédemment dans ce guide.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Appelez la fonction execute de façon asynchrone en passant les variables query et params en tant qu’arguments. Stockez le résultat dans une variable nommée result de type types.ResultSet.
```
let result: types.ResultSet = await client.execute(query, params);
```
Stockez la propriété du rows résultat sous la forme d’une variable nommée matchedProducts de type Product[].
```
let matchedProducts: Product[] = result.rows;
```
Itérer sur les résultats de la requête en appelant la foreach méthode sur le tableau de produits.
```
matchedProducts.forEach((product: Product) => {
    // Do something here with each result
});
```

Exécuter le code

Exécutez l’application nouvellement créée à l’aide d’un terminal dans votre répertoire d’application.

node index.js

npx tsx index.ts

Nettoyer les ressources

Lorsque vous n’avez plus besoin du compte, supprimez le compte de votre abonnement Azure en supprimant la ressource.

Azure CLI
portail Azure

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Étape suivante

Vue d’ensemble d’Azure Cosmos DB pour Apache Cassandra

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-07-23