Introduzione ad Azure Cosmos DB per NoSQL con JavaScript

  • Articolo

SI APPLICA A: NoSQL

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

Package (npm) | Samples | API reference | Library source code | Give 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 npm init comando con il modello di console .

    npm init -y

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

    npm install @azure/cosmos

Connessione ad Azure Cosmos DB per NoSQL

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

Connessione 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 API per l'endpoint NoSQL da usare per tutte le richieste
authKeyOrResourceToken La variabile di ambiente COSMOS_KEY Chiave dell'account o token di risorsa da usare per l'autenticazione

Recuperare l'endpoint e la chiave dell'account

  1. Creare una variabile della shell per resourceGroupName.

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

  2. Usare il az cosmosdb list comando 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 per NoSQL per l'account usando il az cosmosdb show comando .

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

  4. Trovare la CHIAVE PRIMARIA dall'elenco di chiavi per l'account con il az-cosmosdb-keys-list comando .

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

  5. Registrare i valori URI e PRIMARY KEY . Queste credenziali verranno usate in un secondo momento.

Per usare i valori URI e PRIMARY KEY all'interno del codice, renderli persistenti 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 COSMOS_ENDPOINT variabili di ambiente e COSMOS_KEY come parametri.

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

Connessione con un stringa di connessione

Un altro costruttore per CosmosClient contiene solo un singolo parametro:

Parametro Valore di esempio Descrizione
accountEndpoint La variabile di ambiente COSMOS_ENDPOINT API per l'endpoint NoSQL da usare per tutte le richieste
connectionString La variabile di ambiente COSMOS_CONNECTION_STRING stringa Connessione ion all'account API per NoSQL

Recuperare il stringa di connessione dell'account

  1. Usare il az cosmosdb list comando 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. Trovare LA STRINGA DI CONNESSIONE PRIMARIA dall'elenco di stringa di connessione per l'account con il az-cosmosdb-keys-list comando .

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

Per usare il valore PRIMARY CONNECTION STRING all'interno del codice, salvarlo in modo permanente in una nuova variabile di ambiente nel computer locale che esegue l'applicazione.

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

Creare CosmosClient con stringa di connessione

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

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

Connessione con Microsoft Identity Platform

Per connettersi all'account API per NoSQL usando Microsoft Identity Platform e Microsoft Entra ID, usare un'entità di sicurezza. Il tipo esatto di entità dipende dalla posizione in cui si ospita il codice dell'applicazione. La tabella seguente funge da guida di riferimento rapido.

Posizione in cui 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

Importazione @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 npm install comando .

    npm install @azure/identity

  2. Nell'editor di codice aggiungere le dipendenze.

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

Creare CosmosClient con l'implementazione predefinita delle credenziali

Se si esegue il test in un computer locale o l'applicazione verrà eseguita nei servizi di Azure con supporto diretto per le identità gestite, ottenere un token OAuth creando un'istanza DefaultAzureCredential di . Creare quindi una nuova istanza della classe CosmosClient con la COSMOS_ENDPOINT variabile di ambiente 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 personalizzata

Se si prevede di distribuire l'applicazione da Azure, è possibile ottenere un token OAuth usando altre classi nella libreria client di @azure/identità per JavaScript. Queste altre classi derivano anche dalla TokenCredential classe .

Per questo esempio viene creata un'istanza ClientSecretCredential usando 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 con la COSMOS_ENDPOINT variabile di ambiente e l'oggetto TokenCredential come parametri.

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:

  • L'account API per NoSQL, ovvero lo spazio dei nomi principale univoco per i dati di Azure Cosmos DB.

  • Database, che organizzano i contenitori nell'account.

  • Contenitori che contengono un set di singoli elementi nel database.

  • Elementi che rappresentano un documento JSON nel contenitore.

Il diagramma seguente mostra la relazione tra queste risorse.

Diagram of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

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, o non, esistere ancora nel servizio. Il database viene convalidato sul lato server quando si tenta di accedervi o di 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 tenta di usarlo.

Le guide seguenti illustrano come usare ognuna di queste classi per compilare l'applicazione.

Guida Descrizione
Creare un database Creare database
Creare un contenitore Creare contenitori
Creare e leggere un elemento Punto letto 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 per NoSQL, usare la guida successiva per creare e gestire i database.

Creare un database in Azure Cosmos DB per NoSQL usando JavaScript