Rozpoczynanie pracy z usługą Azure Cosmos DB for NoSQL przy użyciu języka JavaScript
DOTYCZY: NoSQL
W tym artykule pokazano, jak nawiązać połączenie z usługą Azure Cosmos DB for NoSQL przy użyciu zestawu SDK języka JavaScript. Po nawiązaniu połączenia można wykonywać operacje na bazach danych, kontenerach i elementach.
Kod źródłowy biblioteki źródłowej interfejsu API package (npm)Samples | API Reference | Code | (Dokumentacja interfejsu API pakietu (npm) | Prześlij opinię
Wymagania wstępne
- Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
- Konto usługi Azure Cosmos DB for NoSQL. Utwórz interfejs API dla konta NoSQL.
- Node.js LTS
- Interfejs wiersza polecenia platformy Azure lubprogram Azure PowerShell
Konfigurowanie projektu lokalnego
Utwórz nowy katalog dla projektu JavaScript w powłoce powłoki bash.
mkdir cosmos-db-nosql-javascript-samples && cd ./cosmos-db-nosql-javascript-samples
Utwórz nową aplikację JavaScript przy użyciu
npm init
polecenia z szablonem konsoli .npm init -y
Zainstaluj wymaganą zależność dla zestawu SDK języka JavaScript dla usługi Azure Cosmos DB.
npm install @azure/cosmos
Połączenie do usługi Azure Cosmos DB for NoSQL
Aby nawiązać połączenie z interfejsem API for NoSQL usługi Azure Cosmos DB, utwórz wystąpienie CosmosClient
klasy . Ta klasa jest punktem wyjścia do wykonywania wszystkich operacji względem baz danych. Istnieją trzy podstawowe sposoby nawiązywania połączenia z interfejsem API dla konta NoSQL przy użyciu klasy CosmosClient :
- Połączenie za pomocą interfejsu API dla punktu końcowego NoSQL i klucza odczytu/zapisu
- Połączenie za pomocą interfejsu API dla parametry połączenia NoSQL
- Połączenie za pomocą identyfikatora Entra firmy Microsoft
Połączenie z punktem końcowym i kluczem
Najbardziej typowy konstruktor dla usługi CosmosClient ma dwa parametry:
Parametr | Przykładowa wartość | opis |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT zmienna środowiskowa |
Interfejs API dla punktu końcowego NoSQL do użycia dla wszystkich żądań |
authKeyOrResourceToken |
COSMOS_KEY zmienna środowiskowa |
Klucz konta lub token zasobu do użycia podczas uwierzytelniania |
Pobieranie punktu końcowego i klucza konta
Utwórz zmienną powłoki dla właściwości resourceGroupName.
# Variable for resource group name resourceGroupName="msdocs-cosmos-javascript-howto-rg"
az cosmosdb list
Użyj polecenia , aby pobrać nazwę pierwszego konta usługi Azure Cosmos DB w grupie zasobów i zapisać je w zmiennej powłoki accountName.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
Pobierz identyfikator URI punktu końcowego interfejsu API dla programu NoSQL dla konta przy użyciu
az cosmosdb show
polecenia .az cosmosdb show \ --resource-group $resourceGroupName \ --name $accountName \ --query "documentEndpoint"
Znajdź KLUCZ PODSTAWOWY z listy kluczy dla konta za
az-cosmosdb-keys-list
pomocą polecenia .az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "keys" \ --query "primaryMasterKey"
Zapisz wartości identyfikatora URI i KLUCZA PODSTAWOWEgo. Te poświadczenia będą używane później.
Aby użyć wartości identyfikatora URI i KLUCZA PODSTAWOWEgo w kodzie, utrwały je w nowych zmiennych środowiskowych na komputerze lokalnym z uruchomioną aplikacją.
$env:COSMOS_ENDPOINT = "<cosmos-account-URI>"
$env:COSMOS_KEY = "<cosmos-account-PRIMARY-KEY>"
Tworzenie klienta CosmosClient z punktem końcowym konta i kluczem
Utwórz nowe wystąpienie klasy CosmosClient ze zmiennymi COSMOS_ENDPOINT
środowiskowymi i COSMOS_KEY
jako parametrami.
const client = new CosmosClient({ endpoint, key });
Połączenie z parametry połączenia
Inny konstruktor dla usługi CosmosClient zawiera tylko jeden parametr:
Parametr | Przykładowa wartość | opis |
---|---|---|
accountEndpoint |
COSMOS_ENDPOINT zmienna środowiskowa |
Interfejs API dla punktu końcowego NoSQL do użycia dla wszystkich żądań |
connectionString |
COSMOS_CONNECTION_STRING zmienna środowiskowa |
ciąg Połączenie ion do interfejsu API dla konta NoSQL |
Pobieranie parametry połączenia konta
az cosmosdb list
Użyj polecenia , aby pobrać nazwę pierwszego konta usługi Azure Cosmos DB w grupie zasobów i zapisać je w zmiennej powłoki accountName.# Retrieve most recently created account name accountName=$( az cosmosdb list \ --resource-group $resourceGroupName \ --query "[0].name" \ --output tsv )
Znajdź podstawowe parametry POŁĄCZENIA z listy parametry połączenia dla konta za
az-cosmosdb-keys-list
pomocą polecenia .az cosmosdb keys list \ --resource-group $resourceGroupName \ --name $accountName \ --type "connection-strings" \ --query "connectionStrings[?description == \`Primary SQL Connection String\`] | [0].connectionString"
Aby użyć wartości PODSTAWOWE PARAMETRY POŁĄCZENIA w kodzie, utrąć ją do nowej zmiennej środowiskowej na komputerze lokalnym z uruchomioną aplikacją.
$env:COSMOS_CONNECTION_STRING = "<cosmos-account-PRIMARY-CONNECTION-STRING>"
Tworzenie klienta CosmosClient przy użyciu parametry połączenia
Utwórz nowe wystąpienie klasy CosmosClient ze zmienną COSMOS_CONNECTION_STRING
środowiskową jako jedyny parametr.
// New instance of CosmosClient class using a connection string
const cosmosClient = new CosmosClient(process.env.COSMOS_CONNECTION_STRING);
Połączenie przy użyciu Platforma tożsamości Microsoft
Aby nawiązać połączenie z kontem interfejsu API dla noSQL przy użyciu Platforma tożsamości Microsoft i identyfikatora Entra firmy Microsoft, użyj podmiotu zabezpieczeń. Dokładny typ podmiotu zabezpieczeń zależy od tego, gdzie hostujesz kod aplikacji. Poniższa tabela służy jako krótki przewodnik informacyjny.
Gdzie działa aplikacja | Podmiot zabezpieczeń |
---|---|
Maszyna lokalna (programowanie i testowanie) | Tożsamość użytkownika lub jednostka usługi |
Azure | Tożsamość zarządzana |
Serwery lub klienci spoza platformy Azure | Jednostka usługi |
Importu @azure/identity
Pakiet npm @azure/tożsamości zawiera podstawowe funkcje uwierzytelniania współużytkowane przez wszystkie biblioteki zestawu Azure SDK.
Zaimportuj pakiet npm @azure/tożsamości przy użyciu
npm install
polecenia .npm install @azure/identity
W edytorze kodu dodaj zależności.
const { DefaultAzureCredential } = require("@azure/identity");
Tworzenie elementu CosmosClient z domyślną implementacją poświadczeń
Jeśli testujesz na komputerze lokalnym lub aplikacja będzie działać w usługach platformy Azure z bezpośrednią obsługą tożsamości zarządzanych, uzyskaj token OAuth, tworząc DefaultAzureCredential
wystąpienie. Następnie utwórz nowe wystąpienie klasy CosmosClient za pomocą COSMOS_ENDPOINT
zmiennej środowiskowej i obiektu TokenCredential jako parametrów.
const { CosmosClient } = require("@azure/cosmos");
const { DefaultAzureCredential } = require("@azure/identity");
const credential = new DefaultAzureCredential();
const cosmosClient = new CosmosClient({
endpoint,
aadCredentials: credential
});
Tworzenie klienta CosmosClient z niestandardową implementacją poświadczeń
Jeśli planujesz wdrożyć aplikację z platformy Azure, możesz uzyskać token OAuth przy użyciu innych klas w bibliotece klienta @azure/tożsamości dla języka JavaScript. Te inne klasy pochodzą również z TokenCredential
klasy .
W tym przykładzie utworzymy ClientSecretCredential
wystąpienie przy użyciu identyfikatorów klienta i dzierżawy wraz z wpisem tajnym klienta.
Identyfikator klienta, identyfikator dzierżawy i klucz tajny klienta można uzyskać podczas rejestrowania aplikacji w usłudze Microsoft Entra ID. Aby uzyskać więcej informacji na temat rejestrowania aplikacji firmy Microsoft Entra, zobacz Rejestrowanie aplikacji przy użyciu Platforma tożsamości Microsoft.
Utwórz nowe wystąpienie klasy CosmosClient ze zmienną COSMOS_ENDPOINT
środowiskową i obiektEm TokenCredential 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
});
Kompilowanie aplikacji
Podczas kompilowania aplikacji kod będzie przede wszystkim współdziałać z czterema typami zasobów:
Interfejs API dla konta NoSQL, który jest unikatową przestrzenią nazw najwyższego poziomu dla danych usługi Azure Cosmos DB.
Bazy danych, które organizują kontenery na twoim koncie.
Kontenery, które zawierają zestaw pojedynczych elementów w bazie danych.
Elementy reprezentujące dokument JSON w kontenerze.
Na poniższym diagramie przedstawiono relacje między tymi zasobami.
Diagram hierarchiczny przedstawiający konto usługi Azure Cosmos DB u góry. Konto ma dwa podrzędne węzły bazy danych. Jeden z węzłów bazy danych zawiera dwa podrzędne węzły kontenera. Drugi węzeł bazy danych zawiera jeden podrzędny węzeł kontenera. Ten pojedynczy węzeł kontenera ma trzy węzły elementów podrzędnych.
Każdy typ zasobu jest reprezentowany przez jedną lub więcej skojarzonych klas. Oto lista najpopularniejszych klas:
Klasa | opis |
---|---|
CosmosClient |
Ta klasa zapewnia logiczną reprezentację po stronie klienta dla usługi Azure Cosmos DB. Obiekt klienta służy do konfigurowania i wykonywania żądań względem usługi. |
Database |
Ta klasa jest odwołaniem do bazy danych, która może lub nie istnieje jeszcze w usłudze. Baza danych jest weryfikowana po stronie serwera podczas próby uzyskania do niej dostępu lub wykonania operacji względem niej. |
Container |
Ta klasa jest odwołaniem do kontenera, który również może jeszcze nie istnieć w usłudze. Kontener jest weryfikowany po stronie serwera podczas próby pracy z nim. |
W poniższych przewodnikach pokazano, jak utworzyć aplikację przy użyciu każdej z tych klas.
Przewodnik | opis |
---|---|
Tworzenie bazy danych | Tworzenie baz danych |
Tworzenie kontenera | Tworzenie kontenerów |
Tworzenie i odczytywanie elementu | Punkt odczytu określonego elementu |
Elementy kwerend | Wykonywanie zapytań o wiele elementów |
Zobacz też
Następne kroki
Po nawiązaniu połączenia z kontem interfejsu API dla noSQL użyj następnego przewodnika, aby utworzyć bazy danych i zarządzać nimi.