Snabbstart: Använda Azure Cosmos DB för MongoDB vCore med MongoDB-drivrutin för Node.js

2025-10-13
Gäller för: ✅ MongoDB (vCore)

I den här snabbstarten distribuerar du ett grundläggande Azure Cosmos DB för MongoDB-program med hjälp av Node.js. Azure Cosmos DB for MongoDB vCore är ett schemalöst datalager som gör att program kan lagra ostrukturerade dokument i molnet med MongoDB-bibliotek. Du lär dig hur du skapar dokument och utför grundläggande uppgifter i din Azure Cosmos DB-resurs med hjälp av Node.js.

Bibliotekets källkod | Package (npm) | Azure Developer CLI

Förutsättningar

Azure Developer CLI
Docker Desktop

En prenumeration på Azure
- Om du inte har en Azure-prenumeration, skapa ett gratis konto innan du börjar.

Node.js 22 eller senare

Initiera projektet

Använd Azure Developer CLI (azd) för att skapa ett Azure Cosmos DB for MongoDB vCore-kluster och distribuera ett containerbaserat exempelprogram. Exempelprogrammet använder klientbiblioteket för att hantera, skapa, läsa och fråga efter exempeldata.

Öppna en terminal i en tom katalog.
Om du inte redan är autentiserad autentiserar du till Azure Developer CLI med hjälp av azd auth login. Följ stegen som anges av verktyget för att autentisera till CLI med dina önskade Azure-autentiseringsuppgifter.
```
azd auth login
```

Använd azd init för att initiera projektet.

azd init --template cosmos-db-mongodb-vcore-nodejs-quickstart

Under initieringen konfigurerar du ett unikt miljönamn.
Distribuera klustret med .azd up Bicep-mallarna distribuerar också ett exempel på ett webbprogram.
```
azd up
```
Under etableringsprocessen väljer du din prenumeration, önskad plats och målresursgrupp. Vänta tills försörjningsprocessen har slutförts. Processen kan ta cirka tio minuter.

När etableringen av dina Azure-resurser är klar inkluderas en URL till det webbprogram som körs i utdata.

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.

Använd URL:en i konsolen för att navigera till webbprogrammet i webbläsaren. Observera utdata från appen som körs.

Skärmbild av webbprogrammet som körs.

Installera klientbiblioteket

Klientbiblioteket är tillgängligt via npm som mongodb paket.

Öppna en terminal och navigera till /src/ts mappen.
```
cd ./src/ts
```
Om det inte redan är installerat, installerar du mongodb-paketet med npm install.
```
npm install --save mongodb
```
Om det inte redan är installerat, installerar du @azure/identity-paketet med npm install.
```
npm install --save @azure/identity
```
Öppna och granska filen src/ts/package.json för att verifiera att båda paketposterna finns.

Öppna en terminal och navigera till /src/js mappen.
```
cd ./src/js
```
Om det inte redan är installerat, installerar du mongodb-paketet med npm install.
```
npm install --save mongodb
```
Om det inte redan är installerat, installerar du @azure/identity-paketet med npm install.
```
npm install --save @azure/identity
```
Öppna och granska filen src/js/package.json för att verifiera att båda paketposterna finns.

Importera bibliotek

Importera följande namnområden till programkoden:

	Paket	Källa
`TokenCredential`	`@azure/identity`	Azure SDK för JavaScript
`DefaultAzureCredential`	`@azure/identity`	Azure SDK för JavaScript
`MongoClient`	`mongodb`	Officiell MongoDB-drivrutin för Node.js

import { DefaultAzureCredential, TokenCredential } from '@azure/identity';

import { MongoClient } from 'mongodb';

Importera alla nödvändiga typer till programkoden, inklusive, men inte begränsat till:

	Paket	Källa
`TokenCredential`	`@azure/identity`	Azure SDK för JavaScript
`DefaultAzureCredential`	`@azure/identity`	Azure SDK för JavaScript
`MongoClient`	`mongodb`	Officiell MongoDB-drivrutin för Node.js

import { AccessToken, DefaultAzureCredential, TokenCredential } from '@azure/identity';

import { Collection, Db, Filter, FindCursor, MongoClient, OIDCCallbackParams, OIDCResponse, UpdateFilter, UpdateOptions, UpdateResult, WithId } from 'mongodb';

Objektmodell

Namn	Beskrivning
MongoClient	Typ som används för att ansluta till MongoDB.
`Database`	Representerar en databas i klustret.
`Collection`	Representerar en samling i en databas i klustret.

Exempelkoden i mallen använder en databas med namnet cosmicworks och samlingen med namnet products. Samlingen products innehåller information som namn, kategori, kvantitet och en unik identifierare för varje produkt. Samlingen använder egenskapen /category som en fragmentnyckel.

Autentisera klienten

Microsoft Entra-autentisering för Azure Cosmos DB for MongoDB vCore kan använda välkända TokenCredential typer, men du måste implementera en anpassad tokenhanterare. Den här exempelimplementeringen kan användas för att skapa en MongoClient med stöd för Microsoft Entra-standardautentisering av många identitetstyper.

Definiera först en återuppringning med namnet AzureIdentityTokenCallback som tar in OIDCCallbackParams och TokenCredential och sedan returnerar asynkront en OIDCResponse.

const AzureIdentityTokenCallback = async (params: OIDCCallbackParams, credential: TokenCredential): Promise<OIDCResponse> => {
    const tokenResponse: AccessToken | null = await credential.getToken(['https://ossrdbms-aad.database.windows.net/.default']);
    return {
        accessToken: tokenResponse?.token || '',
        expiresInSeconds: (tokenResponse?.expiresOnTimestamp || 0) - Math.floor(Date.now() / 1000)
    };
};

Definiera variabler för klusternamnet och tokenautentiseringsuppgifterna.

const clusterName: string = '<azure-cosmos-db-mongodb-vcore-cluster-name>';

const credential: TokenCredential = new DefaultAzureCredential();

Skapa en instans av MongoClient med ditt klusternamn och de kända bästa praxis konfigurationsalternativen för Azure Cosmos DB för MongoDB vCore. Konfigurera även din anpassade autentiseringsmekanism.

const client = new MongoClient(
    `mongodb+srv://${clusterName}.global.mongocluster.cosmos.azure.com/`, {
    connectTimeoutMS: 120000,
    tls: true,
    retryWrites: true,
    authMechanism: 'MONGODB-OIDC',
    authMechanismProperties: {
            OIDC_CALLBACK: (params: OIDCCallbackParams) => AzureIdentityTokenCallback(params, credential),
            ALLOWED_HOSTS: ['*.azure.com']
        }
    }
);

Definiera först en motringning med namnet azureIdentityTokenCallback som tar in parametrar och en tokenautentiseringsuppgift och sedan returnerar asynkront ett svar.

const azureIdentityTokenCallback = async (_, credential) => {
    const tokenResponse = await credential.getToken(['https://ossrdbms-aad.database.windows.net/.default']);

    if (!tokenResponse || !tokenResponse.token) {
        throw new Error('Failed to retrieve a valid access token.');
    }

    return {
        accessToken: tokenResponse.token,
        expiresInSeconds: Math.floor((tokenResponse.expiresOnTimestamp - Date.now()) / 1000),
    };
};

Definiera variabler för klusternamnet och tokenautentiseringsuppgifterna.

const clusterName = '<azure-cosmos-db-mongodb-vcore-cluster-name>';

const credential = new DefaultAzureCredential();

client = new MongoClient(`mongodb+srv://${clusterName}.global.mongocluster.cosmos.azure.com/`, {
    connectTimeoutMS: 120000,
    tls: true,
    retryWrites: true,
    authMechanism: 'MONGODB-OIDC',
    authMechanismProperties: {
        OIDC_CALLBACK: (params) => azureIdentityTokenCallback(params, credential),
        ALLOWED_HOSTS: ['*.azure.com']
    }
});

await client.connect();

Hämta en databas

Det här exemplet skapar en instans av typen Db med hjälp av funktionen db av typen MongoClient.

const database: Db = client.db("<database-name>");

const database = client.db("<database-name>");

Hämta en samling

Det här exemplet skapar en instans av typen Collection med hjälp av funktionen collection av typen Db.

Den här funktionen har en allmän parameter som använder den Product typ som definierats i ett gränssnitt.

const collection: Collection<Product> = database.collection<Product>("<collection-name>");

export interface Product {
    _id: string;
    category: string;
    name: string;
    quantity: number;
    price: number;
    clearance: boolean;
}

const collection = database.collection("<collection-name>");

Skapa ett dokument

Skapa ett dokument i samlingen med .collection.updateOne Den här metoden inför eller uppdaterar objektet, vilket effektivt ersätter det om det redan finns.

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

var query: Filter<Product> = {
    _id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    category: 'gear-surf-surfboards'
};
var payload: UpdateFilter<Product> = {
    $set: document
};
var options: UpdateOptions = {
    upsert: true
};
var response: UpdateResult<Product> = await collection.updateOne(query, payload, options);

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

const query = {
    _id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    category: 'gear-surf-surfboards'
};
const payload = {
    $set: document
};
const options = {
    upsert: true,
    new: true
};
var response = await collection.updateOne(query, payload, options);

Läsa ett dokument

Utför en punktläsningsåtgärd med hjälp av både den unika identifieraren (id) och shardnyckelfältet. Använd collection.findOne för att effektivt hämta det specifika objektet.

var query: Filter<Product> = { 
    _id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 
    category: 'gear-surf-surfboards' 
};

var response: WithId<Product> | null = await collection.findOne(query);

var query = { 
    _id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb', 
    category: 'gear-surf-surfboards' 
};

var response = await collection.findOne(query);

Sök dokument

Utför en fråga över flera objekt i en container med hjälp av collection.find. Den här sökfrågan hittar alla objekt inom en angiven kategori (shardnyckel).

var query: Filter<Product> = { 
    category: 'gear-surf-surfboards' 
};

var response: FindCursor<WithId<Product>> = collection.find(query);

for await (const item of response) {
    // Do something with each item
}

var query = { 
    category: 'gear-surf-surfboards' 
};

var response = collection.find(query);

for await (const item of response) {
    // Do something with each item
}

Ta bort ett dokument

Ta bort ett dokument genom att skicka ett filter för dokumentets unika identifierare. Använd collection.deleteOne<> för att asynkront ta bort dokumentet från samlingen.

var filter: Filter<Product> = { 
    _id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};

await collection.deleteOne(filter);

const filter = {
    _id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};

await collection.deleteOne(filter);

Utforska dina data

Använd Visual Studio Code-tillägget för Azure Cosmos DB för att utforska dina MongoDB vCore-data. Du kan utföra grundläggande databasåtgärder, inklusive, men inte begränsat till:

Utföra sökningar med hjälp av ett skrivblock eller frågeredigeraren
Ändra, uppdatera, skapa och ta bort dokument
Importera massdata från andra källor
Hantera databaser och samlingar

Mer information finns i Använda Visual Studio Code-tillägget för att utforska Azure Cosmos DB for MongoDB vCore-data.

Rensa resurser

När du inte längre behöver exempelprogrammet eller resurserna tar du bort motsvarande distribution och alla resurser.

azd down --force

Feedback

Var den här sidan till hjälp?