Rychlý start: Azure Cosmos DB pro tabulku pro .NET

Článek
03/08/2024

PLATÍ PRO: Tabulka

V tomto rychlém startu se dozvíte, jak začít pracovat se službou Azure Cosmos DB for Table z aplikace .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í balíčku Azure.Data.Tables (NuGet).

Poznámka:

Ukázkové fragmenty kódu jsou k dispozici na GitHubu jako projekt .NET.

Referenční dokumentace | k rozhraní API pro tabulky Azure.Data.Tables Package (NuGet)

Požadavky

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Účet GitHub

Účet Azure s aktivním předplatným. Vytvoření účtu zdarma
Azure Developer CLI
Docker Desktop

Nastavení

Nasaďte vývojový kontejner tohoto projektu do svého prostředí. Pak pomocí Azure Developer CLI (azd) vytvořte účet služby Azure Cosmos DB pro tabulku 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.

Důležité

Účty GitHubu zahrnují nárok na úložiště a hodiny jádra bez poplatků. Další informace najdete v zahrnutých hodinách úložiště a jader pro účty GitHubu.

Otevřete terminál v kořenovém adresáři projektu.
Ověřte se v Rozhraní příkazového řádku Azure Developer CLI pomocí azd auth loginrozhraní příkazového řádku . 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
```
Slouží azd init k inicializaci projektu.
```
azd init
```
Během inicializace nakonfigurujte jedinečný název prostředí.

Tip

Název prostředí se také použije jako název cílové skupiny prostředků. Pro účely tohoto rychlého startu zvažte použití .msdocs-cosmos-db
Nasaďte účet služby Azure Cosmos DB pomocí azd up. Šablony Bicep také nasazují ukázkovou webovou aplikaci.
```
azd up
```
Během procesu zřizování vyberte své předplatné a požadované umístění. Počkejte na dokončení procesu zřizování. Proces může trvat přibližně pět minut.

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.

Pomocí adresy URL v konzole přejděte do webové aplikace v prohlížeči. Sledujte výstup spuštěné aplikace.

Instalace klientské knihovny

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

Otevřete terminál a přejděte do /src/web složky.
```
cd ./src/web
```
Pokud ještě není nainstalovaný, nainstalujte Azure.Data.Tables balíček pomocí dotnet add package.
```
dotnet add package Azure.Data.Tables
```
Pokud ještě není nainstalovaný, nainstalujte Azure.Identity balíček.
```
dotnet add package Azure.Identity
```
Otevřete a zkontrolujte soubor src/web/Cosmos.Samples.Table.Quickstart.Web.csproj a ověřte, že Microsoft.Azure.Cosmos existují obě Azure.Identity položky.

Vzorový kód popsaný v tomto článku vytvoří tabulku s názvem adventureworks. Každý řádek tabulky obsahuje podrobnosti o produktu, jako je název, kategorie, množství a indikátor prodeje. Každý produkt obsahuje také jedinečný identifikátor.

K interakci s těmito prostředky použijete následující rozhraní API pro třídy tabulek:

TableServiceClient – Tato třída poskytuje metody pro provádění operací na úrovni služeb se službou Azure Cosmos DB for Table.
TableClient – Tato třída umožňuje interakci s tabulkami hostovanými v rozhraní TABLE API služby Azure Cosmos DB.
TableEntity – Tato třída je odkazem na řádek v tabulce, která umožňuje spravovat vlastnosti a data sloupců.

Ověření klienta

V adresáři projektu otevřete soubor Program.cs . V editoru přidejte direktivu using pro Azure.Data.Tables.

using Azure.Data.Tables;

Definujte novou instanci TableServiceClient třídy pomocí konstruktoru a Environment.GetEnvironmentVariable načtěte připojovací řetězec, kterou jste nastavili dříve.

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

Vytvoření tabulky

Načtěte instanci TableClient třídy TableServiceClient . Použijte metodu TableClient.CreateIfNotExistsAsyncTableClient pro vytvoření nové tabulky, pokud ještě neexistuje. Tato metoda vrátí odkaz na existující nebo nově vytvořenou tabulku.

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

await tableClient.CreateIfNotExistsAsync();

Vytvoření položky

Nejjednodušší způsob, jak vytvořit novou položku 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.

// 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!;
}

Vytvořte položku v kolekci pomocí Product třídy voláním TableClient.AddEntityAsync<T>.

// 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);

Získání položky

Pomocí metody můžete načíst konkrétní položku z tabulky TableEntity.GetEntityAsync<T> . partitionKey Zadejte parametry a rowKey jako k identifikaci správného řádku pro rychlé čtení této položky.

// 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);

Dotazování položek

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

Poznámka:

Položky můžete dotazovat také pomocí syntaxe OData . Příklad tohoto přístupu si můžete prohlédnout v kurzu Dotazování na data .

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

Spuštění kódu

Tato aplikace vytvoří tabulku rozhraní Table API služby Azure Cosmos DB. Příklad pak vytvoří položku a pak přečte úplně stejnou položku zpět. Nakonec příklad vytvoří druhou položku a pak provede dotaz, který by měl vrátit více položek. V každém kroku příklad vypíše metadata do konzoly o krocích, které provedl.

Pokud chcete aplikaci spustit, přejděte pomocí terminálu do adresáře aplikace a spusťte aplikaci.

dotnet run

Výstup aplikace by měl být podobný tomuto příkladu:

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

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

Pokud už účet služby Azure Cosmos DB pro tabulku nepotřebujete, můžete odstranit odpovídající skupinu prostředků.

az group delete Pomocí příkazu odstraňte skupinu prostředků.

az group delete --name $resourceGroupName

Pomocí rutiny Remove-AzResourceGroup odstraňte skupinu prostředků.

$parameters = @{
    Name = $RESOURCE_GROUP_NAME
}
Remove-AzResourceGroup @parameters

Další kroky

V tomto rychlém startu jste zjistili, jak vytvořit účet služby Azure Cosmos DB pro tabulky, vytvořit tabulku a spravovat položky pomocí sady .NET SDK. Teď se můžete do sady SDK ponořit hlouběji, abyste se dozvěděli, jak provádět pokročilejší dotazy na data a úlohy správy ve službě Azure Cosmos DB for Table Resources.

Začínáme se službou Azure Cosmos DB for Table a .NET