Snabbstart: Azure Cosmos DB för NoSQL-klientbibliotek för .NET

GÄLLER FÖR: NoSQL

Kom igång med Azure Cosmos DB-klientbiblioteket för .NET för att skapa databaser, containrar och objekt i ditt konto. Följ de här stegen för att installera paketet och prova exempelkod för grundläggande uppgifter.

Anteckning

Exempelkodfragmenten är tillgängliga på GitHub som ett .NET-projekt.

API-referensdokumentation | Källkod | för bibliotek Paket (NuGet) | Prover

Förutsättningar

Kravkontroll

  • I ett terminal- eller kommandofönster kör du dotnet --version för att kontrollera att .NET SDK är version 6.0 eller senare.
  • Kör az --version (Azure CLI) eller Get-Module -ListAvailable AzureRM (Azure PowerShell) för att kontrollera att du har rätt Azure-kommandoradsverktyg installerade.

Inrätta

Det här avsnittet vägleder dig genom att skapa ett Azure Cosmos DB-konto och konfigurera ett projekt som använder Azure Cosmos DB för NoSQL-klientbibliotek för .NET för att hantera resurser.

Skapa ett Azure Cosmos DB-konto

Tips

Ingen Azure-prenumeration? Du kan prova Azure Cosmos DB kostnadsfritt utan kreditkort. Om du skapar ett konto med den kostnadsfria utvärderingsversionen kan du på ett säkert sätt gå vidare till avsnittet Skapa en ny .NET-app .

Den här snabbstarten skapar ett enda Azure Cosmos DB-konto med hjälp av API:et för NoSQL.

Tips

För den här snabbstarten rekommenderar vi att du använder resursgruppsnamnet msdocs-cosmos-quickstart-rg.

  1. Logga in på Azure-portalen.

  2. Välj Skapa en resurs på Azure Portal-menyn eller på startsidan.

  3. På sidan Nytt söker du efter och väljer Azure Cosmos DB.

  4. sidan Välj API-alternativ väljer du alternativet Skapa i avsnittet NoSQL . Azure Cosmos DB har sex API:er: NoSQL, MongoDB, PostgreSQL, Apache Cassandra, Apache Gremlin och Table. Läs mer om API:et för NoSQL.

    Skärmbild av sidan välj API-alternativ för Azure Cosmos DB.

  5. På sidan Skapa Azure Cosmos DB-konto anger du följande information:

    Inställning Värde Beskrivning
    Prenumeration Prenumerationens namn Välj den Azure-prenumeration som du vill använda för det här Azure Cosmos-kontot.
    Resursgrupp Namn på resursgrupp Välj en resursgrupp eller välj Skapa ny och ange sedan ett unikt namn för den nya resursgruppen.
    Account Name Ett unikt namn Ange ett namn som identifierar ditt Azure Cosmos-konto. Namnet används som en del av ett fullständigt kvalificerat domännamn (FQDN) med suffixet documents.azure.com, så namnet måste vara globalt unikt. Namnet får endast innehålla gemener, siffror och bindestreck (-). Namnet måste också vara mellan 3 och 44 tecken långt.
    Location Den region som är närmast dina användare Välj en geografisk plats som värd för ditt Azure Cosmos DB-konto. Använd den plats som är närmast dina användare för att ge dem så snabb åtkomst till data som möjligt.
    Kapacitetsläge Etablerat dataflöde eller serverlöst Välj Etablerat dataflöde för att skapa ett konto i etablerat dataflödesläge . Välj Serverlös för att skapa ett konto i serverlöst läge.
    Tillämpa rabatt på den kostnadsfria Azure Cosmos DB-nivån Använd eller använd inte Aktivera kostnadsfri nivå för Azure Cosmos DB. Med den kostnadsfria Azure Cosmos DB-nivån får du de första 1 000 RU:erna och 25 GB lagringsutrymme kostnadsfritt på ett konto. Läs mer om den kostnadsfria nivån.

    Anteckning

    Du kan ha upp till ett Azure Cosmos DB-konto på kostnadsfri nivå per Azure-prenumeration och måste anmäla dig när du skapar kontot. Om du inte ser alternativet för att tillämpa rabatten på den kostnadsfria nivån innebär det att ett annat konto i prenumerationen redan har aktiverats med den kostnadsfria nivån.

    Skärmbild av den nya kontosidan för API för NoSQL.

  6. Välj Granska + skapa.

  7. Granska de inställningar du anger och välj sedan Skapa. Det tar några minuter att skapa kontot. Vänta tills portalsidan visas Distributionen är klar innan du går vidare.

  8. Välj Gå till resurs för att gå till sidan för Azure Cosmos DB-kontot.

    Skärmbild av distributionssidan för API för NoSQL-resurs.

  9. Från sidan API för NoSQL-konto väljer du menyalternativet Nycklar i navigeringsmenyn.

    Skärmbild av en API för NoSQL-kontosida. Alternativet Nycklar är markerat på navigeringsmenyn.

  10. Registrera värdena från fälten URI och PRIMÄRNYCKEL . Du använder dessa värden i ett senare steg.

    Skärmbild av sidan Nycklar med olika autentiseringsuppgifter för ett API för NoSQL-konto.

Skapa en ny .NET-app

Skapa ett nytt .NET-program i en tom mapp med önskad terminal. dotnet new Använd kommandot som anger konsolmallen.

dotnet new console

Installera paketet

Lägg till NuGet-paketet Microsoft.Azure.Cosmos i .NET-projektet. dotnet add package Använd kommandot som anger namnet på NuGet-paketet.

dotnet add package Microsoft.Azure.Cosmos

Skapa projektet med dotnet build kommandot .

dotnet build

Kontrollera att bygget lyckades utan fel. De förväntade utdata från bygget bör se ut ungefär så här:

  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)

Konfigurera miljövariabler

Om du vill använda värdena för URI och PRIMÄRNYCKEL i koden sparar du dem i nya miljövariabler på den lokala datorn som kör programmet. Om du vill ange miljövariabeln använder du önskad terminal för att köra följande kommandon:

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

Objektmodell

Innan du börjar skapa programmet ska vi titta på resurshierarkin i Azure Cosmos DB. Azure Cosmos DB har en specifik objektmodell som används för att skapa och komma åt resurser. Azure Cosmos DB skapar resurser i en hierarki som består av konton, databaser, containrar och objekt.

Diagram över Azure Cosmos DB-hierarkin, inklusive konton, databaser, containrar och objekt.

Hierarkiskt diagram som visar ett Azure Cosmos DB-konto högst upp. Kontot har två underordnade databasnoder. En av databasnoderna innehåller två underordnade containernoder. Den andra databasnoden innehåller en enda underordnad containernod. Den enskilda containernoden har tre underordnade objektnoder.

Mer information om hierarkin för olika resurser finns i Arbeta med databaser, containrar och objekt i Azure Cosmos DB.

Du använder följande .NET-klasser för att interagera med dessa resurser:

  • CosmosClient – Den här klassen tillhandahåller en logisk representation på klientsidan för Azure Cosmos DB-tjänsten. Klientobjektet används för att konfigurera och köra begäranden mot tjänsten.
  • Database – Den här klassen är en referens till en databas som kanske, eller kanske inte, finns i tjänsten ännu. Databasen verifieras på serversidan när du försöker komma åt den eller utföra en åtgärd mot den.
  • Container – Den här klassen är en referens till en container som inte heller finns i tjänsten ännu. Containern verifieras på serversidan när du försöker arbeta med den.
  • QueryDefinition – Den här klassen representerar en SQL-fråga och alla frågeparametrar.
  • FeedIterator<> – Den här klassen representerar en iterator som kan spåra den aktuella sidan med resultat och få en ny sida med resultat.
  • FeedResponse<> – Den här klassen representerar en enda sida med svar från iteratorn. Den här typen kan itereras över med hjälp av en foreach loop.

Kodexempel

Exempelkoden som beskrivs i den här artikeln skapar en databas med namnet cosmicworks med en container med namnet products. Tabellen products är utformad för att innehålla produktinformation som namn, kategori, kvantitet och en försäljningsindikator. Varje produkt innehåller också en unik identifierare.

För den här exempelkoden använder containern kategorin som en logisk partitionsnyckel.

Autentisera klienten

Programbegäranden till de flesta Azure-tjänster måste auktoriseras. Att använda klassen DefaultAzureCredential som tillhandahålls av Azure Identity-klientbiblioteket är den rekommenderade metoden för att implementera lösenordslösa anslutningar till Azure-tjänster i din kod.

Du kan också auktorisera begäranden till Azure-tjänster med hjälp av lösenord, anslutningssträngar eller andra autentiseringsuppgifter direkt. Den här metoden bör dock användas med försiktighet. Utvecklare måste vara noggranna för att aldrig exponera dessa hemligheter på en oskyddad plats. Alla som får åtkomst till lösenordet eller den hemliga nyckeln kan autentisera sig. DefaultAzureCredential ger bättre hanterings- och säkerhetsfördelar jämfört med kontonyckeln för att tillåta lösenordsfri autentisering. Båda alternativen visas i följande exempel.

DefaultAzureCredential är en klass som tillhandahålls av Azure Identity-klientbiblioteket för .NET. Mer information om DefaultAzureCredentialfinns i Översikt över DefaultAzureCredential. DefaultAzureCredential stöder flera autentiseringsmetoder och avgör vilken metod som ska användas vid körning. Med den här metoden kan din app använda olika autentiseringsmetoder i olika miljöer (lokalt jämfört med produktion) utan att implementera miljöspecifik kod.

Din app kan till exempel autentisera med dina inloggningsuppgifter för Visual Studio när du utvecklar lokalt och sedan använda en hanterad identitet när den har distribuerats till Azure. Inga kodändringar krävs för den här övergången.

När du utvecklar lokalt med lösenordsfri autentisering kontrollerar du att användarkontot som ansluter till Cosmos DB har tilldelats en roll med rätt behörigheter för att utföra dataåtgärder. För närvarande innehåller Azure Cosmos DB for NoSQL inte inbyggda roller för dataåtgärder, men du kan skapa egna med hjälp av Azure CLI eller PowerShell.

Roller består av en samling behörigheter eller åtgärder som en användare kan utföra, till exempel läsa, skriva och ta bort. Du kan läsa mer om hur du konfigurerar rollbaserad åtkomstkontroll (RBAC) i dokumentationen om cosmos-säkerhetskonfiguration.

Skapa den anpassade rollen

Skapa roller med kommandot az role definition create . Skicka in Cosmos DB-kontonamnet och resursgruppen, följt av en brödtext i JSON som definierar den anpassade rollen. I följande exempel skapas en roll med namnet PasswordlessReadWrite med behörighet att läsa och skriva objekt i Cosmos DB-containrar. Rollen är också begränsad till kontonivån med hjälp av /.

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/*"
        ]
    }]
}'

När kommandot har slutförts kopierar du ID-värdet från fältet name och klistrar in det någonstans för senare användning.

Tilldela sedan rollen som du skapade till användarkontot eller tjänstens huvudnamn som ska ansluta till Cosmos DB. Under den lokala utvecklingen är detta vanligtvis ditt eget konto som är inloggat i Visual Studio eller Azure CLI.

Hämta information om ditt konto med kommandot az ad user .

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

Kopiera värdet för id egenskapen från resultatet och klistra in det någonstans för senare användning.

Slutligen tilldelar du den anpassade rollen som du skapade till ditt användarkonto med hjälp av az cosmosdb sql role assignment create kommandot och de ID:t som du kopierade tidigare.

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

Autentisera med defaultAzureCredential

Kontrollera att du är autentiserad med samma Azure AD konto som du tilldelade rollen till. Du kan autentisera via Azure CLI, Visual Studio eller Azure PowerShell.

Logga in på Azure via Azure CLI med följande kommando:

az login

Du kan autentisera Azure.Identity till Cosmos DB för NoSQL med hjälp DefaultAzureCredential av att lägga till NuGet-paketet i ditt program. DefaultAzureCredential identifierar automatiskt och använder det konto som du loggade in med i föregående steg.

dotnet add package Azure.Identity

Öppna filen från projektkatalogen Program.cs . I redigeringsprogrammet lägger du till med hjälp av direktiv för Microsoft.Azure.Cosmos namnrymderna och Azure.Identity .

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

Definiera en ny instans av CosmosClient klassen med konstruktorn och Environment.GetEnvironmentVariable för att läsa COSMOS_ENDPOINT miljövariabeln som du skapade tidigare.

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

Mer information om olika sätt att skapa en CosmosClient instans finns i Komma igång med Azure Cosmos DB för NoSQL och .NET.

Skapa och fråga databasen

Därefter skapar du en databas och container för att lagra produkter och utför frågor för att infoga och läsa dessa objekt.

Med klientbiblioteken Microsoft.Azure.Cosmos kan du utföra dataåtgärder med hjälp av Azure RBAC. Men för att autentisera hanteringsåtgärder som att skapa och ta bort databaser måste du använda RBAC via något av följande alternativ:

Azure CLI-metoden används i det här exemplet. Använd kommandona az cosmosdb sql database create och az cosmosdb sql container create för att skapa en Cosmos DB NoSQL-databas och container.

# 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

När resurserna har skapats använder du klasser från klientbiblioteken Microsoft.Azure.Cosmos för att ansluta till och köra frågor mot databasen.

Hämta databasen

CosmosClient.GetDatabase Använd metoden returnerar en referens till den angivna databasen.

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

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

Hämta containern

Database.GetContainer Returnerar en referens till den angivna containern.

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

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

Skapa ett objekt

Det enklaste sättet att skapa ett nytt objekt i en container är att först skapa en C#- klass eller posttyp med alla medlemmar som du vill serialisera till JSON. I det här exemplet har C#-posten en unik identifierare, ett categoryId-fält för partitionsnyckeln och extra kategoriNamn, namn, kvantitet och försäljningsfält .

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

Skapa ett objekt i containern genom att anropa 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}]");

Mer information om hur du skapar, utökar eller ersätter objekt finns i Skapa ett objekt i Azure Cosmos DB för NoSQL med .NET.

Hämta ett objekt

I Azure Cosmos DB kan du utföra en punktläsningsåtgärd med hjälp av både fälten unik identifierare (id) och partitionsnyckel. I SDK anropar du Container.ReadItemAsync<> att skicka in båda värdena för att returnera en deserialiserad instans av din C#-typ.

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

Mer information om hur du läser objekt och parsar svaret finns i Läsa ett objekt i Azure Cosmos DB för NoSQL med .NET.

Frågeobjekt

När du har infogat ett objekt kan du köra en fråga för att hämta alla objekt som matchar ett visst filter. Det här exemplet kör SQL-frågan: SELECT * FROM products p WHERE p.categoryId = "61dba35b-4f02-45c5-b648-c6badc0cbd79". I det här exemplet används QueryDefinition-typen och ett parametriserat frågeuttryck för partitionsnyckelfiltret. När frågan har definierats anropar du Container.GetItemQueryIterator<> för att hämta en resultat-iterator som hanterar sidorna med resultaten. Använd sedan en kombination av while och foreach loopar för att hämta sidor med resultat och sedan iterera över de enskilda objekten.

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

Kör koden

Den här appen skapar ett API för NoSQL-databas och container. Exemplet skapar sedan ett objekt och läser sedan exakt samma objekt tillbaka. Slutligen utfärdar exemplet en fråga som bara ska returnera det enskilda objektet. Med varje steg matar exemplet ut metadata till konsolen om de steg som har utförts.

Om du vill köra appen använder du en terminal för att navigera till programkatalogen och köra programmet.

dotnet run

Utdata för appen bör likna det här exemplet:

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

Rensa resurser

När du inte längre behöver API:et för NoSQL-kontot kan du ta bort motsvarande resursgrupp.

  1. Gå till den resursgrupp som du skapade tidigare i Azure Portal.

    Tips

    I den här snabbstarten rekommenderade vi namnet msdocs-cosmos-quickstart-rg.

  2. Välj Ta bort resursgrupp.

    Skärmbild av alternativet Ta bort resursgrupp i navigeringsfältet för en resursgrupp.

  3. I dialogrutan Vill du ta bort anger du namnet på resursgruppen och väljer sedan Ta bort.

    Skärmbild av bekräftelsesidan för borttagning för en resursgrupp.

Nästa steg

I den här snabbstarten har du lärt dig hur du skapar ett Azure Cosmos DB för NoSQL-konto, skapar en databas och skapar en container med hjälp av .NET SDK. Nu kan du fördjupa dig i en självstudie där du hanterar dina Azure Cosmos DB för NoSQL-resurser och -data med hjälp av ett .NET-konsolprogram.