Rychlý start: Použití služby Azure Cosmos DB pro tabulky se sadou Azure SDK pro .NET

  • Článek
  • Platí pro:
    ✅ Table

V tomto rychlém startu nasadíte základní aplikaci Azure Cosmos DB for Table pomocí sady Azure SDK pro .NET. Azure Cosmos DB for Table je úložiště dat bez schématu, které umožňuje aplikacím ukládat strukturovaná data tabulek v cloudu. Naučíte se vytvářet tabulky, řádky a provádět základní úlohy v rámci prostředku služby Azure Cosmos DB pomocí sady Azure SDK pro .NET.

Referenční dokumentace k | rozhraní API – Balíček zdrojového kódu | knihovny (NuGet) | Azure Developer CLI

Požadavky

  • Azure Developer CLI
  • Docker Desktop
  • .NET 9.0

Pokud nemáte účet Azure, vytvořte si bezplatný účet před tím, než začnete.

Inicializace projektu

Pomocí Azure Developer CLI (azd) vytvořte účet Azure Cosmos DB for Table a nasaďte kontejnerizovanou ukázkovou aplikaci. Ukázková aplikace používá klientskou knihovnu ke správě, vytváření, čtení a dotazování ukázkových dat.

  1. Otevřete terminál v prázdném adresáři.

  2. Pokud ještě nejste ověřeni, ověřte se v Azure Developer CLI pomocí azd auth login. Postupujte podle kroků určených nástrojem k ověření v rozhraní příkazového řádku pomocí vašich upřednostňovaných přihlašovacích údajů Azure.

    azd auth login

  3. Slouží azd init k inicializaci projektu.

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

  4. Během inicializace nakonfigurujte jedinečný název prostředí.

  5. Nasaďte účet služby Azure Cosmos DB pomocí azd up. Šablony Bicep také nasazují ukázkovou webovou aplikaci.

    azd up

  6. Během procesu zřizování vyberte své předplatné, požadované umístění a cílovou skupinu prostředků. Počkejte na dokončení procesu zřizování. Proces může trvat přibližně pět minut.

  7. Po dokončení zřizování prostředků Azure se do výstupu zahrne adresa URL spuštěné webové aplikace.

    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. Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.

Snímek obrazovky se spuštěnou webovou aplikací

Instalace klientské knihovny

Klientská knihovna je k dispozici prostřednictvím Balíčku NuGet Azure.Data.Tables .

  1. Otevřete terminál a přejděte do /src/web složky.

    cd ./src/web

  2. Pokud ještě není nainstalovaný, nainstalujte Azure.Data.Tables balíček pomocí dotnet add package.

    dotnet add package Azure.Data.Tables

  3. Otevřete a zkontrolujte soubor src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj a ověřte, že Azure.Data.Tables položka existuje.

Objektový model

Název Popis
TableServiceClient Tato třída je primární klientskou třídou a slouží ke správě metadat nebo databází pro celý účet.
TableClient Tato třída představuje klienta pro tabulku v rámci účtu.

Příklady kódu

Vzorový kód v šabloně používá tabulku s názvem cosmicworks-products. Tabulka cosmicworks-products obsahuje podrobnosti, jako je název, kategorie, množství, cena, jedinečný identifikátor a příznak prodeje pro každý produkt. Kontejner používá jedinečný identifikátor* jako klíč řádku a kategorii jako klíč oddílu.

Ověření klienta

Tato ukázka vytvoří novou instanci TableServiceClient třídy.

DefaultAzureCredential credential = new();

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

Získání tabulky

Tato ukázka vytvoří instanci TableClient třídy pomocí GetTableClient metody TableServiceClient třídy.

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

Vytvoření entity

Nejjednodušší způsob, jak vytvořit novou entitu v tabulce, je vytvořit třídu, která implementuje ITableEntity rozhraní. Potom můžete do třídy přidat vlastní vlastnosti, které naplní sloupce dat v daném řádku tabulky.

public record Product : ITableEntity
{
    public required string RowKey { get; set; }

    public required string PartitionKey { get; set; }

    public required string Name { get; set; }

    public required int Quantity { get; set; }

    public required decimal Price { get; set; }

    public required bool Clearance { get; set; }

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

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

Vytvořte entitu v tabulce pomocí Product třídy voláním TableClient.AddEntityAsync<T>.

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

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

Získání entity

Pomocí metody můžete načíst konkrétní entitu z tabulky TableClient.GetEntityAsync<T> . partitionKey Zadejte parametry a rowKey určete správný řádek pro rychlé čtení dané entity.

Response<Product> response = await client.GetEntityAsync<Product>(
    rowKey: "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
    partitionKey: "gear-surf-surfboards"
);

Dotazování entit

Po vložení entity můžete také spustit dotaz, který pomocí metody získá všechny entity, které odpovídají určitému TableClient.Query<T> filtru. Tento příklad filtruje produkty podle kategorie pomocí syntaxe LINQ (Language Integrated Query), což je výhoda použití typových ITableEntity modelů, jako je Product třída.

string category = "gear-surf-surfboards";

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

Parsujte stránkované výsledky dotazu tak, že projdete každou stránku výsledků pomocí asynchronní smyčky.

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

Vyčištění prostředků

Pokud už ukázkovou aplikaci nebo prostředky nepotřebujete, odeberte odpovídající nasazení a všechny prostředky.

azd down

Související obsah