Szybki start: biblioteka tabel usługi Azure Cosmos DB dla platformy .NET

DOTYCZY: Stół

• .NET
• Python
• Node.js
• Java

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 zestawu Azure SDK dla platformy .NET

Dokumentacja interfejsu API — pakiet | kodu | źródłowego biblioteki (NuGet) | Interfejs wiersza polecenia dla deweloperów platformy Azure

Wymagania wstępne

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

Inicjowanie projektu

Użyj interfejsu wiersza polecenia dla deweloperów platformy Azure (azd), aby utworzyć usługę Azure Cosmos DB dla konta 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.

1. Otwórz terminal w pustym katalogu.

2. Jeśli jeszcze nie uwierzytelniono, uwierzytelnij się w interfejsie wiersza polecenia dewelopera 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 --template cosmos-db-table-dotnet-quickstart
   

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

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ę, żądaną lokalizację i docelową grupę zasobów. 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 Azure.Data.Tables .

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. Otwórz plik src/web/Microsoft.Samples.Cosmos.Table.Quickstart.Web.csproj, aby sprawdzić, czy Azure.Data.Tables wpis istnieje.

Model obiektów

Nazwa/nazwisko	opis
TableServiceClient	Ta klasa jest podstawową klasą klienta i służy do zarządzania metadanymi lub bazami danych dla całego konta.
TableClient	Ta klasa reprezentuje klienta dla tabeli w ramach konta.

Przykłady kodu

• Uwierzytelnianie użytkownika
• Pobieranie tabeli
• Tworzenie elementu
• Pobieranie elementu
• Elementy kwerend

Przykładowy kod w szablonie używa tabeli o nazwie cosmicworks-products. Tabela cosmicworks-products zawiera szczegółowe informacje, takie jak nazwa, kategoria, ilość, cena, unikatowy identyfikator i flaga sprzedaży dla każdego produktu. Kontener używa unikatowego identyfikatora* jako klucza wiersza i kategorii jako klucza partycji.

Uwierzytelnianie użytkownika

Ten przykład tworzy nowe wystąpienie TableServiceClient klasy.

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

Pobieranie tabeli

Ten przykład tworzy wystąpienie TableClient klasy przy użyciu GetTableClient metody TableServiceClient klasy.

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

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.

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

Utwórz element w kolekcji przy użyciu klasy, wywołując metodę Product TableClient.AddEntityAsync<T>.

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

Pobieranie elementu

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

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

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

string category = "gear-surf-surfboards";

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

Przeanalizuj wyniki zapytania podzielonego na strony, wykonując pętlę na każdej stronie wyników przy użyciu pętli asynchronicznej.

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

Czyszczenie zasobów

Jeśli nie potrzebujesz już przykładowej aplikacji lub zasobów, usuń odpowiednie wdrożenie i wszystkie zasoby.

azd down

Powiązana zawartość

• przewodnik Szybki start dotyczący Node.js
• Przewodnik Szybki start dla języka Python
• Przewodnik Szybki start dla języka Java