Quickstart: Azure Cosmos DB voor Apache Cassandra-clientbibliotheek voor Node.js

2025-07-21
Van toepassing op: ✅ Apache Cassanda

Ga aan de slag met de Azure Cosmos DB voor Apache Cassandra-clientbibliotheek voor Node.js om ongestructureerde gegevens op te slaan, te beheren en er query's op uit te voeren. Volg de stappen in deze handleiding om een nieuw account te maken, een Node.js-clientbibliotheek te installeren, verbinding te maken met het account, algemene bewerkingen uit te voeren en uw uiteindelijke voorbeeldgegevens op te vragen.

API-referentiedocumentatie | Bibliotheekbroncode | Package (npm)

Vereiste voorwaarden

Een Azure-abonnement
- Als je geen Azure-abonnement hebt, maak dan een gratis account aan voordat je begint.

De nieuwste versie van de Azure CLI in Azure Cloud Shell.
- Als u liever CLI-referentieopdrachten lokaal uitvoert, meldt u zich aan bij de Azure CLI met behulp van de az login opdracht.

Node.js 22 of hoger

Installeren

Stel eerst de account- en ontwikkelomgeving voor deze handleiding in. In deze sectie wordt u begeleid bij het maken van een account, het verkrijgen van de referenties en het voorbereiden van uw ontwikkelomgeving.

Een account maken

Begin met het maken van een API voor een Apache Cassandra-account. Zodra het account is gemaakt, maakt u de keyspace- en tabelbronnen.

Azure-CLI
Azure-portal

Als u nog geen doelresourcegroep hebt, gebruikt u de az group create opdracht om een nieuwe resourcegroep in uw abonnement te maken.
```
az group create \
    --name "<resource-group-name>" \
    --location "<location>"
```

Gebruik de az cosmosdb create opdracht om een nieuw Azure Cosmos DB voor Apache Cassandra-account te maken met standaardinstellingen.

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

Maak een nieuwe keyspace met az cosmosdb cassandra keyspace create en noem deze cosmicworks.

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

Maak een nieuw JSON-object om uw schema weer te geven met behulp van een Bash-opdracht met meerdere regels. Gebruik vervolgens de opdracht om een nieuwe tabel met de az cosmosdb cassandra table create naam productste maken.

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"

Meld u aan bij Azure Portal (https://portal.azure.com).
Voer Azure Cosmos DB in de algemene zoekbalk in.
Binnen Services, selecteer Azure Cosmos DB.
Selecteer Maken in het deelvenster Azure Cosmos DB, en selecteer vervolgens Azure Cosmos DB voor Apache Cassandra onder het tabblad Overige.
Kies RU-gegevensbankaccount aanvragen voor het accounttype.

Configureer in het deelvenster Basisbeginselen de volgende opties en selecteer vervolgens Beoordelen en maken:

	Waarde
Workloadtype	Leren
Abonnement	Selecteer uw Azure-abonnement
Resourcegroep	Een nieuwe resourcegroep maken of een bestaande resourcegroep selecteren
Accountnaam	Geef een wereldwijd unieke naam op
Beschikbaarheidszones	Uitschakelen
Plaats	Selecteer een ondersteunde Azure-regio voor uw abonnement

Aanbeveling

U kunt alle niet-opgegeven opties op de standaardwaarden laten staan. U kunt het account ook configureren om de totale doorvoer van accounts te beperken tot 1000 aanvraageenheden per seconde (RU/s) of om de gratis laag in te schakelen om uw kosten te minimaliseren.

Wacht in het deelvenster Controleren en maken tot de validatie van uw account is voltooid, en selecteer vervolgens Maken.
De portal gaat automatisch naar het deelvenster Implementatie . Wacht tot de implementatie is voltooid.
Zodra de implementatie is voltooid, selecteert u Ga naar de resource om naar de nieuwe API voor het Apache Cassandra-account te navigeren.
Selecteer in het resourcemenu de optie Data Explorer .
Selecteer + Nieuwe tabel in Data Explorer.

Configureer in het dialoogvenster Tabel toevoegen de volgende opties en selecteer VERVOLGENS OK:

	Waarde
Keyspace	Nieuwe maken
Keyspace-naam	`cosmicworks`
Tabelnaam	`product`
Tabelschema	`(id text, name text, category text, quantity int, price decimal, clearance boolean, PRIMARY KEY (id))`

Aanbeveling

U kunt alle niet-opgegeven opties op de standaardwaarden laten staan.

Referenties ophalen

Haal nu het wachtwoord op dat de clientbibliotheek moet gebruiken om een verbinding te maken met het onlangs gemaakte account.

Azure-CLI
Azure-portal

Gebruik az cosmosdb show dit om het contactpunt en de gebruikersnaam voor het account op te halen.

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

Noteer de waarde van de contactPoint en username eigenschappen uit de uitvoer van de vorige opdrachten. De waarden van deze eigenschappen zijn het contactpunt en de gebruikersnaam die u verderop in deze handleiding gebruikt om verbinding te maken met het account met de bibliotheek.

Gebruik az cosmosdb keys list om de sleutels op te halen voor het account.

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

Noteer de waarde van de primaryMasterKey eigenschap uit de uitvoer van de vorige opdrachten. De waarde van deze eigenschap is het wachtwoord dat u verderop in deze handleiding gebruikt om verbinding te maken met het account met de bibliotheek.

Ontwikkelomgeving voorbereiden

Configureer vervolgens uw ontwikkelomgeving met een nieuw project en de clientbibliotheek. Deze stap is het laatste vereiste voordat u verdergaat met de rest van deze handleiding.

Begin in een lege map.
Initialiseer een nieuwe module.
```
npm init es6 --yes
```
Installeer het cassandra-driver pakket vanuit Node Package Manager (npm).
```
npm install --save cassandra-driver
```
Maak het index.js-bestand .

Begin in een lege map.
Initialiseer een nieuwe module.
```
npm init es6 --yes
```
Installeer het typescript pakket vanuit Node Package Manager (npm).
```
npm install --save-dev typescript
```
Installeer het tsx pakket vanuit npm.
```
npm install --save-dev tsx
```
Installeer het cassandra-driver pakket vanuit npm.
```
npm install --save cassandra-driver
```

Initialiseer het TypeScript-project met behulp van de compiler (tsc).

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

Maak het index.ts-bestand .

Objectmodel

	Beschrijving
`Client`	Vertegenwoordigt een specifieke verbinding met een cluster
`Mapper`	Cassandra Query Language -client (CQL) die wordt gebruikt om query's uit te voeren

Client verifiëren

Begin met het authentificeren van de client met behulp van de inloggegevens die eerder in deze handleiding zijn verzameld.

Open het index.js-bestand in uw IDE (Integrated Development Environment).

Importeer de volgende typen uit de 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;

Maak tekenreeksconstante variabelen voor de referenties die eerder in deze handleiding zijn verzameld. Geef de variabelen usernameeen naam en passwordcontactPoint.
```
const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';
```
Maak een andere tekenreeksvariabele voor de regio waar u uw Azure Cosmos DB voor Apache Cassandra-account hebt gemaakt. Geef deze variabele regioneen naam.
```
const region = '<azure-region>';
```
Maak een nieuw PlainTextAuthProvider object met de referenties die zijn opgegeven in de vorige stappen.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```

Maak een Client object met behulp van de referenties en configuratievariabelen die in de vorige stappen zijn gemaakt.

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

Asynchroon verbinding maken met het cluster.
```
await client.connect();
```

Maak een nieuwe mapper die gericht is op de cosmicworks keyspace en product tabel. Geef de mapper Producteen naam.

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

Genereer een mapper-exemplaar met behulp van de forModel functie en de Product mappernaam.
```
const productMapper = mapper.forModel('Product');
```

Open het bestand index.ts in uw IDE (Integrated Development Environment).
Importeer de volgende typen uit de 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;
```
Maak tekenreeksconstante variabelen voor de referenties die eerder in deze handleiding zijn verzameld. Geef de variabelen usernameeen naam en passwordcontactPoint.
```
const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';
```
Maak een andere tekenreeksvariabele voor de regio waar u uw Azure Cosmos DB voor Apache Cassandra-account hebt gemaakt. Geef deze variabele regioneen naam.
```
const region: string = '<azure-region>';
```
Maak een nieuw PlainTextAuthProvider object met de referenties die zijn opgegeven in de vorige stappen.
```
let authProvider = new PlainTextAuthProvider(
    username,
    password
);
```
Maak een anoniem object met opties die ervoor zorgen dat u het TLS 1.2-protocol (Transport Layer Security) gebruikt.
```
let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};
```

Maak een ClientOptions object met behulp van de referenties en configuratievariabelen die in de vorige stappen zijn gemaakt.

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

Maak een Client object met behulp van de clientOptions variabele in de constructor.
```
let client = new Client(clientOptions);
```
Asynchroon verbinding maken met het cluster.
```
await client.connect();
```

Maak een nieuwe mapper die gericht is op de cosmicworks keyspace en product tabel. Geef de mapper Producteen naam.

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

Genereer een mapper-exemplaar met behulp van de forModel functie en de Product mappernaam.
```
const productMapper = mapper.forModel('Product');
```

Waarschuwing

Volledige TLS-validatie (Transport Layer Security) is uitgeschakeld in deze handleiding om verificatie te vereenvoudigen. Voor productie-implementaties schakelt u validatie volledig in.

Gegevens bijwerken of toevoegen

Vervolgens worden nieuwe gegevens in een tabel geplaatst. Upserting zorgt ervoor dat de gegevens op de juiste wijze worden gemaakt of vervangen, afhankelijk van of dezelfde gegevens al in de tabel aanwezig zijn.

Maak een nieuw object in een variabele met de naam product.

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

Roep asynchroon de insert functie aan die de product variabele doorgeeft die in de vorige stap is gemaakt.
```
await productMapper.insert(product);
```

Definieer een nieuwe interface met de naam Product velden die overeenkomen met de tabel die eerder in deze handleiding is gemaakt.

Typologie

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;
}
```
Aanbeveling

In Node.jskunt u dit type in een ander bestand maken of maken aan het einde van het bestaande bestand.

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

Maak een nieuw object van het type Product. Sla het object op in een variabele met de naam product.

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

Roep asynchroon de insert functie aan die de product variabele doorgeeft die in de vorige stap is gemaakt.
```
await productMapper.insert(product);
```

Gegevens lezen

Lees vervolgens gegevens die eerder in de tabel zijn geplaatst.

Maak een anoniem object met de naam filter. Neem in dit object een eigenschap id op met dezelfde waarde als het product dat u eerder in deze handleiding hebt gemaakt.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Roep de get functie aan van de mapper die de filter variabele doorgeeft. Sla het resultaat op in een variabele met de naam matchedProduct.
```
let matchedProduct = await productMapper.get(filter);
```

Maak een anoniem object met de naam filter. Neem in dit object een eigenschap id op met dezelfde waarde als het product dat u eerder in deze handleiding hebt gemaakt.
```
const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};
```
Roep de get functie aan van de mapper die de filter variabele doorgeeft. Sla het resultaat op in een variabele met de naam matchedProduct van het type Product.
```
let matchedProduct: Product = await productMapper.get(filter);
```

Gegevens opvragen

Gebruik ten slotte een query om alle gegevens te vinden die overeenkomen met een specifiek filter in de tabel.

Maak een nieuwe tekenreeksvariabele genaamd query, met een CQL-query die overeenkomt met items met hetzelfde category-veld.
```
const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Maak een anoniem object met de naam params. Neem in dit object een eigenschap category op met dezelfde waarde als het product dat u eerder in deze handleiding hebt gemaakt.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Roep asynchroon de execute functie aan die zowel de queryparams als de variabelen als argumenten doorgeeft. Sla de eigenschap van rows het resultaat op als een variabele met de naam matchedProducts.
```
let { rows: matchedProducts } = await client.execute(query, params);
```
De queryresultaten herhalen door de foreach methode aan te roepen op de matrix met producten.
```
matchedProducts.forEach(product => {
    // Do something here with each result
});
```

Maak een nieuwe tekenreeksvariabele genaamd query, met een CQL-query die overeenkomt met items met hetzelfde category-veld.
```
const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;
```
Maak een anoniem object met de naam params. Neem in dit object een eigenschap category op met dezelfde waarde als het product dat u eerder in deze handleiding hebt gemaakt.
```
const params = {
    category: 'gear-surf-surfboards'
};
```
Roep asynchroon de execute functie aan die zowel de queryparams als de variabelen als argumenten doorgeeft. Sla het resultaat op in een variabele met de naam result van het type types.ResultSet.
```
let result: types.ResultSet = await client.execute(query, params);
```
Sla de eigenschap van het resultaat rows op als een variabele met de naam matchedProducts en van het type Product[].
```
let matchedProducts: Product[] = result.rows;
```

De queryresultaten herhalen door de foreach methode aan te roepen op de matrix met producten.

matchedProducts.forEach((product: Product) => {
    // Do something here with each result
});

De code uitvoeren

Voer de zojuist gemaakte toepassing uit met behulp van een terminal in uw toepassingsmap.

node index.js

npx tsx index.ts

De hulpbronnen opschonen

Wanneer u het account niet meer nodig hebt, verwijdert u het account uit uw Azure-abonnement door de resource te verwijderen .

Azure-CLI
Azure-portal

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

Volgende stap

Overzicht van Azure Cosmos DB voor Apache Cassandra

Feedback

Is deze pagina nuttig?