Condividi tramite

Introduzione ad Azure Cosmos DB for NoSQL con JavaScript

  • Articolo

SI APPLICA A: NoSQL

Questo articolo illustra come connettersi ad Azure Cosmos DB for NoSQL usando JavaScript SDK. Una volta stabilita la connessione, è possibile eseguire operazioni su database, contenitori ed elementi.

Pacchetto (npm) | Esempi | Riferimento API | Codice sorgente della libreria | Inviare feedback

Prerequisiti

Configurare il progetto locale

  1. Creare una nuova directory per il progetto JavaScript in una shell bash.

    mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples

  2. Creare una nuova applicazione JavaScript usando il comando npm init con il modello di console.

    npm init -y

  3. Installare la dipendenza necessaria per Azure Cosmos DB for NoSQL JavaScript SDK.

    npm install @azure/cosmos

Connettersi ad Azure Cosmos DB for NoSQL

Per connettersi all'API for NoSQL di Azure Cosmos DB, creare un'istanza della classe CosmosClient. Questa classe è il punto di partenza per eseguire qualsiasi operazione sui database. Esistono tre modi principali per connettersi a un account API for NoSQL con la classe CosmosClient:

Connettersi con un endpoint e una chiave

Il costruttore più comune per CosmosClient ha due parametri:

Parametro Valore di esempio Descrizione
accountEndpoint La variabile di ambiente COSMOS_ENDPOINT Endpoint API for NoSQL da usare per tutte le richieste
authKeyOrResourceToken La variabile di ambiente COSMOS_KEY Chiave dell'account o token della risorsa da usare per l'autenticazione

Recuperare l'endpoint e la chiave dell'account

  1. Creare una variabile di shell per resourceGroupName.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-javascript-howto-rg"

  2. Usare il comando az cosmosdb list per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  3. Ottenere l'URI dell'endpoint API for NoSQL per l'account con il comando az cosmosdb show.

    az cosmosdb show \
    --resource-group $resourceGroupName \
    --name $accountName \
    --query "documentEndpoint"

  4. Trovare il valore di PRIMARY KEY nell'elenco di chiavi per l'account con il comando az-cosmosdb-keys-list.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "keys" \
    --query "primaryMasterKey"

  5. Registrare i valori URI e PRIMARY KEY. Queste credenziali saranno necessarie più avanti.

Per usare i valori URI e PRIMARY KEY all'interno del codice, mantenerli in nuove variabili di ambiente nel computer locale che esegue l'applicazione.

$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"

Creare CosmosClient con endpoint e chiave dell'account

Creare una nuova istanza della classe CosmosClient con le variabili di ambiente COSMOS_ENDPOINT e COSMOS_KEY come parametri.

const client = new CosmosClient({ endpoint, key });

Connettersi con una stringa di connessione

Un altro costruttore per CosmosClient contiene solo un parametro:

Parametro Valore di esempio Descrizione
accountEndpoint La variabile di ambiente COSMOS_ENDPOINT Endpoint API for NoSQL da usare per tutte le richieste
connectionString La variabile di ambiente COSMOS_CONNECTION_STRING Stringa di connessione all'account API for NoSQL

Recuperare la stringa di connessione dell'account

  1. Usare il comando az cosmosdb list per recuperare il nome del primo account Azure Cosmos DB nel gruppo di risorse e archiviarlo nella variabile della shell accountName.

    # Retrieve most recently created account name
accountName=$(
    az cosmosdb list \
        --resource-group $resourceGroupName \
        --query "[0].name" \
        --output tsv
)

  2. Eseguire il cmdlet az-cosmosdb-keys-list per trovare il valore di PRIMARY CONNECTION STRING dall'elenco delle stringhe di connessione per l'account.

    az cosmosdb keys list \
    --resource-group $resourceGroupName \
    --name $accountName \
    --type "connection-strings" \
    --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"

Per utilizzare il valore della STRINGA DI CONNESSIONE PRIMARIA all'interno del codice, salvarlo in una nuova variabile di ambiente sul computer locale che esegue l'applicazione.

$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"

Creare CosmosClient con la stringa di connessione

Creare una nuova istanza della classe CosmosClient specificando la variabile di ambiente COSMOS_CONNECTION_STRING come unico parametro.

// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);

Connettersi con Microsoft Identity Platform

Per connettersi all'account API for NoSQL usando Microsoft Identity Platform e Microsoft Entra ID, usare un'entità di sicurezza. Il tipo esatto di entità di sicurezza dipende da dove viene ospitato il codice dell'applicazione. La tabella seguente funge da guida di riferimento rapido.

Dove viene eseguita l'applicazione Entità di sicurezza principale
Computer locale (sviluppo e test) Identità utente o entità servizio
Azure Identità gestita
Server o client esterni ad Azure Entità servizio

Importare @azure/identity

Il pacchetto npm @azure/identity contiene funzionalità di autenticazione di base condivise tra tutte le librerie di Azure SDK.

  1. Importare il pacchetto npm @azure/identity usando il comando npm install.

    npm install @azure/identity

  2. Nell'editor di codice, aggiungere le dipendenze.

    const { DefaultAzureCredential } = require("@azure/identity");

Creare CosmosClient con implementazione di credenziali predefinite

Se si sta eseguendo un test su un computer locale o se l'applicazione verrà eseguita su servizi di Azure con supporto diretto per le identità gestite, ottenere un token OAuth creando un'istanza DefaultAzureCredential. Poi, creare una nuova istanza della classe CosmosClient con la variabile di ambiente COSMOS_ENDPOINT e l'oggetto TokenCredential come parametri.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();

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

Creare CosmosClient con un'implementazione di credenziali personalizzate

Se si prevede di distribuire l'applicazione all'esterno di Azure, è possibile ottenere un token OAuth usando altre classi nella libreria client di @azure/identity per JavaScript. Anche queste altre classi derivano dalla classe TokenCredential.

Per questo esempio viene creata un'istanza ClientSecretCredential con identificatori client e tenant, insieme a un segreto client.

È possibile ottenere l'ID client, l'ID tenant e il segreto client quando si registra un'applicazione in Microsoft Entra ID. Per altre informazioni sulla registrazione di applicazioni Microsoft Entra, vedere Registrare un'applicazione con Microsoft Identity Platform.

Creare una nuova istanza della classe CosmosClient specificando come parametri la variabile di ambiente COSMOS_ENDPOINT e l'oggetto TokenCredential.

const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new ClientSecretCredential(
    tenantId: process.env.AAD_TENANT_ID,
    clientId: process.env.AAD_CLIENT_ID,
    clientSecret: process.env.AAD_CLIENT_SECRET
);

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

Compilare l'applicazione

Durante la compilazione dell'applicazione, il codice interagirà principalmente con quattro tipi di risorse:

  • Account API for NoSQL, ovvero lo spazio dei nomi di primo livello univoco per i dati di Azure Cosmos DB.

  • Database, che organizzano i contenitori nell'account.

  • Contenitori, che contengono una serie di singoli elementi nel database.

  • Elementi, che rappresentano un documento JSON nel contenitore.

Il diagramma seguente mostra la relazione tra queste risorse.

Diagramma della gerarchia di Azure Cosmos DB, inclusi account, database, contenitori ed elementi.

Ogni tipo di risorsa è rappresentato da una o più classi associate. Ecco un elenco delle classi più comuni:

Classe Descrizione
CosmosClient Questa classe fornisce una rappresentazione logica lato client per il servizio Azure Cosmos DB. L'oggetto client viene usato per configurare ed eseguire richieste nel servizio.
Database Questa classe è un riferimento a un database che potrebbe esistere o meno nel servizio. Il database viene convalidato sul lato server quando si prova ad accedervi o a eseguire un'operazione su di esso.
Container Questa classe è un riferimento a un contenitore che potrebbe non esistere ancora nel servizio. Il contenitore viene convalidato sul lato server quando si prova a usarlo.

Nelle guide seguenti viene illustrato come usare ognuna di queste classi per creare l'applicazione.

Guida Descrizione
Creare un database Creare database
Creare un contenitore Crea contenitori
Creare e leggere un elemento Lettura diretta di un elemento specifico
Eseguire query sugli elementi Eseguire query su più elementi

Vedi anche

Passaggi successivi

Dopo aver eseguito la connessione a un account API for NoSQL, passare alla guida successiva per creare e gestire i database.

Creare un database in Azure Cosmos DB for NoSQL usando JavaScript