Teilen über

Schnellstart: Azure Cosmos DB for Table-Clientbibliothek für .NET

  • Artikel

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 Tabellen, Zeilen und grundlegende Aufgaben innerhalb Ihrer Azure Cosmos DB-Ressource mithilfe des Azure SDK for .NET erstellen

API-Referenzdokumentation | Quellcode der Bibliothek | Paket (NuGet) | Azure Developer CLI

Voraussetzungen

Initialisieren des Projekts

Verwenden Sie 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.

  1. Öffnen Sie ein Terminal in einem leeren Verzeichnis.

  2. Wenn Sie noch nicht authentifiziert sind, authentifizieren Sie sich mithilfe von azd auth login bei der 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

  3. Verwenden Sie azd init, um das Projekt zu initialisieren.

    azd init --template cosmos-db-table-dotnet-quickstart

  4. Konfigurieren Sie während der Initialisierung einen eindeutigen Umgebungsnamen.

  5. Stellen Sie das Azure Cosmos DB-Konto mit azd up bereit. Die Bicep-Vorlagen stellen auch eine Beispielwebanwendung bereit.

    azd up

  6. Wählen Sie während des Bereitstellungsprozesses Ihr Abonnement, den gewünschten Standort und die Zielressourcengruppe aus. Warten Sie auf den Abschluss des Bereitstellungsvorgangs. Dieser Prozess kann ca. fünf Minuten dauern.

  7. 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.

  8. 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.

    Screenshot der ausgeführten Web-App.

Installieren der Clientbibliothek

Die Clientbibliothek ist über NuGet als Azure.Data.Tables-Paket verfügbar.

  1. Öffnen Sie ein Terminal, und navigieren Sie zu dem /src/web-Ordner.

    cd ./src/web

  2. Installieren Sie das Azure.Data.Tables-Paket mithilfe von dotnet add package, falls es noch nicht installiert ist.

    dotnet add package Azure.Data.Tables

  3. Öffnen Sie die src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj Datei, um zu überprüfen, ob der Azure.Data.Tables Eintrag vorhanden ist.

Objektmodell

name Beschreibung
TableServiceClient Diese Klasse ist die primäre Clientklasse und wird verwendet, um kontoweite Metadaten oder Datenbanken zu verwalten.
TableClient Diese Klasse stellt den Client für eine Tabelle innerhalb des Kontos dar.

Codebeispiele

Der Beispielcode in der Vorlage verwendet eine Tabelle mit dem Namen cosmicworks-products. Die Tabelle cosmicworks-products enthält Details wie Name, Kategorie, Menge, Preis, eindeutiger Bezeichner und ein Verkaufsflag für jedes Produkt. Der Container verwendet einen eindeutigen Bezeichner* als Zeilenschlüssel und Kategorie als Partitionsschlüssel.

Authentifizieren des Clients

Dieses Beispiel erstellt eine neue Instanz der TableServiceClient-Klasse.

TableServiceClient serviceClient = new(
    endpoint: new Uri("<azure-cosmos-db-table-account-endpoint>"),
    credential
);

Tabelle abrufen

In diesem Beispiel wird eine Instanz der Klasse TableClient mithilfe der Methode GetTableClient der Klasse TableServiceClient erstellt.

TableClient client = serviceClient.GetTableClient(
    tableName: "<azure-cosmos-db-table-name>"
);

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.

public record Product : ITableEntity
{
    public string RowKey { get; set; } = $"{Guid.NewGuid()}";

    public string PartitionKey { get; set; } = String.Empty;

    public string Name { get; set; } = String.Empty;

    public int Quantity { get; set; } = 0;

    public decimal Price { get; set; } = 0.0m;

    public bool Clearance { get; set; } = false;

    public ETag ETag { get; set; } = ETag.All;

    public DateTimeOffset? Timestamp { get; set; }
};

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

Product entity = new()
{
    RowKey = "68719518391",
    PartitionKey = "gear-surf-surfboards",
    Name = "Surfboard",
    Quantity = 10,
    Price = 300.00m,
    Clearance = true
};

Response response = await client.UpsertEntityAsync<Product>(
    entity: entity,
    mode: TableUpdateMode.Replace
);

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.

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "68719518391",
    partitionKey: "gear-surf-surfboards"
);

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.

string category = "gear-surf-surfboards";

AsyncPageable<Product> results = client.QueryAsync<Product>(
    product => product.PartitionKey == category
);

Analysieren Sie die paginierten Ergebnisse der Abfrage, indem Sie jede Seite der Ergebnisse mithilfe einer asynchronen Schleife durchlaufen.

List<Product> entities = new();
await foreach (Product product in results)
{
    entities.Add(product);
}

Bereinigen von Ressourcen

Wenn Sie die Beispielanwendung oder Ressourcen nicht mehr benötigen, entfernen Sie die entsprechende Bereitstellung und alle Ressourcen.

azd down

Zugehöriger Inhalt