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

  • Artykuł

DOTYCZY: Tabeli

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 for Table to bez schematu magazyn danych, który umożliwia aplikacjom przechowywanie ustrukturyzowanych danych NoSQL 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 usłudze GitHub jako projekt platformy .NET.

Dokumentacja referencyjna | interfejsu API dla tabelPakiet Azure.Data.Tables (NuGet)

Wymagania wstępne

Sprawdzanie wymagań wstępnych

  • W terminalu lub oknie polecenia uruchom polecenie dotnet --list-sdks , aby sprawdzić, czy platforma .NET 6.x jest jedną z dostępnych wersji.
  • Uruchom az --version polecenie (interfejs wiersza polecenia platformy Azure) lub Get-Module -ListAvailable AzureRM (Azure PowerShell), aby sprawdzić, czy masz zainstalowane odpowiednie narzędzia wiersza polecenia platformy Azure.

Konfigurowanie

W tej sekcji przedstawiono sposób tworzenia konta usługi Azure Cosmos DB i konfigurowania projektu korzystającego z interfejsu API dla pakietów NuGet tabel.

Tworzenie konta usługi Azure Cosmos DB

Ten przewodnik Szybki start utworzy pojedyncze konto usługi Azure Cosmos DB przy użyciu interfejsu API dla tabeli.

  1. Utwórz zmienne powłoki dla parametrów accountName, resourceGroupName i location.

    # Variable for resource group name
resourceGroupName="msdocs-cosmos-quickstart-rg"
location="westus"

# Variable for account name with a randomnly generated suffix
let suffix=$RANDOM*$RANDOM
accountName="msdocs-$suffix"

  2. Jeśli jeszcze tego nie zrobiono, zaloguj się do interfejsu wiersza polecenia platformy az login Azure przy użyciu polecenia .

  3. Użyj polecenia , az group create aby utworzyć nową grupę zasobów w ramach subskrypcji.

    az group create \
    --name $resourceGroupName \
    --location $location

  4. az cosmosdb create Użyj polecenia , aby utworzyć nowe konto usługi Azure Cosmos DB dla tabel z ustawieniami domyślnymi.

    az cosmosdb create \
    --resource-group $resourceGroupName \
    --name $accountName \
    --locations regionName=$location
    --capabilities EnableTable

Pobieranie interfejsu API dla parametrów połączenia tabeli

  1. Znajdź interfejs API dla parametrów połączenia tabeli z listy parametrów połączenia dla konta za pomocą az cosmosdb list-connection-strings polecenia .

    az cosmosdb list-connection-strings \
    --resource-group $resourceGroupName \
    --name $accountName

  2. Zarejestruj wartości parametrów połączenia tabeli podstawowej . Te poświadczenia będą używane później.

Tworzenie nowej aplikacji .NET

Utwórz nową aplikację .NET w pustym folderze przy użyciu preferowanego terminalu. Użyj polecenia , dotnet new console aby utworzyć nową aplikację konsolową.

dotnet new console --output <app-name>

Instalowanie pakietu NuGet

Dodaj pakiet NuGet Azure.Data.Tables do nowego projektu platformy .NET. dotnet add package Użyj polecenia określającego nazwę pakietu NuGet.

dotnet add package Azure.Data.Tables

Konfigurowanie zmiennych środowiskowych

Aby użyć wartości PARAMETRY POŁĄCZENIA w kodzie, ustaw tę wartość na komputerze lokalnym z uruchomioną aplikacją. Aby ustawić zmienną środowiskową, użyj preferowanego terminalu, aby uruchomić następujące polecenia:

$env:COSMOS_CONNECTION_STRING = "<cosmos-connection-string>"

Przykłady kodu

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ługi 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 klienta

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

Tworzenie tabeli

Pobierz wystąpienie TableClient klasy .TableServiceClient Użyj metody w elemecie TableClient.CreateIfNotExistsAsyncTableClient , 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 implementujące 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 w celu zidentyfikowania poprawnego wiersza w celu szybkiego 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 zapytań

Po wstawieniu elementu można również uruchomić zapytanie, aby pobrać wszystkie elementy pasujące do określonego filtru TableClient.Query<T> przy użyciu metody . Ten przykład filtruje produkty według kategorii przy użyciu składni Linq , która 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ład wyprowadza metadane do konsoli o wykonanych krokach.

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.

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

az group delete --name $resourceGroupName

Następne kroki

W tym przewodniku Szybki start przedstawiono sposób tworzenia konta usługi Azure Cosmos DB dla tabel, tworzenia tabeli i zarządzania 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 o dane i zadania zarządzania w usłudze Azure Cosmos DB dla zasobów tabel.

Rozpoczynanie pracy z usługą Azure Cosmos DB dla tabel i platformy .NET