Quickstart: Azure Cosmos DB for NoSQL-clientbibliotheek voor .NET

  • Artikel
  • 18 minuten om te lezen

VAN TOEPASSING OP: NoSQL

Ga aan de slag met de Azure Cosmos DB-clientbibliotheek voor .NET om databases, containers en items in uw account te maken. Volg deze stappen om het pakket te installeren en voorbeeldcode voor basistaken uit te proberen.

Notitie

De voorbeeldcodefragmenten zijn beschikbaar op GitHub als een .NET-project.

API-referentiedocumentatie | Broncode van bibliotheek | Pakket (NuGet) | Samples

Vereisten

Controle van vereisten

  • Voer in een terminal of opdrachtvenster uit dotnet --version om te controleren of de .NET SDK versie 6.0 of hoger is.
  • Voer az --version (Azure CLI) of Get-Module -ListAvailable AzureRM (Azure PowerShell) uit om te controleren of u de juiste Azure-opdrachtregelprogramma's hebt geïnstalleerd.

Instellen

In deze sectie wordt u begeleid bij het maken van een Azure Cosmos DB-account en het instellen van een project dat gebruikmaakt van de Azure Cosmos DB for NoSQL-clientbibliotheek voor .NET om resources te beheren.

Maak een Azure Cosmos DB-account

Tip

Geen Azure-abonnement? U kunt Azure Cosmos DB gratis uitproberen zonder dat u een creditcard nodig hebt. Als u een account maakt met behulp van de gratis proefversie, kunt u veilig doorgaan naar de sectie Een nieuwe .NET-app maken .

In deze quickstart wordt één Azure Cosmos DB-account gemaakt met behulp van de API voor NoSQL.

Tip

Voor deze quickstart raden we u aan de naam msdocs-cosmos-quickstart-rgvan de resourcegroep te gebruiken.

  1. Meld u aan bij de Azure-portal.

  2. Selecteer vanuit het menu van Azure Portal of op de startpagina de optie Een resource maken.

  3. Zoek op de pagina Nieuw naar Azure Cosmos DB en selecteer dit.

  4. Selecteer op de pagina API-optie selecteren de optie Maken in de sectie NoSQL . Azure Cosmos DB heeft zes API's: NoSQL, MongoDB, PostgreSQL, Apache Cassandra, Apache Gremlin en Table. Meer informatie over de API voor NoSQL.

    Schermopname van de pagina api-optie selecteren voor Azure Cosmos DB.

  5. Voer op de pagina Azure Cosmos DB-account maken de volgende gegevens in:

    Instelling Waarde Beschrijving
    Abonnement Abonnementsnaam Selecteer het Azure-abonnement dat u wilt gebruiken voor dit Azure Cosmos-account.
    Resourcegroep Naam van de resourcegroep Selecteer een resourcegroep of selecteer Nieuwe maken en voer vervolgens een unieke naam in voor de nieuwe resourcegroep.
    Accountnaam Een unieke naam Voer een naam in om uw Azure Cosmos-account te identificeren. De naam wordt gebruikt als onderdeel van een FQDN (Fully Qualified Domain Name) met het achtervoegsel documents.azure.com, dus de naam moet wereldwijd uniek zijn. De naam mag alleen kleine letters, cijfers en het koppelteken (-) bevatten. De naam moet ook tussen de 3 en 44 tekens lang zijn.
    Locatie De regio het dichtst bij uw gebruikers Selecteer een geografische locatie waar u het Azure Cosmos DB-account wilt hosten. Gebruik de locatie die zich het dichtst bij uw gebruikers bevindt, zodat ze de snelst mogelijke toegang tot de gegevens hebben.
    Capaciteitsmodus Ingerichte doorvoer of serverloos Selecteer Ingerichte doorvoer om een account te maken in de modus Ingerichte doorvoer. Selecteer Serverloos om een account te maken in de modus serverloos.
    Niveaukorting op gratis laag van Azure Cosmos DB toepassen Toepassen of niet toepassen Schakel de gratis laag van Azure Cosmos DB in. Met de gratis laag van Azure Cosmos DB krijgt u de eerste 1000 RU/s en 25 GB gratis opslagruimte in een account. Meer informatie over de gratis laag.

    Notitie

    U kunt per Azure-abonnement maximaal één gratis laag voor het Azure Cosmos DB-account hebben, en u moet zich aanmelden wanneer u het account maakt. Als u de optie voor het toepassen van de korting voor gratis lagen niet ziet, betekent dit dat er al een ander account in het abonnement is ingeschakeld met een gratis laag.

    Schermopname van de pagina nieuw account voor API voor NoSQL.

  6. Selecteer Controleren + maken.

  7. Controleer de instellingen die u opgeeft en selecteer vervolgens Maken. Het duurt een paar minuten om het account te maken. Wacht totdat op de portalpagina Uw implementatie is voltooid wordt weergegeven voordat u verdergaat.

  8. Selecteer Ga naar resource om naar de Azure Cosmos DB-accountpagina te gaan.

    Schermopname van de implementatiepagina voor DE API voor NoSQL-resource.

  9. Selecteer op de pagina API for NoSQL-account de optie Navigatiemenu Sleutels .

    Schermopname van een API voor NoSQL-accountpagina. De optie Sleutels is gemarkeerd in het navigatiemenu.

  10. Noteer de waarden uit de velden URI en PRIMAIRE SLEUTEL . U gebruikt deze waarden in een latere stap.

    Schermopname van de pagina Sleutels met verschillende referenties voor een API voor NoSQL-account.

Een nieuwe .NET-app maken

Maak een nieuwe .NET-toepassing in een lege map met behulp van de terminal van uw voorkeur. Gebruik de dotnet new opdracht om de consolesjabloon op te geven.

dotnet new console

Het pakket installeren

Voeg het NuGet-pakket Microsoft.Azure.Cosmos toe aan het .NET-project. Gebruik de dotnet add package opdracht om de naam van het NuGet-pakket op te geven.

dotnet add package Microsoft.Azure.Cosmos

Bouw het project met de dotnet build opdracht .

dotnet build

Zorg ervoor dat de build is geslaagd zonder fouten. De verwachte uitvoer van de build moet er ongeveer als volgt uitzien:

  Determining projects to restore...
  All projects are up-to-date for restore.
  dslkajfjlksd -> C:\Users\sidandrews\Demos\dslkajfjlksd\bin\Debug\net6.0\dslkajfjlksd.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Omgevingsvariabelen configureren

Als u de waarden URI en PRIMAIRE SLEUTEL in uw code wilt gebruiken, bewaart u deze in nieuwe omgevingsvariabelen op de lokale computer waarop de toepassing wordt uitgevoerd. Als u de omgevingsvariabele wilt instellen, gebruikt u de terminal van uw voorkeur om de volgende opdrachten uit te voeren:

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

Objectmodel

Voordat u begint met het bouwen van de toepassing, bekijken we de hiërarchie van resources in Azure Cosmos DB. Azure Cosmos DB heeft een specifiek objectmodel dat wordt gebruikt voor het maken en openen van resources. Azure Cosmos DB maakt resources in een hiërarchie die bestaat uit accounts, databases, containers en items.

Diagram van de Azure Cosmos DB-hiërarchie, inclusief accounts, databases, containers en items.

Zie Werken met databases, containers en items in Azure Cosmos DB voor meer informatie over de hiërarchie van verschillende resources.

U gebruikt de volgende .NET-klassen om te communiceren met deze resources:

  • 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 aan de serverzijde gevalideerd wanneer u deze probeert te openen of er een bewerking op uitvoert.
  • Container - Deze klasse is een verwijzing naar een container die mogelijk nog niet bestaat in de service. De container wordt aan de serverzijde gevalideerd wanneer u ermee probeert te werken.
  • QueryDefinition - Deze klasse vertegenwoordigt een SQL-query en eventuele queryparameters.
  • FeedIterator<> - Deze klasse vertegenwoordigt een iterator die de huidige pagina met resultaten kan volgen en een nieuwe pagina met resultaten kan ophalen.
  • FeedResponse<> - Deze klasse vertegenwoordigt één pagina met antwoorden van de iterator. Dit type kan worden herhaald met behulp van een foreach lus.

Codevoorbeelden

Met de voorbeeldcode die in dit artikel wordt beschreven, wordt een database met de naam cosmicworks gemaakt met een container met de naam products. De products tabel is ontworpen om productgegevens te bevatten, zoals naam, categorie, hoeveelheid en een verkoopindicator. Elk product bevat ook een unieke id.

Voor deze voorbeeldcode gebruikt de container de categorie als logische partitiesleutel.

De client verifiëren

Toepassingsaanvragen voor de meeste Azure-services moeten worden geautoriseerd. Het gebruik van de DefaultAzureCredential klasse van de Azure Identity-clientbibliotheek is de aanbevolen methode voor het implementeren van wachtwoordloze verbindingen met Azure-services in uw code.

U kunt aanvragen voor Azure-services ook rechtstreeks autoriseren met behulp van wachtwoorden, verbindingsreeksen of andere referenties. Deze aanpak moet echter met de nodige voorzichtigheid worden gebruikt. Ontwikkelaars moeten ijverig zijn om deze geheimen nooit beschikbaar te maken op een onbeveiligde locatie. Iedereen die toegang krijgt tot het wachtwoord of de geheime sleutel, kan zich verifiëren. DefaultAzureCredential biedt verbeterde beheer- en beveiligingsvoordelen ten opzichte van de accountsleutel om verificatie zonder wachtwoord toe te staan. Beide opties worden in het volgende voorbeeld gedemonstreerd.

DefaultAzureCredential is een klasse die wordt geleverd door de Azure Identity-clientbibliotheek voor .NET. Zie het Overzicht van DefaultAzureCredential voor meer informatie overDefaultAzureCredential. DefaultAzureCredential ondersteunt meerdere verificatiemethoden en bepaalt welke methode tijdens runtime moet worden gebruikt. Met deze aanpak kan uw app verschillende verificatiemethoden gebruiken in verschillende omgevingen (lokaal versus productie) zonder omgevingsspecifieke code te implementeren.

Uw app kan bijvoorbeeld verifiëren met behulp van uw Visual Studio-aanmeldingsreferenties bij het lokaal ontwikkelen en vervolgens een beheerde identiteit gebruiken zodra deze in Azure is geïmplementeerd. Er zijn geen codewijzigingen vereist voor deze overgang.

Wanneer u lokaal ontwikkelt met verificatie zonder wachtwoord, moet u ervoor zorgen dat aan het gebruikersaccount dat verbinding maakt met Cosmos DB, een rol is toegewezen met de juiste machtigingen om gegevensbewerkingen uit te voeren. Momenteel bevat Azure Cosmos DB voor NoSQL geen ingebouwde rollen voor gegevensbewerkingen, maar u kunt uw eigen rollen maken met behulp van de Azure CLI of PowerShell.

Rollen bestaan uit een verzameling machtigingen of acties die een gebruiker mag uitvoeren, zoals lezen, schrijven en verwijderen. Meer informatie over het configureren van op rollen gebaseerd toegangsbeheer (RBAC) vindt u in de cosmos-beveiligingsconfiguratiedocumentatie.

De aangepaste rol maken

Maak rollen met behulp van de az role definition create opdracht . Geef de naam en resourcegroep van het Cosmos DB-account door, gevolgd door een JSON-hoofdtekst die de aangepaste rol definieert. In het volgende voorbeeld wordt een rol met de naam gemaakt PasswordlessReadWrite met machtigingen voor het lezen en schrijven van items in Cosmos DB-containers. De rol is ook gericht op het accountniveau met behulp van /.

az cosmosdb sql role definition create 
    --account-name passwordlessnosql
    --resource-group  passwordlesstesting 
    --body '{
    "RoleName": "PasswordlessReadWrite",
    "Type": "CustomRole",
    "AssignableScopes": ["/"],
    "Permissions": [{
        "DataActions": [
            "Microsoft.DocumentDB/databaseAccounts/readMetadata",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/items/*",
            "Microsoft.DocumentDB/databaseAccounts/sqlDatabases/containers/*"
        ]
    }]
}'

Wanneer de opdracht is voltooid, kopieert u de id-waarde uit het name veld en plakt u deze ergens voor later gebruik.

Wijs vervolgens de rol toe die u hebt gemaakt aan het gebruikersaccount of de service-principal die verbinding maakt met Cosmos DB. Tijdens de lokale ontwikkeling is dit over het algemeen uw eigen account dat is aangemeld bij Visual Studio of de Azure CLI.

Haal de details van uw account op met behulp van de az ad user opdracht .

az ad user show --id "<your-email-address>"

Kopieer de waarde van de id eigenschap uit de resultaten en plak deze ergens voor later gebruik.

Wijs ten slotte de aangepaste rol toe die u hebt gemaakt aan uw gebruikersaccount met behulp van de az cosmosdb sql role assignment create opdracht en de id's die u eerder hebt gekopieerd.

az cosmosdb sql role assignment create 
    --account-name passwordlessnosql
    --resource-group passwordlesstesting
    --scope "/" 
    --principal-id <your-user-id>
    --role-definition-id <your-custom-role-id>

Verifiëren met DefaultAzureCredential

Zorg ervoor dat u bent geverifieerd met hetzelfde Azure AD account waaraan u de rol hebt toegewezen. U kunt zich verifiëren via de Azure CLI, Visual Studio of Azure PowerShell.

Meld u aan bij Azure via de Azure CLI met behulp van de volgende opdracht:

az login

U kunt zich verifiëren bij Cosmos DB for NoSQL door DefaultAzureCredential het Azure.Identity NuGet-pakket toe te voegen aan uw toepassing. DefaultAzureCredential detecteert en gebruikt automatisch het account waarmee u zich in de vorige stap hebt aangemeld.

dotnet add package Azure.Identity

Open het bestand vanuit de Program.cs projectmap. Voeg in de editor using-instructies toe voor de Microsoft.Azure.Cosmos naamruimten en Azure.Identity .

using Microsoft.Azure.Cosmos;
using Azure.Identity;

Definieer een nieuw exemplaar van de CosmosClient klasse met behulp van de constructor en Environment.GetEnvironmentVariable lees de COSMOS_ENDPOINT omgevingsvariabele die u eerder hebt gemaakt.

// New instance of CosmosClient class
using CosmosClient client = new(
    accountEndpoint: Environment.GetEnvironmentVariable("COSMOS_ENDPOINT"),
    tokenCredential: new DefaultAzureCredential()
);

Zie Aan de slag met Azure Cosmos DB voor NoSQL en .NET voor meer informatie over verschillende manieren om een CosmosClient exemplaar te maken.

De database maken en er query's op uitvoeren

Vervolgens maakt u een database en container om producten op te slaan en voert u query's uit om deze items in te voegen en te lezen.

Met de Microsoft.Azure.Cosmos clientbibliotheken kunt u gegevensbewerkingen uitvoeren met behulp van Azure RBAC. Als u echter beheerbewerkingen wilt verifiëren, zoals het maken en verwijderen van databases, moet u RBAC gebruiken via een van de volgende opties:

In dit voorbeeld wordt de Azure CLI-benadering gebruikt. Gebruik de az cosmosdb sql database create opdrachten en az cosmosdb sql container create om een Cosmos DB NoSQL-database en -container te maken.

# Create a SQL API database
az cosmosdb sql database create 
    --account-name msdocs-cosmos-nosql
    --resource-group msdocs
    --name cosmicworks

# Create a SQL API container
az cosmosdb sql container create
    --account-name msdocs-cosmos-nosql 
    --resource-group msdocs
    --database-name cosmicworks
    --name products

Nadat de resources zijn gemaakt, gebruikt u klassen uit de Microsoft.Azure.Cosmos clientbibliotheken om verbinding te maken met en query's uit te voeren op de database.

De database ophalen

Gebruik de CosmosClient.GetDatabase methode retourneert een verwijzing naar de opgegeven database.

// Database reference with creation if it does not already exist
Database database = client.GetDatabase(id: "cosmicworks");

Console.WriteLine($"New database:\t{database.Id}");

De container ophalen

De Database.GetContainer retourneert een verwijzing naar de opgegeven container.

// Container reference with creation if it does not alredy exist
Container container = database.GetContainer(id: "products");

Console.WriteLine($"New container:\t{container.Id}");

Een item maken

De eenvoudigste manier om een nieuw item in een container te maken, is door eerst een C#- klasse of recordtype te maken met alle leden die u wilt serialiseren in JSON. In dit voorbeeld heeft de C#-record een unieke id, een categoryId-veld voor de partitiesleutel en extra categoryName-, naam-, hoeveelheid- en verkoopvelden .

// C# record representing an item in the container
public record Product(
    string id,
    string categoryId,
    string categoryName,
    string name,
    int quantity,
    bool sale
);

Maak een item in de container door aan te roepen Container.CreateItemAsync.

// Create new object and upsert (create or replace) to container
Product newItem = new(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    categoryId: "61dba35b-4f02-45c5-b648-c6badc0cbd79",
    categoryName: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    sale: false
);

Product createdItem = await container.CreateItemAsync<Product>(
    item: newItem,
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Console.WriteLine($"Created item:\t{createdItem.id}\t[{createdItem.categoryName}]");

Zie Een item maken in Azure Cosmos DB voor NoSQL met behulp van .NET voor meer informatie over het maken, uitvoeren of vervangen van items.

Een item ophalen

In Azure Cosmos DB kunt u een puntleesbewerking uitvoeren met behulp van zowel de unieke id (id) als de partitiesleutelvelden. Roep Container.ReadItemAsync<> in de SDK het doorgeven van beide waarden aan om een gedeserialiseerd exemplaar van uw C#-type te retourneren.

// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
    id: "70b63682-b93a-4c77-aad2-65501347265f",
    partitionKey: new PartitionKey("61dba35b-4f02-45c5-b648-c6badc0cbd79")
);

Zie Een item lezen in Azure Cosmos DB voor NoSQL met behulp van .NET voor meer informatie over het lezen van items en het parseren van het antwoord.

Query-items

Nadat u een item hebt ingevoegd, kunt u een query uitvoeren om alle items op te halen die overeenkomen met een specifiek filter. In dit voorbeeld wordt de SQL-query uitgevoerd: SELECT * FROM products p WHERE p.categoryId = "61dba35b-4f02-45c5-b648-c6badc0cbd79". In dit voorbeeld wordt het type QueryDefinition en een query-expressie met parameters gebruikt voor het partitiesleutelfilter. Zodra de query is gedefinieerd, roept u Container.GetItemQueryIterator<> aan om een resultaat-iterator op te halen die de pagina's met resultaten beheert. Gebruik vervolgens een combinatie van while en-lussen foreach om pagina's met resultaten op te halen en herhaal vervolgens de afzonderlijke items.

// Create query using a SQL string and parameters
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.categoryId = @categoryId"
)
    .WithParameter("@categoryId", "61dba35b-4f02-45c5-b648-c6badc0cbd79");

using FeedIterator<Product> feed = container.GetItemQueryIterator<Product>(
    queryDefinition: query
);

while (feed.HasMoreResults)
{
    FeedResponse<Product> response = await feed.ReadNextAsync();
    foreach (Product item in response)
    {
        Console.WriteLine($"Found item:\t{item.name}");
    }
}

De code uitvoeren

Met deze app maakt u een API voor Een NoSQL-database en -container. In het voorbeeld wordt vervolgens een item gemaakt en wordt exact hetzelfde item teruggelezen. Ten slotte geeft het voorbeeld een query uit die alleen dat ene item mag retourneren. Bij elke stap voert het voorbeeld metagegevens uit naar de console over de stappen die zijn uitgevoerd.

Als u de app wilt uitvoeren, gebruikt u een terminal om naar de toepassingsmap te navigeren en de toepassing uit te voeren.

dotnet run

De uitvoer van de app moet er ongeveer uitzien als in dit voorbeeld:

New database:   adventureworks
New container:  products
Created item:   68719518391     [gear-surf-surfboards]

Resources opschonen

Wanneer u de API voor NoSQL-account niet meer nodig hebt, kunt u de bijbehorende resourcegroep verwijderen.

  1. Navigeer naar de resourcegroep die u eerder hebt gemaakt in de Azure Portal.

    Tip

    In deze quickstart hebben we de naam msdocs-cosmos-quickstart-rgaanbevolen.

  2. Selecteer Resourcegroep verwijderen.

    Schermopname van de optie Resourcegroep verwijderen in de navigatiebalk voor een resourcegroep.

  3. Voer in het dialoogvenster Weet u zeker dat u wilt verwijderen de naam van de resourcegroep in en selecteer vervolgens Verwijderen.

    Schermopname van de bevestigingspagina voor verwijderen voor een resourcegroep.

Volgende stappen

In deze quickstart hebt u geleerd hoe u een Azure Cosmos DB voor NoSQL-account maakt, een database maakt en een container maakt met behulp van de .NET SDK. U kunt nu dieper ingaan op een zelfstudie waarin u uw Azure Cosmos DB voor NoSQL-resources en -gegevens beheert met behulp van een .NET-consoletoepassing.

Zelfstudie: Een .NET-consoletoepassing ontwikkelen met Azure Cosmos DB voor NoSQL