Začínáme se službou Azure Cosmos DB for NoSQL pomocí JavaScriptu

  • Článek

PLATÍ PRO: NoSQL

V tomto článku se dozvíte, jak se připojit ke službě Azure Cosmos DB for NoSQL pomocí sady JavaScript SDK. Po připojení můžete provádět operace s databázemi, kontejnery a položkami.

Package (npm) | Samples | API reference | Library source code | Give Feedback

Požadavky

Nastavení místního projektu

  1. Vytvořte nový adresář pro projekt JavaScriptu v prostředí bash.

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

  2. Pomocí příkazu se šablonou konzoly vytvořte novou javascriptovou aplikacinpm init.

    npm init -y

  3. Nainstalujte požadovanou závislost pro sadu Azure Cosmos DB for NoSQL JavaScript SDK.

    npm install @azure/cosmos

Připojení do služby Azure Cosmos DB for NoSQL

Pokud se chcete připojit k rozhraní API pro NoSQL služby Azure Cosmos DB, vytvořte instanci CosmosClient třídy. Tato třída je výchozím bodem pro provádění všech operací s databázemi. Existují tři základní způsoby připojení k účtu ROZHRANÍ API pro NoSQL pomocí třídy CosmosClient :

Připojení s koncovým bodem a klíčem

Nejběžnější konstruktor pro CosmosClient má dva parametry:

Parametr Příklad hodnoty Popis
accountEndpoint COSMOS_ENDPOINT proměnná prostředí Rozhraní API pro koncový bod NoSQL, který se má použít pro všechny požadavky
authKeyOrResourceToken COSMOS_KEY proměnná prostředí Klíč účtu nebo token prostředku, který se má použít při ověřování

Načtení koncového bodu a klíče účtu

  1. Vytvořte proměnnou prostředí pro resourceGroupName.

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

  2. az cosmosdb list Pomocí příkazu načtěte název prvního účtu služby Azure Cosmos DB ve vaší skupině prostředků a uložte ho do proměnné prostředí accountName.

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

  3. Pomocí příkazu získejte identifikátor URI koncového bodu API pro NoSQL pro účetaz cosmosdb show.

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

  4. Pomocí příkazu najděte PRIMÁRNÍ KLÍČ ze seznamu klíčů pro účetaz-cosmosdb-keys-list.

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

  5. Zaznamená hodnoty identifikátoru URI a PRIMÁRNÍHO KLÍČE . Tyto přihlašovací údaje použijete později.

Pokud chcete v kódu použít hodnoty URI a PRIMARY KEY , zachovejte je do nových proměnných prostředí na místním počítači, na kterém běží aplikace.

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

Vytvoření CosmosClient s koncovým bodem účtu a klíčem

Vytvořte novou instanci třídy CosmosClient s proměnnými COSMOS_ENDPOINT prostředí a COSMOS_KEY jako parametry.

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

Připojení s připojovací řetězec

Jiný konstruktor pro CosmosClient obsahuje pouze jeden parametr:

Parametr Příklad hodnoty Popis
accountEndpoint COSMOS_ENDPOINT proměnná prostředí Rozhraní API pro koncový bod NoSQL, který se má použít pro všechny požadavky
connectionString COSMOS_CONNECTION_STRING proměnná prostředí řetězec Připojení pro účet ROZHRANÍ API pro NoSQL

Načtení připojovací řetězec účtu

  1. az cosmosdb list Pomocí příkazu načtěte název prvního účtu služby Azure Cosmos DB ve vaší skupině prostředků a uložte ho do proměnné prostředí accountName.

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

  2. V seznamu připojovací řetězec pro účet pomocí az-cosmosdb-keys-list příkazu vyhledejte PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC.

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

Pokud chcete v kódu použít hodnotu PRIMARY CONNECTION STRING , zachovejte ji do nové proměnné prostředí na místním počítači, na kterém běží aplikace.

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

Vytvoření CosmosClient pomocí připojovací řetězec

Vytvořte novou instanci třídy CosmosClient s COSMOS_CONNECTION_STRING proměnnou prostředí jako jediný parametr.

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

Připojení s využitím platformy Microsoft Identity Platform

Pokud se chcete připojit k účtu ROZHRANÍ API for NoSQL pomocí platformy Microsoft Identity Platform a ID Microsoft Entra, použijte instanční objekt zabezpečení. Přesný typ objektu zabezpečení závisí na tom, kde hostujete kód aplikace. Následující tabulka slouží jako stručná referenční příručka.

Kde aplikace běží Objekt zabezpečení
Místní počítač (vývoj a testování) Identita uživatele nebo instanční objekt
Azure Spravovaná identita
Servery nebo klienti mimo Azure Instanční objekt

Import @azure/identity

Balíček npm @azure/identity obsahuje základní funkce ověřování, které se sdílí mezi všemi knihovnami sady Azure SDK.

  1. Importujte balíček npm @azure/identity pomocí npm install příkazu.

    npm install @azure/identity

  2. V editoru kódu přidejte závislosti.

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

Vytvoření CosmosClient s výchozí implementací přihlašovacích údajů

Pokud testujete na místním počítači nebo vaše aplikace bude běžet na službách Azure s přímou podporou spravovaných identit, získejte token OAuth vytvořením DefaultAzureCredential instance. Pak vytvořte novou instanci třídy CosmosClient s COSMOS_ENDPOINT proměnnou prostředí a TokenCredential objekt jako parametry.

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

const credential = new DefaultAzureCredential();

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

Vytvoření CosmosClient s vlastní implementací přihlašovacích údajů

Pokud plánujete nasadit aplikaci z Azure, můžete token OAuth získat pomocí jiných tříd v klientské knihovně @azure/identity pro JavaScript. Tyto další třídy jsou také odvozeny z TokenCredential třídy.

V tomto příkladu ClientSecretCredential vytvoříme instanci pomocí identifikátorů klienta a tenanta spolu s tajným klíčem klienta.

ID klienta, ID tenanta a tajný klíč klienta můžete získat při registraci aplikace v Microsoft Entra ID. Další informace o registraci aplikací Microsoft Entra naleznete v tématu Registrace aplikace na platformě Microsoft Identity Platform.

Vytvořte novou instanci třídy CosmosClient s COSMOS_ENDPOINT proměnnou prostředí a tokenCredential objekt jako parametry.

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

Sestavení aplikace

Při vytváření aplikace bude váš kód primárně pracovat se čtyřmi typy prostředků:

  • Účet ROZHRANÍ API pro NoSQL, což je jedinečný obor názvů nejvyšší úrovně pro vaše data Azure Cosmos DB.

  • Databáze, které uspořádají kontejnery ve vašem účtu.

  • Kontejnery, které obsahují sadu jednotlivých položek v databázi.

  • Položky, které představují dokument JSON ve vašem kontejneru.

Na následujícím diagramu jsou vztahy těchto prostředků.

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

Každý typ prostředku je reprezentován jednou nebo více přidruženými třídami. Tady je seznam nejběžnějších tříd:

Třída Popis
CosmosClient Tato třída poskytuje logickou reprezentaci na straně klienta pro službu Azure Cosmos DB. Objekt klienta slouží ke konfiguraci a spouštění požadavků na službu.
Database Tato třída je odkazem na databázi, která může nebo nemusí existovat ve službě ještě. Databáze je ověřena na straně serveru, když se pokusíte o přístup k databázi nebo provedete operaci s ní.
Container Tato třída je odkazem na kontejner, který ještě nemusí ve službě existovat. Kontejner se ověří na straně serveru, když se s ním pokusíte pracovat.

Následující příručky vám ukážou, jak pomocí každé z těchto tříd sestavit aplikaci.

Průvodce Popis
Vytvoření databáze Vytvoření databází
Vytvoření kontejneru Vytváření kontejnerů
Vytvoření a přečtení položky Načtení konkrétní položky
Dotazování položek Dotazování na více položek

Viz také

Další kroky

Teď, když jste se připojili k účtu ROZHRANÍ API pro NoSQL, použijte další příručku k vytváření a správě databází.

Vytvoření databáze ve službě Azure Cosmos DB for NoSQL pomocí JavaScriptu