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

  • Artikel
  • 9 Minuten Lesedauer

GILT FÜR: Tabellen-API

Dieser Schnellstart zeigt Ihnen, wie Sie mit der Azure Cosmos DB Table API aus einer .NET-Anwendung heraus arbeiten können. Die Tabellen-API von Azure Cosmos DB ist ein schemaloser Datenspeicher, der es Anwendungen ermöglicht, strukturierte NoSQL-Daten in der Cloud zu speichern. Sie erfahren, wie Sie Tabellen, Zeilen und grundlegende Aufgaben in Ihrer Cosmos DB-Ressource mithilfe des Azure.Data.Tables-Pakets (NuGet) erstellen und ausführen.

Hinweis

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

Tabellen-API Referenzdokumentation | azure.Data.Tables Package (NuGet)

Voraussetzungen

Prüfen der Voraussetzungen

  • Führen Sie in einem Terminal- oder Befehlsfenster dotnet --list-sdks aus, um sich zu vergewissern, dass .NET 6.x eine der verfügbaren Versionen 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

In diesem Abschnitt erfahren Sie, wie Sie ein Azure Cosmos-Konto erstellen und ein Projekt einrichten, das die Tabellen-API NuGet-Pakete verwendet.

Erstellen eines Azure Cosmos DB-Kontos

Mit diesem Schnellstart wird ein einzelnes Azure Cosmos DB-Konto mithilfe der Tabellen-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-Tabellen-API-Konto mit Standardeinstellungen zu erstellen.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --capabilities EnableTable

Tabellen-API Verbindungszeichenfolge abrufen

  1. Suchen Sie mit dem Befehl az cosmosdb list-connection-strings die Tabellen-API-Verbindungszeichenfolge in der Liste der Verbindungszeichenfolgen für das Konto.

    az cosmosdb list-connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Zeichnen Sie die PRIMARY KEY-Werte (Primärschlüsselwerte) auf. 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 dotnet new console, um eine neue Konsolen-App zu erstellen.

dotnet new console -output <app-name>

Installieren des NuGet-Pakets

Fügen Sie das Azure.Data.Tables NuGet-Paket zu dem neuen .NET-Projekt hinzu. Verwenden Sie den dotnet add package-Befehl, der den Namen des NuGet Pakets angibt.

dotnet add package Azure.Data.Tables

Konfigurieren von Umgebungsvariablen

Wenn Sie die Werte von CONNECTION STRING (Verbindungszeichenfolge) in Ihrem Code verwenden möchten, legen diesen Wert auf dem lokalen Computer fest, auf dem die Anwendung ausgeführt wird. Verwenden Sie zum Festlegen der Umgebungsvariablen Ihr bevorzugtes Terminal, um die folgenden Befehle auszuführen:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Codebeispiele

Der in diesem Artikel beschriebene Beispielcode erstellt eine Tabelle namens adventureworks. Jede Tabellenzeile enthält die Details eines Produkts wie Name, Kategorie, Menge und Verkaufsanzeige. Jedes Produkt enthält außerdem einen eindeutigen Bezeichner.

Für die Interaktion mit diesen Ressourcen verwenden Sie die folgenden Tabellen-API-Klassen:

  • TableServiceClient - Diese Klasse bietet Methoden zum Ausführen von Dienstebenenvorgängen mit Azure Cosmos DB Tabellen-API.
  • TableClient - Mit dieser Klasse können Sie mit Tabellen interagieren, die in der Azure Cosmos DB Tabellen-API gehostet werden.
  • TableEntity - Diese Klasse ist ein Verweis auf eine Zeile in einer Tabelle, mit der Sie Eigenschaften und Spaltendaten verwalten können.

Authentifizieren des Clients

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

using Azure.Data.Tables;

Definieren Sie eine neue Instanz der TableServiceClient-Klasse mit dem Konstruktor und Environment.GetEnvironmentVariable für das Lesen der Verbindungszeichenfolge, die Sie zuvor festgelegt haben.

// New instance of the TableClient class
TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("COSMOS_CONNECTION_STRING"));

Erstellen einer Tabelle

Rufen Sie eine Instanz von TableClient mit Hilfe der Klasse TableServiceClient ab. Verwenden Sie die TableClient.CreateIfNotExistsAsync Methode auf TableClient zum Erstellen einer neuen Tabelle, wenn noch keine vorhanden ist. Diese Methode gibt einen Verweis auf die bereits vorhandene oder neu erstellte Tabelle zurück.

// New instance of TableClient class referencing the server-side table
TableClient tableClient = tableServiceClient.GetTableClient(
    tableName: "adventureworks"
);

await tableClient.CreateIfNotExistsAsync();

Erstellen eines Elements

Die einfachste Möglichkeit zum Erstellen eines neuen Elements in einer Tabelle besteht darin, eine Klasse zu erstellen, die die ITableEntity Schnittstelle implementiert. Anschließend können Sie der Klasse eigene Eigenschaften hinzufügen, um Spalten von Daten in dieser Tabellenzeile aufzufüllen.

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

Erstellen Sie ein Element in der Auflistung mithilfe der Product Klasse, indem Sie TableClient.AddEntityAsync<T> aufrufen.

// Create new item using composite key constructor
var prod1 = new Product()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Ocean Surfboard",
    Quantity = 8,
    Sale = true
};

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(prod1);

Abrufen eines Elements

Sie können ein bestimmtes Element aus einer Tabelle mithilfe der TableEntity.GetEntityAsync<T> Methode abrufen. Stellen Sie die partitionKey und rowKey Parameter bereit, um die richtige Zeile zu identifizieren, um ein schnelles Lesen dieses Elements auszuführen.

// Read a single item from container
var product = await tableClient.GetEntityAsync<Product>(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);
Console.WriteLine("Single product:");
Console.WriteLine(product.Value.Name);

Abfrageelemente

Nachdem Sie ein Element eingefügt haben, können Sie auch eine Abfrage durchführen, um alle Elemente zu erhalten, die einem bestimmten Filter entsprechen, indem Sie die Methode TableClient.Query<T> verwenden. In diesem Beispiel werden Produkte nach Kategorie mithilfe der Linq-Syntax gefiltert, die ein Vorteil der Verwendung von stark typisierten ITableEntity Modellen wie der Product Klasse ist.

Hinweis

Sie können auch Elemente mithilfe der OData-Syntax abfragen. Sie können ein Beispiel für diesen Ansatz im Abfragedaten-Lernprogramm sehen.

// Read multiple items from container
var prod2 = new Product()
{
    RowKey = "68719518390",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sand Surfboard",
    Quantity = 5,
    Sale = false
};

await tableClient.AddEntityAsync<Product>(prod2);

var products = tableClient.Query<Product>(x => x.PartitionKey == "gear-surf-surfboards");

Console.WriteLine("Multiple products:");
foreach (var item in products)
{
    Console.WriteLine(item.Name);
}

Ausführen des Codes

Diese App erstellt eine Azure Cosmos Tabellen-API Tabelle. Anschließend erstellt das Beispiel ein Element und liest dann dasselbe Element wieder ein. Schließlich erstellt das Beispiel ein zweites Element und führt dann eine Abfrage aus, die mehrere Elemente 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:

Single product name: 
Yamba Surfboard
Multiple products:
Yamba Surfboard
Sand Surfboard

Bereinigen von Ressourcen

Wenn Sie das Azure Cosmos DB-Tabellen-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 Tabellen-API-Konto anlegen, eine Tabelle erstellen und Einträge mit dem .NET SDK verwalten. Sie können nun tiefer in das SDK eintauchen, um zu erfahren, wie Sie erweiterte Datenabfragen und Verwaltungsaufgaben in Ihren Azure Cosmos DB Tabellen-API-Ressourcen ausführen können.

Erste Schritte mit Azure Cosmos DB Tabellen-API und .NET