Creare un'app console Node.js con Azure DocumentDB

Questa guida consente di creare un'applicazione console Node.js per connettersi a un cluster di Azure DocumentDB. Si prepara l'ambiente di sviluppo, si usa il @azure/identity pacchetto di Azure SDK per JavaScript per l'autenticazione e si eseguono operazioni comuni sui documenti nel database.

Prerequisiti

Una sottoscrizione di Azure
- Se non hai un abbonamento Azure, crea un account gratuito

Un cluster Di Azure DocumentDB esistente
- Se non si ha un cluster, creare un nuovo cluster

È possibile utilizzare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.
Se preferisci eseguire localmente i comandi di riferimento della CLI, installa l'Azure CLI. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
- Se usi un'installazione locale, accedi all'interfaccia della riga di comando di Azure usando il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.
- Quando ti viene richiesto, installa l'estensione Azure CLI al primo utilizzo. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'interfaccia della riga di comando di Azure.
- Esegui az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, avviare az upgrade.

Autenticazione di Microsoft Entra configurata per il cluster con il ruolo root concesso all'identità dell'utente.
- Per abilitare l'autenticazione di Microsoft Entra, vedere la guida alla configurazione.
Versione più recente del supporto a lungo termine (LTS) di Node

Versione più recente di TypeScript.

Configurare l'applicazione console

Creare quindi un nuovo progetto di applicazione console e importare le librerie necessarie per l'autenticazione nel cluster.

Creare una nuova directory per il progetto e inizializzarla con npm init.
```
mkdir mongodb-app
cd mongodb-app
npm init -y
```

Configurare TypeScript nel progetto.

npm install typescript ts-node @types/node --save-dev
npx tsc --init

Creare il file TypeScript app.ts principale per l'applicazione.
```
touch app.ts
```
Installare la @azure/identity libreria per l'autenticazione.
```
npm install @azure/identity
```
Installare la libreria mongodb.
```
npm install mongodb
```

Connettersi al cluster

Ora, utilizza la libreria Azure.Identity per ottenere un TokenCredential da utilizzare per connetterti al cluster. Il driver Ufficiale di MongoDB ha un'interfaccia speciale che deve essere implementata per ottenere i token da Microsoft Entra per l'uso durante la connessione al cluster.

Importare i moduli necessari nella parte superiore del file JavaScript.

import { MongoClient } from 'mongodb';
import { DefaultAzureCredential } from '@azure/identity';

Creare una funzione di callback del token che ottiene i token dall'istanza TokenCredential quando necessario.

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),
    };
};

Imposta la variabile del nome del cluster per connettersi al cluster Azure DocumentDB.
```
const clusterName = '<azure-documentdb-cluster-name>';
```

Creare un'istanza di DefaultAzureCredential.

const credential = new DefaultAzureCredential();

Creare un client MongoDB configurato con l'autenticazione OIDC (OpenID Connect).

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']
    }
});

console.log('Client created');

Importare i moduli necessari nella parte superiore del file TypeScript.

import { AccessToken, DefaultAzureCredential, TokenCredential } from '@azure/identity';
import { Collection, Db, Filter, FindCursor, MongoClient, OIDCCallbackParams, OIDCResponse, UpdateFilter, UpdateOptions, UpdateResult, WithId } from 'mongodb';

Creare una funzione di callback del token che ottiene i token dall'istanza TokenCredential quando necessario.

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)
    };
};

Definire la variabile del nome del cluster per connettersi al cluster di Azure DocumentDB.
```
const clusterName: string = '<azure-documentdb-cluster-name>';
```

Creare un'istanza di DefaultAzureCredential.

const credential: TokenCredential = new DefaultAzureCredential();

Creare un client MongoDB configurato con l'autenticazione OIDC (OpenID Connect).

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']
    }
});

console.log('Client created');

Eseguire operazioni comuni

Infine, usare la libreria ufficiale per eseguire attività comuni con database, raccolte e documenti. In questo caso si usano le stesse classi e metodi usati per interagire con MongoDB o DocumentDB per gestire le raccolte e gli elementi.

Ottieni un riferimento al tuo database per nome.

const databaseName = process.env.SETTINGS__DATABASENAME ?? 'cosmicworks';

console.log('Database pointer created');

Ottieni un riferimento alla tua raccolta.

const collectionName = process.env.SETTINGS__COLLECTIONNAME ?? 'products';

console.log('Collection pointer created');

Crea un documento usando collection.updateOne e upsertalo nella raccolta.

const filter = { _id: request.params._id };
const payload = {
    $set: document
};
const options = {
    upsert: true
};

var response = await collection.updateOne(filter, payload, options);

if (response.acknowledged) {
    console.log(`Documents upserted count:\t${response.matchedCount}`);
}

Utilizzare collection.findOne per ottenere un documento specifico dalla raccolta.

const filter = { _id: request.params.id };

var document = await collection.findOne(filter, options);

console.log(`Read document _id:\t${document._id}`);

Eseguire una query per più documenti corrispondenti a un filtro usando collection.find.

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

var documents = collection.find(filter);

for await (const document of documents) {
    console.log(`Found document:\t${JSON.stringify(document)}`);
}

Al termine, chiudere la connessione client MongoDB.
```
await client.close();
```

Ottieni un riferimento al tuo database per nome.

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

console.log('Database pointer created');

Ottieni un riferimento alla tua raccolta.

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

console.log('Collection pointer created');

Definire un'interfaccia per rappresentare i documenti del prodotto.

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

Crea un documento usando collection.updateOne e upsertalo nella raccolta.

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'
};
var payload: UpdateFilter<Product> = {
    $set: document
};
var options: UpdateOptions = {
    upsert: true
};
var response: UpdateResult<Product> = await collection.updateOne(query, payload, options);

if (response.acknowledged) {
    console.log(`Documents upserted count:\t${response.matchedCount}`);
}

Utilizzare collection.findOne per ottenere un documento specifico dalla raccolta.

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

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

var read_item: Product = response as Product;

console.log(`Read document _id:\t${read_item._id}`);

Eseguire una query per più documenti corrispondenti a un filtro usando collection.find.

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

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

for await (const document of response) {
    console.log(`Found document:\t${JSON.stringify(document)}`);
}

Al termine, chiudere la connessione client MongoDB.
```
await client.close();
```

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-19