Share via

Rozpoczynanie pracy z usługą Azure Cosmos DB for NoSQL przy użyciu platformy .NET

  • Artykuł

DOTYCZY: NoSQL

W tym artykule pokazano, jak nawiązać połączenie z usługą Azure Cosmos DB for NoSQL przy użyciu zestawu .NET SDK. 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 (NuGet)Samples | API Reference | Code | (Dokumentacja interfejsu API pakietu (NuGet) | Prześlij opinię

Wymagania wstępne

konfigurowanie projektu

Tworzenie aplikacji konsolowej .NET

Utwórz nową aplikację .NET przy użyciu dotnet new polecenia z szablonem konsoli .

dotnet new console

Zaimportuj pakiet NuGet Microsoft.Azure.Cosmos przy użyciu dotnet add package polecenia .

dotnet add package Microsoft.Azure.Cosmos

Skompiluj projekt za dotnet build pomocą polecenia .

dotnet build

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 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

  1. Utwórz zmienną powłoki dla właściwości resourceGroupName.

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

  2. 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
)

  3. 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"

  4. 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"

  5. Zapisz wartości identyfikatora URI i KLUCZA PODSTAWOWEgo. Te poświadczenia będą używane później.

Aby użyć wartości URI i PRIMARY KEY w kodzie platformy .NET, utrwali 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.

// New instance of CosmosClient class using an endpoint and key string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    authKeyOrResourceToken: Environment.GetEnvironmentVariable("COSMOS_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

  1. 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
)

  2. 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 platformy .NET, utrwali ją w nowej zmiennej środowiskowej na komputerze lokalnym, na którym jest uruchomiona aplikacja.

$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
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("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ń będzie zależeć 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

Importowanie pliku Azure.Identity

Pakiet NuGet Azure.Identity zawiera podstawowe funkcje uwierzytelniania współużytkowane przez wszystkie biblioteki zestawu Azure SDK.

Zaimportuj pakiet NuGet Azure.Identity przy użyciu dotnet add package polecenia .

dotnet add package Azure.Identity

Skompiluj projekt za dotnet build pomocą polecenia .

dotnet build

W edytorze kodu dodaj dyrektywy using dla Azure.Core przestrzeni nazw i Azure.Identity .

using Azure.Core;
using 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.

W tym przykładzie zapisano wystąpienie w zmiennej typu TokenCredential , ponieważ jest to bardziej ogólny typ, który jest wielokrotnego użytku w zestawach SDK.

// Credential class for testing on a local machine or Azure services
TokenCredential credential = new DefaultAzureCredential();

Utwórz nowe wystąpienie klasy CosmosClient ze zmienną COSMOS_ENDPOINT środowiskową i obiektEm TokenCredential jako parametry.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: 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.Identity dla platformy .NET. 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.

// Custom credential class for servers and clients outside of Azure
TokenCredential credential = new ClientSecretCredential(
    tenantId: Environment.GetEnvironmentVariable("AAD_TENANT_ID")!,
    clientId: Environment.GetEnvironmentVariable("AAD_CLIENT_ID")!,
    clientSecret: Environment.GetEnvironmentVariable("AAD_CLIENT_SECRET")!,
    options: new TokenCredentialOptions()
);

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.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: 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 of the Azure Cosmos DB hierarchy including accounts, databases, containers, and items.

Każdy typ zasobu jest reprezentowany przez co najmniej jedną skojarzną klasę platformy .NET. 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
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.

Tworzenie bazy danych w usłudze Azure Cosmos DB for NoSQL przy użyciu platformy .NET