Aan de slag met Azure Cosmos DB for NoSQL met .NET

VAN TOEPASSING OP: NoSQL

In dit artikel leest u hoe u verbinding maakt met Azure Cosmos DB for NoSQL met behulp van de .NET SDK. Zodra u verbinding hebt gemaakt, kunt u bewerkingen uitvoeren op databases, containers en items.

Pakket (NuGet) | Samples | API reference | Library source code | Give Feedback

Vereisten

Uw project instellen

De .NET-consoletoepassing maken

Maak een nieuwe .NET-toepassing met behulp van de dotnet new opdracht met de consolesjabloon .

dotnet new console

Importeer het Microsoft.Azure.Cosmos NuGet-pakket met behulp van de dotnet add package opdracht.

dotnet add package Microsoft.Azure.Cosmos

Bouw het project met de dotnet build opdracht.

dotnet build

Verbinding maken naar Azure Cosmos DB for NoSQL

Als u verbinding wilt maken met de API voor NoSQL van Azure Cosmos DB, maakt u een exemplaar van de CosmosClient klasse. Deze klasse is het startpunt om alle bewerkingen uit te voeren op databases. Er zijn drie belangrijke manieren om verbinding te maken met een API voor NoSQL-account met behulp van de CosmosClient-klasse :

Verbinding maken met een eindpunt en sleutel

De meest voorkomende constructor voor CosmosClient heeft twee parameters:

Parameter Voorbeeldwaarde Omschrijving
accountEndpoint COSMOS_ENDPOINT Omgevingsvariabele API voor NoSQL-eindpunt voor alle aanvragen
authKeyOrResourceToken COSMOS_KEY Omgevingsvariabele Accountsleutel of resourcetoken dat moet worden gebruikt bij het verifiëren

Uw accounteindpunt en -sleutel ophalen

  1. Maak een shellvariabele voor resourceGroupName.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-dotnet-howto-rg"
    
  2. Gebruik de az cosmosdb list opdracht om de naam van het eerste Azure Cosmos DB-account in uw resourcegroep op te halen en op te slaan in de accountName-shellvariabele .

    # Retrieve most recently created account name
    accountName=$(
        az cosmosdb list \
            --resource-group $resourceGroupName \
            --query "[0].name" \
            --output tsv
    )
    
  3. Haal de API voor NoSQL-eindpunt-URI voor het account op met behulp van de az cosmosdb show opdracht.

    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query "documentEndpoint"
    
  4. Zoek de PRIMAIRE SLEUTEL in de lijst met sleutels voor het account met de az-cosmosdb-keys-list opdracht.

    az cosmosdb keys list \
        --resource-group $resourceGroupName \
        --name $accountName \
        --type "keys" \
        --query "primaryMasterKey"
    
  5. Noteer de waarden voor de URI en PRIMAIRE SLEUTEL . U gebruikt deze referenties later.

Als u de URI - en PRIMAIRE SLEUTEL-waarden in uw .NET-code wilt gebruiken, moet u deze behouden tot nieuwe omgevingsvariabelen op de lokale computer waarop de toepassing wordt uitgevoerd.

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

CosmosClient maken met accounteindpunt en -sleutel

Maak een nieuw exemplaar van de CosmosClient-klasse met de COSMOS_ENDPOINT en COSMOS_KEY omgevingsvariabelen als parameters.

// 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")!
);

Verbinding maken met een verbindingsreeks

Een andere constructor voor CosmosClient bevat slechts één parameter:

Parameter Voorbeeldwaarde Omschrijving
accountEndpoint COSMOS_ENDPOINT Omgevingsvariabele API voor NoSQL-eindpunt voor alle aanvragen
connectionString COSMOS_CONNECTION_STRING Omgevingsvariabele Verbinding maken iontekenreeks naar het API voor NoSQL-account

Uw account ophalen verbindingsreeks

  1. Gebruik de az cosmosdb list opdracht om de naam van het eerste Azure Cosmos DB-account in uw resourcegroep op te halen en op te slaan in de accountName-shellvariabele .

    # Retrieve most recently created account name
    accountName=$(
        az cosmosdb list \
            --resource-group $resourceGroupName \
            --query "[0].name" \
            --output tsv
    )
    
  2. Zoek de PRIMAIRE VERBINDINGSREEKS in de lijst met verbindingsreeks s voor het account met de az-cosmosdb-keys-list opdracht.

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

Als u de waarde PRIMARY CONNECTION STRING in uw .NET-code wilt gebruiken, moet u deze behouden tot een nieuwe omgevingsvariabele op de lokale computer waarop de toepassing wordt uitgevoerd.

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

CosmosClient maken met verbindingsreeks

Maak een nieuw exemplaar van de CosmosClient-klasse met de COSMOS_CONNECTION_STRING omgevingsvariabele als enige parameter.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    connectionString: Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING")!
);

Verbinding maken het Microsoft Identity Platform gebruiken

Gebruik een beveiligingsprincipaal om verbinding te maken met uw API voor NoSQL-account met behulp van het Microsoft Identity Platform en de Microsoft Entra-id. Het exacte type principal is afhankelijk van waar u uw toepassingscode host. De onderstaande tabel fungeert als een snelzoekgids.

Waar de toepassing wordt uitgevoerd Beveiligingsprincipal
Lokale machine (ontwikkelen en testen) Gebruikersidentiteit of service-principal
Azure Beheerde identiteit
Servers of clients buiten Azure Service-principal

Azure.Identity importeren

Het NuGet-pakket Azure.Identity bevat kernverificatiefunctionaliteit die wordt gedeeld tussen alle Azure SDK-bibliotheken.

Importeer het NuGet-pakket Azure.Identity met behulp van de dotnet add package opdracht.

dotnet add package Azure.Identity

Bouw het project opnieuw met de dotnet build opdracht.

dotnet build

Voeg in uw code-editor instructies toe voor Azure.Core en Azure.Identity naamruimten.

using Azure.Core;
using Azure.Identity;

CosmosClient maken met standaardreferentie-implementatie

Als u test op een lokale computer of uw toepassing wordt uitgevoerd op Azure-services met directe ondersteuning voor beheerde identiteiten, moet u een OAuth-token verkrijgen door een DefaultAzureCredential exemplaar te maken.

In dit voorbeeld hebben we het exemplaar opgeslagen in een variabele van het type TokenCredential , omdat dit een meer algemeen type is dat opnieuw kan worden gebruikt in SDK's.

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

Maak een nieuw exemplaar van de CosmosClient-klasse met de COSMOS_ENDPOINT omgevingsvariabele en het TokenCredential-object als parameters.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

CosmosClient maken met een aangepaste referentie-implementatie

Als u van plan bent om de toepassing uit Azure te implementeren, kunt u een OAuth-token verkrijgen met behulp van andere klassen in de Azure.Identity-clientbibliotheek voor .NET. Deze andere klassen zijn ook afgeleid van de TokenCredential klasse.

In dit voorbeeld maken we een ClientSecretCredential exemplaar met behulp van client- en tenant-id's, samen met een clientgeheim.

// 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()
);

U kunt de client-id, tenant-id en clientgeheim verkrijgen wanneer u een toepassing registreert in Microsoft Entra-id. Zie Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het registreren van Microsoft Entra-toepassingen.

Maak een nieuw exemplaar van de CosmosClient-klasse met de COSMOS_ENDPOINT omgevingsvariabele en het TokenCredential-object als parameters.

// New instance of CosmosClient class using a connection string
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT")!,
    tokenCredential: credential
);

Uw toepassing bouwen

Tijdens het bouwen van uw toepassing werkt uw code voornamelijk met vier typen resources:

  • De API voor NoSQL-account, de unieke naamruimte op het hoogste niveau voor uw Azure Cosmos DB-gegevens.

  • Databases, die de containers in uw account organiseren.

  • Containers, die een set afzonderlijke items in uw database bevatten.

  • Items, die een JSON-document in uw container vertegenwoordigen.

Het volgende diagram geeft de relatie tussen deze resources weer.

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

Hiërarchisch diagram met een Azure Cosmos DB-account bovenaan. Het account heeft twee onderliggende databaseknooppunten. Een van de databaseknooppunten bevat twee onderliggende containerknooppunten. Het andere databaseknooppunt bevat één onderliggend containerknooppunt. Dat knooppunt met één container heeft drie onderliggende itemknooppunten.

Elk type resource wordt vertegenwoordigd door een of meer bijbehorende .NET-klassen. Hier volgt een lijst met de meest voorkomende klassen:

Klasse Omschrijving
CosmosClient Deze klasse biedt een logische weergave aan de clientzijde voor de Azure Cosmos DB-service. Het clientobject wordt gebruikt om aanvragen aan de service te configureren en uitvoeren.
Database Deze klasse is een verwijzing naar een database die al dan niet bestaat in de service. De database wordt gevalideerd aan de serverzijde wanneer u deze probeert te openen of een bewerking uitvoert.
Container Deze klasse is een verwijzing naar een container die mogelijk nog niet bestaat in de service. De container wordt gevalideerd aan de serverzijde wanneer u ermee probeert te werken.

In de volgende handleidingen ziet u hoe u elk van deze klassen gebruikt om uw toepassing te bouwen.

Guide Omschrijving
Een database maken Databases maken
Een container maken Containers maken
Een item lezen Een specifiek item lezen
Query's uitvoeren op items Query's uitvoeren op meerdere items

Zie ook

Volgende stappen

Nu u verbinding hebt gemaakt met een API voor NoSQL-account, gebruikt u de volgende handleiding voor het maken en beheren van databases.