Schnellstart: Azure Cosmos DB-SQL-API-Clientbibliothek für .NET

GILT FÜR: SQL-API

Erste Schritte mit der Azure Cosmos DB-Clientbibliothek für .NET, um Datenbanken, Container und Elemente in Ihrem Konto zu erstellen. Sie können ein kostenloses Azure Cosmos DB-Testkonto einrichten, ohne eine Kreditkarte oder ein Azure-Abonnement zu benötigen. Führen Sie die nachfolgenden Schritte aus, um das Paket zu installieren und den Beispielcode für grundlegende Aufgaben zu testen.

Hinweis

Die Beispielcodeausschnitte sind auf GitHub als .NET-Projekt verfügbar.

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet) | Beispiele

Voraussetzungen

Prüfen der Voraussetzungen

  • Führen Sie in einem Terminal- oder Befehlsfenster den Befehl dotnet --version aus, um sich zu vergewissern, dass das .NET SDK die Version 6.0 oder höher ist.
  • Führen Sie az --version (Azure CLI) oder Get-Module -ListAvailable AzureRM (Azure PowerShell) aus, um zu überprüfen, ob die geeigneten Azure-Befehlszeilentools installiert wurden.

Einrichten

Dieser Abschnitt führt Sie durch das Erstellen eines Azure Cosmos-Kontos und durch das Einrichten eines Projekts, das die Azure Cosmos DB-SQL-API-Clientbibliothek für .NET zum Verwalten von Ressourcen verwendet.

Erstellen eines Azure Cosmos DB-Kontos

Mit diesem Schnellstart wird ein einzelnes Azure Cosmos DB-Konto mithilfe der SQL-API erstellt.

  1. Erstellen Sie Shellvariablen für accountName, resourceGroupName und location.

    # Variable for resource group name
    resourceGroupName="msdocs-cosmos-quickstart-rg"
    location="westus"
    
    # Variable for account name with a randomnly generated suffix
    let suffix=$RANDOM*$RANDOM
    accountName="msdocs-$suffix"
    
  2. Wenn Sie das noch nicht getan haben, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an.

  3. Erstellen Sie mit dem Befehl az group create eine neue Ressourcengruppe in Ihrem Abonnement.

    az group create \
        --name $resourceGroupName \
        --location $location
    
  4. Verwenden Sie den az cosmosdb create-Befehl, um ein neues Azure Cosmos DB-SQL-API-Konto mit Standardeinstellungen zu erstellen.

    az cosmosdb create \
        --resource-group $resourceGroupName \
        --name $accountName \
        --locations regionName=$location
    
  5. Rufen Sie den SQL-API-Endpunkt-URI für das Konto mithilfe des az cosmosdb show-Befehls ab.

    az cosmosdb show \
        --resource-group $resourceGroupName \
        --name $accountName \
        --query "documentEndpoint"
    
  6. Suchen Sie den PRIMÄRSCHLÜSSEL aus der Liste der Schlüssel für das Konto mit dem az-cosmosdb-keys-list-Befehl.

    az cosmosdb keys list \
        --resource-group $resourceGroupName \
        --name $accountName \
        --type "keys" \
        --query "primaryMasterKey"
    
  7. Aufzeichnen der Werte von URI und PRIMÄRSCHLÜSSEL. Sie werden diese Anmeldeinformationen zu einem späteren Zeitpunkt verwenden.

Erstellen einer neuen .NET-App

Erstellen Sie eine neue .NET-Anwendung in einem leeren Ordner mit Ihrem bevorzugten Terminal. Verwenden Sie den Befehl dotnet new, der die Vorlage Console angibt.

dotnet new console

Installieren des Pakets

Fügen Sie dem .NET-Projekt das NuGet-Paket von microsoft.Azure.Cosmos hinzu. Verwenden Sie den dotnet add package-Befehl, der den Namen des NuGet Pakets angibt.

dotnet add package Microsoft.Azure.Cosmos

Erstellen Sie das Projekt mit dem dotnet build-Befehl.

dotnet build

Stellen Sie sicher, dass der Build ohne Fehler erfolgreich war. Die erwartete Ausgabe aus dem Build sollte etwa wie folgt aussehen:

  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)

Konfigurieren von Umgebungsvariablen

Um die Werte von URI und PRIMÄRSCHLÜSSEL in Ihrem .NET-Code zu verwenden, speichern Sie sie auf neuen Umgebungsvariablen auf dem lokalen Computer, auf dem die Anwendung ausgeführt wird. Verwenden Sie zum Festlegen der Umgebungsvariablen Ihr bevorzugtes Terminal, um die folgenden Befehle auszuführen:

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

Objektmodell

Bevor Sie mit dem Erstellen der Anwendung beginnen, sehen Sie sich die Hierarchie von Ressourcen in Azure Cosmos DB an. Bei Azure Cosmos DB gibt es ein spezifisches Objektmodell, das zum Erstellen von und Zugreifen auf Ressourcen verwendet wird. Die Azure Cosmos DB erstellt Ressourcen in einer Hierarchie, die aus Konten, Datenbanken, Containern und Elementen besteht.

Diagram der Azure Cosmos DB-Hierarchie, einschließlich Konten, Datenbanken, Containern und Elementen.

Hierarchisches Diagramm mit einem Azure Cosmos DB-Konto oben. Das Konto verfügt über zwei untergeordnete Datenbankknoten. Einer der Datenbankknoten enthält zwei untergeordnete Containerknoten. Der andere Datenbankknoten enthält einen einzelnen untergeordneten Containerknoten. Dieser einzelne Containerknoten hat drei untergeordnete Elementknoten.

Weitere Informationen zur Hierarchie der verschiedenen Entitäten finden Sie im Artikel Arbeiten mit Datenbanken, Containern und Elementen in Azure Cosmos DB.

Für die Interaktion mit diesen Ressourcen verwenden Sie die folgenden .NET-Klassen:

  • CosmosClient: Diese Klasse bietet eine clientseitige logische Darstellung für den Azure Cosmos DB-Dienst. Das Clientobjekt wird zum Konfigurieren und Ausführen von Anforderungen für den Dienst verwendet.
  • Database – Diese Klasse ist ein Verweis auf eine Datenbank, die im Dienst möglicherweise vorhanden oder noch nicht vorhanden ist. Die Datenbank wird vom Server aus überprüft, wenn Sie versuchen, darauf zuzugreifen oder einen Vorgang auszuführen.
  • Container - Diese Klasse ist ein Verweis auf einen Container, der möglicherweise noch nicht im Dienst vorhanden ist. Der Container wird vom Server aus überprüft, wenn Sie versuchen, damit zu arbeiten.
  • QueryDefinition - Diese Klasse stellt eine SQL-Abfrage und alle Abfrageparameter dar.
  • FeedIterator<> - Diese Klasse stellt einen Iterator dar, der die aktuelle Seite der Ergebnisse nachverfolgen und eine neue Seite mit Ergebnissen erhalten kann.
  • FeedResponse<> - Diese Klasse stellt eine einzelne Seite von Antworten aus dem Iterator dar. Dieser Typ kann über eine foreach-Schleife durchlaufen werden.

Codebeispiele

Der in diesem Artikel beschriebene Beispielcode erstellt eine Datenbank mit dem Namen adventureworks mit einem Container mit dem Namen products. Die products-Tabelle soll Produktdetails wie Name, Kategorie, Menge und Verkaufsindikator enthalten. Jedes Produkt enthält außerdem einen eindeutigen Bezeichner.

Für diesen Beispielcode verwendet der Container die Kategorie als logischer Partitionsschlüssel.

Authentifizieren des Clients

Öffnen Sie die Program.cs-Datei aus dem Projektverzeichnis heraus. Fügen Sie in Ihrem Editor eine Verwendungsanweisung für Microsoft.Azure.Cosmos hinzu.

using Microsoft.Azure.Cosmos;

Definieren Sie eine neue Instanz der CosmosClient-Klasse mithilfe des Konstruktors und Environment.GetEnvironmentVariable, um die beiden zuvor erstellten Umgebungsvariablen zu lesen.

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

Weitere Informationen zum Erstellen einer CosmosClient-Instanz, sehen Sie Erste Schritte mit Azure Cosmos DB-SQL-API und .NET.

Erstellen einer Datenbank

Verwenden Sie die Methode CosmosClient.CreateDatabaseIfNotExistsAsync zum Erstellen einer neuen Datenbank, wenn noch keine vorhanden ist. Diese Methode gibt einen Verweis auf die bereits vorhandene oder neu erstellte Datenbank zurück.

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

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

Weitere Informationen zum Erstellen einer Datenbank finden Sie unter Erstellen einer Datenbank in Azure Cosmos DB SQL API mithilfe von .NET.

Erstellen eines Containers

Der Database.CreateContainerIfNotExistsAsync erstellt einen neuen Container, wenn er noch nicht vorhanden ist. Diese Methode gibt auch einen Verweis auf den Container zurück.

// Container reference with creation if it does not alredy exist
Container container = await database.CreateContainerIfNotExistsAsync(
    id: "products",
    partitionKeyPath: "/category",
    throughput: 400
);

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

Weitere Informationen zum Erstellen einer Datenbank finden Sie unter Erstellen eines Containers in Azure Cosmos DB SQL API mithilfe von .NET.

Erstellen eines Elements

Die einfachste Möglichkeit zum Erstellen eines neuen Elements in einem Container besteht darin, zuerst eine C#-Klasse oder einen Datensatztyp mit allen Elementen zu erstellen, die Sie in JSON serialisieren möchten. In diesem Beispiel verfügt der C#-Datensatz über einen eindeutigen Bezeichner, ein Kategoriefeld für den Partitionsschlüssel und einen zusätzlichen Namen sowie Felder für Mengen und Verkauf.

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

Erstellen Sie ein Element im Container, indem Sie Container.UpsertItemAsync aufrufen. In diesem Beispiel haben wir uns dafür entschieden, ein Upsert auszuführen statt ein neues Element zu erstellen, wenn Sie diesen Beispielcode mehrmals ausführen.

// Create new object and upsert (create or replace) to container
Product newItem = new(
    id: "68719518391",
    category: "gear-surf-surfboards",
    name: "Yamba Surfboard",
    quantity: 12,
    sale: false
);

Product createdItem = await container.UpsertItemAsync<Product>(
    item: newItem,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

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

Weitere Informationen zu Erstellungs-, Upsert- oder Ersetzungsvorgängen für Elemente finden Sie unter Erstellen eines Elements in der SQL-API von Azure Cosmos DB mithilfe von .NET.

Abrufen eines Elements

In Azure Cosmos DB können Sie einen Punktlesevorgang ausführen, indem Sie sowohl die eindeutigen Bezeichner (id) als auch die Partitionsschlüsselfelder verwenden. Rufen Sie im SDK Container.ReadItemAsync<> auf, das beide Werte durchläuft, um eine deserialisierte Instanz Ihres C#-Typs zurückzugeben.

// Point read item from container using the id and partitionKey
Product readItem = await container.ReadItemAsync<Product>(
    id: "68719518391",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Weitere Informationen zum Lesen von Elementen und zum Analysieren der Antwort finden Sie unter Lesen eines Elements in der SQL-API von Azure Cosmos DB mithilfe von .NET.

Abfrageelemente

Nachdem Sie ein Element eingefügt haben, können Sie eine Abfrage ausführen, um alle Elemente abzurufen, die einem bestimmten Filter entsprechen. In diesem Beispiel wird die SQL-Abfrage ausgeführt: SELECT * FROM todo t WHERE t.partitionKey = 'gear-surf-surfboards'. In diesem Beispiel wird der QueryDefinition-Typ und ein parametrisierter Abfrageausdruck für den Partitionsschlüsselfilter verwendet. Sobald die Abfrage definiert ist, rufen Sie Container.GetItemQueryIterator<> auf, um einen Ergebnis-Iterator abzurufen, der die Seiten der Ergebnisse verwaltet. Verwenden Sie dann eine Kombination aus while- und foreach-Schleifen, um Seiten von Ergebnissen abzurufen und dann über die einzelnen Elemente zu durchlaufen.

// Create query using a SQL string and parameters
var query = new QueryDefinition(
    query: "SELECT * FROM products p WHERE p.category = @key"
)
    .WithParameter("@key", "gear-surf-surfboards");

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

Ausführen des Codes

Diese App erstellt eine Azure Cosmos DB SQL API-Datenbank und Container. Anschließend erstellt das Beispiel ein Element und liest dann dasselbe Element wieder ein. Schließlich verursacht das Beispiel eine Abfrage, die nur dieses einzelne Element zurückgeben soll. In jedem Schritt gibt das Beispiel über die ausgeführten Schritte Metadaten in die Konsole aus.

Verwenden Sie zur Ausführung der App ein Terminal, um zum Anwendungsverzeichnis zu navigieren und die Anwendung auszuführen.

dotnet run

Die Ausgabe der App sollte ähnlich wie dieses Beispiel aussehen:

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

Bereinigen von Ressourcen

Wenn Sie das Azure Cosmos DB-SQL-API-Konto nicht mehr benötigen, können Sie die entsprechende Ressourcengruppe löschen.

Verwenden Sie den Befehl az group delete zum Löschen der Ressourcengruppe.

az group delete --name $resourceGroupName

Nächste Schritte

In diesem Schnellstart haben Sie gelernt, wie Sie ein Azure Cosmos DB SQL API-Konto eine Datenbank und einen Container mithilfe von .NET SDK erstellen. Sie können nun tiefer in das SDK eintauchen, um weitere Daten zu importieren, komplexe Abfragen auszuführen und Ihre Azure Cosmos DB SQL API-Ressourcen zu verwalten.