Szybki start: usługa Azure Cosmos DB dla tabeli dla platformy .NET

DOTYCZY: Tabeli

• .NET
• Java
• Node.js
• Python

W tym przewodniku Szybki start pokazano, jak rozpocząć pracę z usługą Azure Cosmos DB for Table z poziomu aplikacji platformy .NET. Usługa Azure Cosmos DB dla tabel to bez schematu magazyn danych, który umożliwia aplikacjom przechowywanie danych ze strukturą tabeli w chmurze. Dowiesz się, jak tworzyć tabele, wiersze i wykonywać podstawowe zadania w zasobie usługi Azure Cosmos DB przy użyciu pakietu Azure.Data.Tables (NuGet).

Uwaga

Przykładowe fragmenty kodu są dostępne w witrynie GitHub jako projekt platformy .NET.

Dokumentacja interfejsu | API dla tabel Azure.Data.Tables Package (NuGet)

Wymagania wstępne

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Konto usługi GitHub

• Konto platformy Azure z aktywną subskrypcją. Utwórz konto bezpłatnie.
• Interfejs wiersza polecenia dla deweloperów platformy Azure
• Docker Desktop

Konfigurowanie

Wdróż kontener projektowy w swoim środowisku. Następnie użyj interfejsu wiersza polecenia dla deweloperów platformy Azure (azd), aby utworzyć konto usługi Azure Cosmos DB dla tabeli i wdrożyć konteneryzowaną przykładową aplikację. Przykładowa aplikacja używa biblioteki klienta do zarządzania, tworzenia, odczytywania i wykonywania zapytań dotyczących przykładowych danych.

Ważne

Konta usługi GitHub obejmują uprawnienia do magazynowania i godzin podstawowych bez ponoszenia kosztów. Aby uzyskać więcej informacji, zobacz uwzględnione godziny magazynowania i rdzeni dla kont usługi GitHub.

1. Otwórz terminal w katalogu głównym projektu.

2. Uwierzytelnianie w interfejsie wiersza polecenia dla deweloperów platformy Azure przy użyciu polecenia azd auth login. Wykonaj kroki określone przez narzędzie, aby uwierzytelnić się w interfejsie wiersza polecenia przy użyciu preferowanych poświadczeń platformy Azure.

   azd auth login
   

3. Użyj azd init polecenia , aby zainicjować projekt.

   azd init
   

4. Podczas inicjowania skonfiguruj unikatową nazwę środowiska.

   Napiwek

   Nazwa środowiska będzie również używana jako nazwa docelowej grupy zasobów. W tym przewodniku Szybki start rozważ użycie polecenia msdocs-cosmos-db.

5. Wdróż konto usługi Azure Cosmos DB przy użyciu polecenia azd up. Szablony Bicep wdrażają również przykładową aplikację internetową.

   azd up
   

6. Podczas procesu aprowizacji wybierz subskrypcję i żądaną lokalizację. Poczekaj na zakończenie procesu aprowizacji. Proces może potrwać około pięciu minut.

7. Po zakończeniu aprowizacji zasobów platformy Azure adres URL uruchomionej aplikacji internetowej zostanie uwzględniony w danych wyjściowych.

   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. Użyj adresu URL w konsoli, aby przejść do aplikacji internetowej w przeglądarce. Obserwuj dane wyjściowe uruchomionej aplikacji.

   

Instalowanie biblioteki klienta

Biblioteka klienta jest dostępna za pośrednictwem pakietu NuGet Microsoft.Azure.Cosmos .

1. Otwórz terminal i przejdź do /src/web folderu.

   cd ./src/web
   

2. Jeśli pakiet nie został jeszcze zainstalowany, zainstaluj go Azure.Data.Tables przy użyciu polecenia dotnet add package.

   dotnet add package Azure.Data.Tables
   

3. Ponadto zainstaluj Azure.Identity pakiet, jeśli nie został jeszcze zainstalowany.

   dotnet add package Azure.Identity
   

4. Otwórz plik src/web/Cosmos.Samples.Table.Quickstart.Web.csproj, aby sprawdzić, czy oba Microsoft.Azure.CosmosAzure.Identity wpisy istnieją.

Przykłady kodu

• Uwierzytelnianie użytkownika
• Utwórz tabelę
• Tworzenie elementu
• Pobieranie elementu
• Elementy kwerend

Przykładowy kod opisany w tym artykule tworzy tabelę o nazwie adventureworks. Każdy wiersz tabeli zawiera szczegóły produktu, takie jak nazwa, kategoria, ilość i wskaźnik sprzedaży. Każdy produkt zawiera również unikatowy identyfikator.

Do interakcji z tymi zasobami użyjesz następującego interfejsu API dla klas tabel:

• TableServiceClient — Ta klasa udostępnia metody wykonywania operacji na poziomie usług za pomocą usługi Azure Cosmos DB dla tabeli.
• TableClient — Ta klasa umożliwia interakcję z tabelami hostowanymi w interfejsie API tabel usługi Azure Cosmos DB.
• TableEntity — Ta klasa jest odwołaniem do wiersza w tabeli, który umożliwia zarządzanie właściwościami i danymi kolumn.

Uwierzytelnianie użytkownika

W katalogu projektu otwórz plik Program.cs . W edytorze dodaj dyrektywę using dla elementu Azure.Data.Tables.

using Azure.Data.Tables;

Zdefiniuj nowe wystąpienie TableServiceClient klasy przy użyciu konstruktora i Environment.GetEnvironmentVariable odczytaj ustawione wcześniej parametry połączenia.

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

Utwórz tabelę

Pobierz wystąpienie TableClient klasy .TableServiceClient TableClient.CreateIfNotExistsAsync Użyj metody w pliku TableClient , aby utworzyć nową tabelę, jeśli jeszcze nie istnieje. Ta metoda zwróci odwołanie do istniejącej lub nowo utworzonej tabeli.

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

await tableClient.CreateIfNotExistsAsync();

Tworzenie elementu

Najprostszym sposobem utworzenia nowego elementu w tabeli jest utworzenie klasy, która implementuje ITableEntity interfejs. Następnie możesz dodać własne właściwości do klasy, aby wypełnić kolumny danych w tym wierszu tabeli.

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

Utwórz element w kolekcji przy użyciu klasy, wywołując metodę ProductTableClient.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);

Pobieranie elementu

Konkretny element można pobrać z tabeli przy użyciu TableEntity.GetEntityAsync<T> metody . partitionKey Podaj parametry i rowKey jako, aby zidentyfikować prawidłowy wiersz, aby wykonać szybki punkt odczytu tego elementu.

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

Elementy kwerend

Po wstawieniu elementu można również uruchomić zapytanie, aby pobrać wszystkie elementy zgodne z określonym filtrem TableClient.Query<T> przy użyciu metody . W tym przykładzie produkty są filtrowane według kategorii przy użyciu składni Linq , co jest zaletą używania modeli typowych ITableEntity , takich jak Product klasa.

Uwaga

Możesz również wykonywać zapytania o elementy przy użyciu składni OData . Przykład tego podejścia można znaleźć w samouczku Dotyczącym danych zapytań.

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

Uruchamianie kodu

Ta aplikacja tworzy tabelę interfejsu API tabel usługi Azure Cosmos DB. Następnie przykład tworzy element, a następnie odczytuje dokładnie ten sam element z powrotem. Na koniec przykład tworzy drugi element, a następnie wykonuje zapytanie, które powinno zwrócić wiele elementów. W każdym kroku przykładowe metadane są wyświetlane w konsoli programu na temat wykonanych kroków.

Aby uruchomić aplikację, użyj terminalu, aby przejść do katalogu aplikacji i uruchomić aplikację.

dotnet run

Dane wyjściowe aplikacji powinny być podobne do tego przykładu:

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

Czyszczenie zasobów

Jeśli nie potrzebujesz już konta usługi Azure Cosmos DB dla tabeli, możesz usunąć odpowiednią grupę zasobów.

Interfejs wiersza polecenia platformy Azure

Użyj polecenia , az group delete aby usunąć grupę zasobów.

az group delete --name $resourceGroupName

Program PowerShell

Remove-AzResourceGroup Użyj polecenia cmdlet , aby usunąć grupę zasobów.

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

Portal

1. Przejdź do grupy zasobów utworzonej wcześniej w witrynie Azure Portal.

   Napiwek

   W tym przewodniku Szybki start zalecamy nazwę msdocs-cosmos-quickstart-rg.

2. Wybierz pozycję Usuń grupę zasobów.

   

3. W oknie dialogowym Czy na pewno chcesz usunąć, wprowadź nazwę grupy zasobów, a następnie wybierz pozycję Usuń.

   

Następne kroki

W tym przewodniku Szybki start pokazano, jak utworzyć konto usługi Azure Cosmos DB dla tabel, utworzyć tabelę i zarządzać wpisami przy użyciu zestawu SDK platformy .NET. Teraz możesz dowiedzieć się więcej na temat zestawu SDK, aby dowiedzieć się, jak wykonywać bardziej zaawansowane zapytania dotyczące danych i zadania zarządzania w usłudze Azure Cosmos DB dla zasobów tabel.

Wprowadzenie do usługi Azure Cosmos DB dla tabel i platformy .NET