Schnellstart: Azure Cosmos DB for Table für .NET
GILT FÜR: Tabelle
In dieser Schnellstartanleitung erfahren Sie, wie Sie mit Azure Cosmos DB for Table aus einer .NET-Anwendung heraus arbeiten. Azure Cosmos DB for Table ist ein schemaloser Datenspeicher, der es Anwendungen ermöglicht, strukturierte NoSQL-Daten in der Cloud zu speichern. Sie erfahren, wie Sie mithilfe des NuGet-Pakets Azure.Data.Tables innerhalb Ihrer Azure Cosmos DB-Ressource Tabellen und Zeilen erstellen und grundlegende Aufgaben ausführen.
Hinweis
Die Beispielcodeausschnitte sind auf GitHub als .NET-Projekt verfügbar.
API for Table-Referenzdokumentation | Azure.Data.Tables-Paket (NuGet)
Voraussetzungen
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- GitHub-Konto
- Ein Azure-Konto mit einem aktiven Abonnement. Sie können kostenlos ein Konto erstellen.
- Azure Developer CLI
- Docker Desktop
Einrichten
Stellen Sie den Entwicklungscontainer dieses Projekts in Ihrer Umgebung bereit. Verwenden Sie dann die Azure Developer CLI (azd), um ein Azure Cosmos DB for Table-Konto zu erstellen und eine containerisierte Beispielanwendung bereitzustellen. Die Beispielanwendung verwendet die Clientbibliothek zum Verwalten, Erstellen, Lesen und Abfragen von Beispieldaten.
Wichtig
GitHub-Konten enthalten eine Berechtigung für Speicher und Kernstunden, für die jeweils keine Kosten anfallen. Weitere Informationen finden Sie unter Monatlich enthaltene Speicherkapazität und Kernstunden für GitHub-Konten.
Öffnen Sie ein Terminal im Stammverzeichnis des Projekts.
Authentifizieren Sie sich mithilfe von
azd auth login
bei Azure Developer CLI. Führen Sie die vom Tool angegebenen Schritte aus, um sich mit Ihren bevorzugten Azure-Anmeldeinformationen bei der CLI zu authentifizieren.azd auth login
Verwenden Sie
azd init
, um das Projekt zu initialisieren.azd init
Konfigurieren Sie während der Initialisierung einen eindeutigen Umgebungsnamen.
Tipp
Der Umgebungsname wird auch als Name der Zielressourcengruppe verwendet. Ziehen Sie für diese Schnellstartanleitung die Verwendung von
msdocs-cosmos-db
in Betracht.Stellen Sie das Azure Cosmos DB-Konto mit
azd up
bereit. Die Bicep-Vorlagen stellen auch eine Beispielwebanwendung bereit.azd up
Wählen Sie während des Bereitstellungsprozesses Ihr Abonnement und den gewünschten Standort aus. Warten Sie auf den Abschluss des Bereitstellungsvorgangs. Dieser Prozess kann ca. fünf Minuten dauern.
Sobald die Bereitstellung Ihrer Azure-Ressourcen abgeschlossen ist, enthält die Ausgabe eine URL zur ausgeführten Webanwendung.
Deploying services (azd deploy) (✓) Done: Deploying service web - Endpoint: <https://[container-app-sub-domain].azurecontainerapps.io> SUCCESS: Your application was provisioned and deployed to Azure in 5 minutes 0 seconds.
Verwenden Sie die URL in der Konsole, um im Browser zu Ihrer Webanwendung zu navigieren. Sehen Sie sich die Ausgabe der ausgeführten App an.
Installieren der Clientbibliothek
Die Clientbibliothek ist über NuGet als Microsoft.Azure.Cosmos
-Paket verfügbar.
Öffnen Sie ein Terminal, und navigieren Sie zu dem
/src/web
-Ordner.cd ./src/web
Installieren Sie das
Azure.Data.Tables
-Paket mithilfe vondotnet add package
, falls es noch nicht installiert ist.dotnet add package Azure.Data.Tables
Installieren Sie außerdem das
Azure.Identity
-Paket (sofern noch nicht installiert).dotnet add package Azure.Identity
Öffnen Sie die Datei src/web/Cosmos.Samples.Table.Quickstart.Web.csproj und überprüfen Sie, ob die beiden Einträge
Microsoft.Azure.Cosmos
undAzure.Identity
vorhanden sind.
Codebeispiele
- Authentifizieren des Clients
- Erstellen einer Tabelle
- Erstellen eines Elements
- Abrufen eines Elements
- Abfrageelemente
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 Klassen der API für Table:
TableServiceClient
: Diese Klasse bietet Methoden zum Ausführen von Vorgängen auf Dienstebene mit Azure Cosmos DB for Table.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 unter Verwendung des Konstruktors sowie Environment.GetEnvironmentVariable
zum Lesen der Anmeldeinformationen.
// 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. Erstellen Sie mithilfe der TableClient.CreateIfNotExistsAsync
-Methode für TableClient
eine neue Tabelle, wenn noch keine vorhanden ist. Diese Methode gibt einen Verweis auf die 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 TableClient.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 einen Vorteil bei der Verwendung von typisierten ITableEntity
-Modellen wie der Klasse Product
darstellt.
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 DB for Table-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. Das Beispiel gibt in der Konsole bei jedem Schritt Metadaten zu den ausgeführten Schritten 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 for Table-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 dieser Schnellstartanleitung haben Sie erfahren, wie Sie ein Azure Cosmos DB for Table-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 umfassendere Datenabfragen und Verwaltungsaufgaben in Ihren Azure Cosmos DB for Table-Ressourcen ausführen können.