Szybki start: tworzenie aplikacji interfejs API tabel za pomocą zestawu .NET SDK i usługi Azure Cosmos DB

DOTYCZY: interfejs API tabel

W tym przewodniku Szybki start pokazano, jak uzyskać dostęp do usługi Azure Cosmos DB interfejs API tabel z aplikacji platformy .NET. Usługa Cosmos DB interfejs API tabel to magazyn danych bez schematu, który umożliwia aplikacjom przechowywanie ustrukturyzowanych danych NoSQL w chmurze. Ponieważ dane są przechowywane w projekcie bez schematu, nowe właściwości (kolumny) są automatycznie dodawane do tabeli po dodaniu obiektu z nowym atrybutem do tabeli.

Aplikacje .NET mogą uzyskać dostęp do Cosmos DB interfejs API tabel użyciu pakietu NuGet Azure.Data.Tables. Pakiet Azure.Data.Tables to biblioteka platformy .NET Standard 2.0, która działa zarówno z aplikacjami .NET Framework (4.7.2 i nowszymi), jak i z aplikacjami platformy .NET Core (2.0 i nowszych).

Wymagania wstępne

Przykładowa aplikacja jest napisana w programie .NET Core 3.1,chociaż zasady mają zastosowanie zarówno do aplikacji .NET Framework, jak i .NET Core. Jako środowiska IDE można Visual Studio, Visual Studio dla komputerów Maclub Visual Studio Code środowiska IDE.

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem Utwórz bezpłatne konto .

Przykładowa aplikacja

Przykładową aplikację dla tego samouczka można sklonować lub pobrać z repozytorium https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-dotnet . Przykładowe repozytorium zawiera zarówno aplikację startową, jak i ukończoną.

git clone https://github.com/Azure-Samples/msdocs-azure-data-tables-sdk-dotnet

Przykładowa aplikacja używa danych pogodowych jako przykładu, aby zademonstrować możliwości interfejs API tabel. Obiekty reprezentujące obserwacje pogody są przechowywane i pobierane przy użyciu interfejs API tabel, w tym obiekty z dodatkowymi właściwościami w celu zademonstrowania możliwości interfejs API tabel.

Zrzut ekranu ukończonej aplikacji przedstawiający dane przechowywane w Cosmos DB przy użyciu interfejs API tabel.

1 — Tworzenie konta usługi Azure Cosmos DB

Najpierw należy utworzyć konto interfejsu API Cosmos DB, które będzie zawierać tabele używane w aplikacji. Można to zrobić przy użyciu interfejsu Azure Portal, interfejsu wiersza polecenia platformy Azure lub Azure PowerShell.

Zaloguj się do Azure Portal i wykonaj następujące kroki, aby utworzyć konto Cosmos DB.

Instrukcje Zrzut ekranu
W witrynie Azure Portal:
  1. Na pasku wyszukiwania w górnej części Azure Portal wprowadź "cosmos db".
  2. W menu wyświetlanym poniżej paska wyszukiwania w obszarze Usługi wybierz element z etykietą Azure Cosmos DB.
Zrzut ekranu przedstawiający sposób użycia pola wyszukiwania na górnym pasku narzędzi w celu znalezienia Cosmos DB na platformie Azure.
Na stronie Azure Cosmos DB wybierz pozycję +Utwórz. Zrzut ekranu przedstawiający lokalizację przycisku Utwórz na stronie Cosmos DB na platformie Azure.
Na stronie opcji Wybierz interfejs API wybierz opcję Tabela platformy Azure. Zrzut ekranu przedstawiający opcję Tabela platformy Azure jako poprawną opcję do wybrania.
Na stronie Tworzenie konta usługi Azure Cosmos DB — Tabela platformy Azure wypełnij formularz w następujący sposób.
  1. Utwórz nową grupę zasobów dla konta magazynu o nazwie rg-msdocs-tables-sdk-demo , wybierając link Utwórz nową w obszarze Grupa zasobów.
  2. Nadaj kontu magazynu nazwę, w cosmos-msdocs-tables-sdk-demo-XYZ której XYZ to dowolne trzy losowe znaki, aby utworzyć unikatową nazwę konta. Nazwy kont usługi Azure Cosmos DB muszą mieć długość od 3 do 44 znaków i mogą zawierać tylko małe litery, cyfry lub znaki łącznika (-).
  3. Wybierz region dla swojego konta magazynu.
  4. Wybierz pozycję Standardowa wydajność.
  5. W tym przykładzie wybierz pozycję Aprowizowana przepływność w obszarze Tryb pojemności.
  6. W tym przykładzie wybierz pozycję Zastosuj w obszarze Zastosuj rabat na warstwę Bezpłatna.
  7. Wybierz przycisk Przejrzyj i utwórz w dolnej części ekranu, a następnie wybierz pozycję "Utwórz" na ekranie podsumowania, aby utworzyć konto usługi Azure Cosmos DB. Ten proces może potrwać kilka minut.
Zrzut ekranu przedstawiający sposób wypełniania pól na stronie tworzenia Cosmos DB.

2 — Tworzenie tabeli

Następnie należy utworzyć tabelę w ramach konta Cosmos DB, aby można było używać aplikacji. W przeciwieństwie do tradycyjnej bazy danych wystarczy określić tylko nazwę tabeli, a nie właściwości (kolumny) w tabeli. Po załadowaniu danych do tabeli właściwości (kolumny) zostaną automatycznie utworzone zgodnie z potrzebami.

W Azure Portalwykonaj następujące kroki, aby utworzyć tabelę wewnątrz konta Cosmos DB.

Instrukcje Zrzut ekranu
W witrynie Azure Portal przejdź do strony przeglądu konta usługi Azure Cosmos DB. Możesz przejść do strony przeglądu konta usługi Cosmos DB, wpisując nazwę (cosmos-msdocs-tables-sdk-demo-XYZ) konta usługi Cosmos DB na górnym pasku wyszukiwania i patrząc pod nagłówkiem resources.Wybierz nazwę konta usługi Azure Cosmos DB, aby przejść do strony przeglądu. Zrzut ekranu przedstawiający sposób użycia pola wyszukiwania na górnym pasku narzędzi w celu znalezienia konta Cosmos DB.
Na stronie przeglądu wybierz pozycję +Dodaj tabelę. Okno dialogowe Nowa tabela będzie wysuwają się z prawej strony. Zrzut ekranu przedstawiający lokalizację przycisku Dodaj tabelę.
W oknie dialogowym Nowa tabela wypełnij formularz w następujący sposób.
  1. Wprowadź nazwę WeatherData dla identyfikatora tabeli. Jest to nazwa tabeli.
  2. W tym przykładzie wybierz pozycję Ręcznie w obszarze Przepływność tabeli (skalowanie automatyczne).
  3. Użyj wartości domyślnej 400 w ramach szacowanej wartości RU/s.
  4. Wybierz przycisk OK, aby utworzyć tabelę.
Zrzut ekranu przedstawiający okno dialogowe Nowa tabela dla tabeli Cosmos DB.

3 — Uzyskiwanie parametrów Cosmos DB

Aby uzyskać dostęp do tabel w Cosmos DB, aplikacja będzie potrzebować parametrów połączenia tabeli dla konta Storage CosmosDB. Te ciągi połączenia można pobrać przy użyciu interfejsu Azure Portal, interfejsu wiersza polecenia platformy Azure lub Azure PowerShell.

Instrukcje Zrzut ekranu
Po lewej stronie strony konta usługi Azure Cosmos DB znajdź element menu o nazwie Connection String (Ustawienia) i wybierz go. Zostanie pobrana strona, na której można pobrać parametrów połączenia dla konta magazynu. Zrzut ekranu przedstawiający lokalizację linku parametry połączenia na stronie Cosmos DB.
Skopiuj wartość PODSTAWOWE CIĄGI POŁĄCZENIA do użycia w aplikacji. Zrzut ekranu przedstawiający ciąg połączenia do wybrania i użycia w aplikacji.

Ciąg połączenia dla konta Cosmos DB jest traktowany jako klucz tajny aplikacji i musi być chroniony tak jak każdy inny klucz tajny aplikacji lub hasło. W tym przykładzie użyto narzędzia Secret Manager do przechowywania parametrów połączenia podczas opracowywania i ich udostępnić aplikacji. Dostęp do narzędzia Secret Manager można uzyskać z Visual Studio interfejsu wiersza polecenia .NET.

Aby otworzyć narzędzie Secret Manager z Visual Studio, kliknij prawym przyciskiem myszy projekt i wybierz pozycję Zarządzaj wpisami tajnymi użytkowników z menu kontekstowego. Spowoduje to otwarcie pliku secrets.json dla projektu. Zastąp zawartość pliku poniższym ciągiem JSON, zastępując ciągi połączenia tabeli Cosmos DB.

{
  "ConnectionStrings": {
    "CosmosTableApi": "<cosmos db table connection string>"
  }  
}

4 — Instalowanie pakietu NuGet Azure.Data.Tables

Aby uzyskać dostęp Cosmos DB interfejs API tabel z aplikacji .NET, zainstaluj pakiet NuGet Azure.Data.Tables.

Install-Package Azure.Data.Tables

5 — Konfigurowanie klienta tabeli w startup.cs

Zestaw Azure SDK komunikuje się z platformą Azure przy użyciu obiektów klienta w celu wykonywania różnych operacji na platformie Azure. Obiekt TableClient jest obiektem używanym do komunikowania się z Cosmos DB interfejs API tabel.

Aplikacja zazwyczaj tworzy jeden obiekt TableClient na tabelę, który będzie używany w całej aplikacji. W tym celu zaleca się użycie wstrzykiwania zależności (DI) i zarejestrowanie obiektu TableClient jako pojedynczego. Aby uzyskać więcej informacji na temat używania wstrzykiwania zależności z zestawem Azure SDK, zobacz Wstrzykiwanie zależności za pomocą zestawu Azure SDK dla platformy .NET.

W pliku aplikacji edytuj metodę ConfigureServices(), aby dopasować Startup.cs następujący fragment kodu:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages()
        .AddMvcOptions(options =>
        {
            options.Filters.Add(new ValidationFilter());
        });
    
    var connectionString = Configuration.GetConnectionString("CosmosTableApi");
    services.AddSingleton<TableClient>(new TableClient(connectionString, "WeatherData"));
    
    services.AddSingleton<TablesService>();
}

Musisz również dodać następującą instrukcje using w górnej części pliku Startup.cs.

using Azure.Data.Tables;

6 — Implementowanie Cosmos tabel bazy danych

Wszystkie Cosmos tabeli bazy danych dla przykładowej aplikacji są implementowane w TableService klasie znajdującej się w katalogu Services. Należy zaimportować przestrzenie nazw i w górnej części tego pliku, aby pracować z Azure Azure.Data.Tables obiektami w pakiecie Azure.Data.Tables SDK.

using Azure;
using Azure.Data.Tables;

Na początku klasy dodaj zmienną członkowski dla obiektu TableClient i konstruktora, aby umożliwić wstrzyknięcie obiektu TableService TableClient do klasy .

private TableClient _tableClient;

public TablesService(TableClient tableClient)
{
    _tableClient = tableClient;
}

Uzyskiwanie wierszy z tabeli

Klasa TableClient zawiera metodę o nazwie Query, która umożliwia wybranie wierszy z tabeli. W tym przykładzie, ponieważ żadne parametry nie są przekazywane do metody , wszystkie wiersze zostaną wybrane z tabeli.

Metoda przyjmuje również parametr ogólny typu ITableEntity, który określa, że dane klasy modelu będą zwracane jako. W tym przypadku używana jest wbudowana klasa TableEntity, co oznacza, że metoda zwróci kolekcję Query Pageable<TableEntity> jako wyniki.

public IEnumerable<WeatherDataModel> GetAllRows()
{
    Pageable<TableEntity> entities = _tableClient.Query<TableEntity>();

    return entities.Select(e => MapTableEntityToWeatherDataModel(e));
}

Klasa TableEntity zdefiniowana w pakiecie ma właściwości klucza partycji i wartości klucza Azure.Data.Tables wiersza w tabeli. Razem te dwie wartości dla unikatowego klucza dla wiersza w tabeli. W tej przykładowej aplikacji nazwa stacji pogodowej (miasta) jest przechowywana w kluczu partycji, a data/godzina obserwacji jest przechowywana w kluczu wiersza. Wszystkie inne właściwości (temperatura, wilgotność, prędkość wiatru) są przechowywane w słowniku obiektu TableEntity .

Częstą praktyką jest mapowanie obiektu TableEntity na obiekt własnej definicji. W tym celu przykładowa aplikacja definiuje WeatherDataModel klasę w katalogu Models. Ta klasa ma właściwości nazwy stacji i daty obserwacji, na które będą mapować klucz partycji i klucz wiersza, zapewniając bardziej znaczące nazwy właściwości dla tych wartości. Następnie używa słownika do przechowywania wszystkich innych właściwości obiektu . Jest to powszechny wzorzec podczas pracy z usługą Table Storage, ponieważ wiersz może mieć dowolną liczbę dowolnych właściwości i chcemy, aby obiekty modelu mogły przechwycić wszystkie z nich. Ta klasa zawiera również metody do listy właściwości klasy.

public class WeatherDataModel 
{
    // Captures all of the weather data properties -- temp, humidity, wind speed, etc
    private Dictionary<string, object> _properties = new Dictionary<string, object>();

    public string StationName { get; set; }

    public string ObservationDate { get; set; }

    public DateTimeOffset? Timestamp { get; set; }

    public string Etag { get; set; }

    public object this[string name] 
    { 
        get => ( ContainsProperty(name)) ? _properties[name] : null; 
        set => _properties[name] = value; 
    }
    
    public ICollection<string> PropertyNames => _properties.Keys;

    public int PropertyCount => _properties.Count;

    public bool ContainsProperty(string name) => _properties.ContainsKey(name);       
}

Metoda MapTableEntityToWeatherDataModel służy do mapowania obiektu TableEntity na WeatherDataModel obiekt . Obiekt TableEntity zawiera właściwość Keys, która pozwala pobrać wszystkie nazwy właściwości zawarte w tabeli dla obiektu (w praktyce nazwy kolumn dla tego wiersza w tabeli). Metoda bezpośrednio mapuje właściwości , , i , a następnie używa właściwości do iterowania po innych właściwościach w obiekcie i mapowania tych właściwości na obiekt bez właściwości, które zostały już bezpośrednio MapTableEntityToWeatherDataModel PartitionKey RowKey Timestamp Etag Keys TableEntity WeatherDataModel zamapowane.

Edytuj kod w metodzie MapTableEntityToWeatherDataModel , aby dopasować go do poniższego bloku kodu.

public WeatherDataModel MapTableEntityToWeatherDataModel(TableEntity entity)
{
    WeatherDataModel observation = new WeatherDataModel();
    observation.StationName = entity.PartitionKey;
    observation.ObservationDate = entity.RowKey;
    observation.Timestamp = entity.Timestamp;
    observation.Etag = entity.ETag.ToString();

    var measurements = entity.Keys.Where(key => !EXCLUDE_TABLE_ENTITY_KEYS.Contains(key));
    foreach (var key in measurements)
    {
        observation[key] = entity[key];
    }
    return observation;            
}

Filtrowanie wierszy zwracanych z tabeli

Aby filtrować wiersze zwracane z tabeli, możesz przekazać ciąg filtru stylu OData do metody Query. Jeśli na przykład chcesz uzyskać wszystkie odczyty pogodowe dla Chicago między północą 1 lipca 2021 r. a północą 2 lipca 2021 r. (włącznie), należy przekazać następujący ciąg filtru.

PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'

Wszystkie operatory filtru OData można wyświetlić w witrynie internetowej OData w sekcji Filtruj opcję zapytania systemowego.

W przykładowej aplikacji obiekt FilterResultsInputModel jest przeznaczony do przechwytywania wszelkich kryteriów filtrowania dostarczonych przez użytkownika.

public class FilterResultsInputModel : IValidatableObject
{
    public string PartitionKey { get; set; }
    public string RowKeyDateStart { get; set; }
    public string RowKeyTimeStart { get; set; }
    public string RowKeyDateEnd { get; set; }
    public string RowKeyTimeEnd { get; set; }
    [Range(-100, +200)]
    public double? MinTemperature { get; set; }
    [Range(-100,200)]
    public double? MaxTemperature { get; set; }
    [Range(0, 300)]
    public double? MinPrecipitation { get; set; }
    [Range(0,300)]
    public double? MaxPrecipitation { get; set; }
}

Gdy ten obiekt jest przekazywany do metody w klasie , tworzy ciąg filtru dla każdej wartości właściwości GetFilteredRows o wartości innych niż TableService null. Następnie tworzy połączony ciąg filtru, łącząc wszystkie wartości razem z klauzulą "and". Ten połączony ciąg filtru jest przekazywany do metody Query w obiekcie TableClient i będą zwracane tylko wiersze pasujące do ciągu filtru. Możesz użyć podobnej metody w kodzie, aby utworzyć odpowiednie ciągi filtru zgodnie z wymaganiami aplikacji.

public IEnumerable<WeatherDataModel> GetFilteredRows(FilterResultsInputModel inputModel)
{
    List<string> filters = new List<string>();

    if (!String.IsNullOrEmpty(inputModel.PartitionKey))
        filters.Add($"PartitionKey eq '{inputModel.PartitionKey}'");
    if (!String.IsNullOrEmpty(inputModel.RowKeyDateStart) && !String.IsNullOrEmpty(inputModel.RowKeyTimeStart))
        filters.Add($"RowKey ge '{inputModel.RowKeyDateStart} {inputModel.RowKeyTimeStart}'");
    if (!String.IsNullOrEmpty(inputModel.RowKeyDateEnd) && !String.IsNullOrEmpty(inputModel.RowKeyTimeEnd))
        filters.Add($"RowKey le '{inputModel.RowKeyDateEnd} {inputModel.RowKeyTimeEnd}'");
    if (inputModel.MinTemperature.HasValue)
        filters.Add($"Temperature ge {inputModel.MinTemperature.Value}");
    if (inputModel.MaxTemperature.HasValue)
        filters.Add($"Temperature le {inputModel.MaxTemperature.Value}");
    if (inputModel.MinPrecipitation.HasValue)
        filters.Add($"Precipitation ge {inputModel.MinTemperature.Value}");
    if (inputModel.MaxPrecipitation.HasValue)
        filters.Add($"Precipitation le {inputModel.MaxTemperature.Value}");

    string filter = String.Join(" and ", filters);
    Pageable<TableEntity> entities = _tableClient.Query<TableEntity>(filter);

    return entities.Select(e => MapTableEntityToWeatherDataModel(e));
}

Wstawianie danych przy użyciu obiektu TableEntity

Najprostszym sposobem dodawania danych do tabeli jest użycie obiektu TableEntity. W tym przykładzie dane są mapowane z obiektu modelu wejściowego na obiekt TableEntity. Właściwości obiektu wejściowego reprezentujące nazwę stacji pogody i datę/czas obserwacji są mapowane odpowiednio na właściwości PartitionKey i RowKey, które razem tworzą unikatowy klucz dla wiersza w tabeli. Następnie dodatkowe właściwości obiektu modelu wejściowego są mapowane na właściwości słownika obiektu TableEntity. Na koniec metoda AddEntity obiektu TableClient służy do wstawiania danych do tabeli.

InsertTableEntityZmodyfikuj klasę w przykładowej aplikacji, aby zawierała następujący kod.

public void InsertTableEntity(WeatherInputModel model)
{
    TableEntity entity = new TableEntity();
    entity.PartitionKey = model.StationName;
    entity.RowKey = $"{model.ObservationDate} {model.ObservationTime}";

    // The other values are added like a items to a dictionary
    entity["Temperature"] = model.Temperature;
    entity["Humidity"] = model.Humidity;
    entity["Barometer"] = model.Barometer;
    entity["WindDirection"] = model.WindDirection;
    entity["WindSpeed"] = model.WindSpeed;
    entity["Precipitation"] = model.Precipitation;

    _tableClient.AddEntity(entity);
}

Upsert data using a TableEntity object (Przetwarzanie upsert danych przy użyciu obiektu TableEntity)

Jeśli spróbujesz wstawić wiersz do tabeli z kombinacją klucza partycji/klucza wiersza, która już istnieje w tej tabeli, zostanie wyświetlony błąd. Z tego powodu często lepiej jest użyć metody UpsertEntity zamiast metody AddEntity podczas dodawania wierszy do tabeli. Jeśli w tabeli istnieje już kombinacja klucza partycji/klucza wiersza, metoda UpsertEntity zaktualizuje istniejący wiersz. W przeciwnym razie wiersz zostanie dodany do tabeli.

public void UpsertTableEntity(WeatherInputModel model)
{
    TableEntity entity = new TableEntity();
    entity.PartitionKey = model.StationName;
    entity.RowKey = $"{model.ObservationDate} {model.ObservationTime}";

    // The other values are added like a items to a dictionary
    entity["Temperature"] = model.Temperature;
    entity["Humidity"] = model.Humidity;
    entity["Barometer"] = model.Barometer;
    entity["WindDirection"] = model.WindDirection;
    entity["WindSpeed"] = model.WindSpeed;
    entity["Precipitation"] = model.Precipitation;

    _tableClient.UpsertEntity(entity);
}

Wstawianie lub upsert danych za pomocą właściwości zmiennej

Jedną z zalet korzystania z bazy danych Cosmos DB interfejs API tabel jest to, że jeśli obiekt ładowany do tabeli zawiera jakiekolwiek nowe właściwości, te właściwości są automatycznie dodawane do tabeli i wartości przechowywanych w Cosmos DB. Nie ma potrzeby uruchamiania instrukcji języka DDL, takich jak ALTER TABLE, aby dodać kolumny tak jak w tradycyjnej bazie danych.

Ten model zapewnia twojej aplikacji elastyczność podczas pracy ze źródłami danych, które mogą dodawać lub modyfikować dane, które mają być przechwytywane w czasie lub gdy różne dane wejściowe dostarczają różne dane do aplikacji. W przykładowej aplikacji możemy zasymulować stację pogodową, która wysyła nie tylko podstawowe dane pogodowe, ale także pewne dodatkowe wartości. Gdy obiekt z tymi nowymi właściwościami jest przechowywany w tabeli po raz pierwszy, odpowiednie właściwości (kolumny) zostaną automatycznie dodane do tabeli.

W przykładowej aplikacji klasa jest zbudowana na podstawie słownika wewnętrznego w celu obsługi dowolnego ExpandableWeatherObject zestawu właściwości obiektu. Ta klasa reprezentuje typowy wzorzec, gdy obiekt musi zawierać dowolny zestaw właściwości.

public class ExpandableWeatherObject
{
    public Dictionary<string, object> _properties = new Dictionary<string, object>();

    public string StationName { get; set; }

    public string ObservationDate { get; set; }

    public object this[string name]
    {
        get => (ContainsProperty(name)) ? _properties[name] : null;
        set => _properties[name] = value;
    }

    public ICollection<string> PropertyNames => _properties.Keys;

    public int PropertyCount => _properties.Count;

    public bool ContainsProperty(string name) => _properties.ContainsKey(name);
}

Aby wstawić lub upsert takiego obiektu przy użyciu obiektu interfejs API tabel, zamapuj właściwości obiektu rozszerzanego na obiekt TableEntity i użyj metod AddEntity lub UpsertEntity w obiekcie TableClient zgodnie z potrzebami.

public void InsertExpandableData(ExpandableWeatherObject weatherObject)
{
    TableEntity entity = new TableEntity();
    entity.PartitionKey = weatherObject.StationName;
    entity.RowKey = weatherObject.ObservationDate;

    foreach (string propertyName in weatherObject.PropertyNames)
    {
        var value = weatherObject[propertyName];
        entity[propertyName] = value;
    }
    _tableClient.AddEntity(entity);
}

        
public void UpsertExpandableData(ExpandableWeatherObject weatherObject)
{
    TableEntity entity = new TableEntity();
    entity.PartitionKey = weatherObject.StationName;
    entity.RowKey = weatherObject.ObservationDate;

    foreach (string propertyName in weatherObject.PropertyNames)
    {
        var value = weatherObject[propertyName];
        entity[propertyName] = value;
    }
    _tableClient.UpsertEntity(entity);
}

Aktualizowanie jednostki

Jednostki można zaktualizować, wywołując metodę UpdateEntity w obiekcie TableClient. Ponieważ jednostka (wiersz) przechowywana przy użyciu obiektu interfejs API tabel może zawierać dowolny zestaw właściwości, często przydatne jest utworzenie obiektu aktualizacji na podstawie obiektu Dictionary podobnego do omówionego ExpandableWeatherObject wcześniej. W takim przypadku jedyną różnicą jest dodanie właściwości, która jest używana do kontroli Etag współbieżności podczas aktualizacji.

public class UpdateWeatherObject
{
    public Dictionary<string, object> _properties = new Dictionary<string, object>();

    public string StationName { get; set; }
    public string ObservationDate { get; set; }
    public string Etag { get; set; }

    public object this[string name]
    {
        get => (ContainsProperty(name)) ? _properties[name] : null;
        set => _properties[name] = value;
    }

    public ICollection<string> PropertyNames => _properties.Keys;

    public int PropertyCount => _properties.Count;

    public bool ContainsProperty(string name) => _properties.ContainsKey(name);
}

W przykładowej aplikacji ten obiekt jest przekazywany do UpdateEntity metody w TableService klasie . Ta metoda najpierw ładuje istniejącą jednostkę z interfejs API tabel przy użyciu metody GetEntity obiektu TableClient. Następnie aktualizuje ten obiekt jednostki i używa UpdateEntity metody zapisywania aktualizacji w bazie danych. Zwróć uwagę, jak metoda UpdateEntity przyjmuje bieżący tag Etag obiektu, aby zagwarantować, że obiekt nie uległ zmianie od czasu początkowego załadowania. Jeśli chcesz zaktualizować jednostkę niezależnie od tego, możesz przekazać wartość Etag.Any do UpdateEntity metody .

public void UpdateEntity(UpdateWeatherObject weatherObject)
{
    string partitionKey = weatherObject.StationName;
    string rowKey = weatherObject.ObservationDate;

    // Use the partition key and row key to get the entity
    TableEntity entity = _tableClient.GetEntity<TableEntity>(partitionKey, rowKey).Value;

    foreach (string propertyName in weatherObject.PropertyNames)
    {
        var value = weatherObject[propertyName];
        entity[propertyName] = value;
    }

    _tableClient.UpdateEntity(entity, new ETag(weatherObject.Etag));
}

Usuwanie jednostki

Aby usunąć jednostkę z tabeli, wywołaj metodę DeleteEntity w obiekcie TableClient z kluczem partycji i kluczem wiersza obiektu.

public void RemoveEntity(string partitionKey, string rowKey)
{
    _tableClient.DeleteEntity(partitionKey, rowKey);           
}

7 — Uruchamianie kodu

Uruchom przykładową aplikację, aby wchodzić w interakcje z Cosmos DB interfejs API tabel. Przy pierwszym uruchomieniu aplikacji nie będzie żadnych danych, ponieważ tabela jest pusta. Użyj dowolnego z przycisków w górnej części aplikacji, aby dodać dane do tabeli.

Zrzut ekranu aplikacji przedstawiający lokalizację przycisków używanych do wstawiania danych do Cosmos DB przy użyciu tabeli A P I.

Wybranie przycisku Wstaw przy użyciu jednostki tabeli powoduje otwarcie okna dialogowego umożliwiającego wstawienie lub wstawienie nowego wiersza przy użyciu TableEntity obiektu .

Zrzut ekranu aplikacji przedstawiający okno dialogowe używane do wstawiania danych przy użyciu obiektu TableEntity.

Wybranie przycisku Wstaw przy użyciu rozwijanych danych powoduje wstawienie okna dialogowego, które umożliwia wstawienie obiektu z właściwościami niestandardowymi, co pokazuje, jak baza danych Cosmos DB interfejs API tabel automatycznie dodaje właściwości (kolumny) do tabeli w razie potrzeby. Użyj przycisku Dodaj pole niestandardowe, aby dodać co najmniej jedną nową właściwości i zademonstrować tę możliwość.

Zrzut ekranu aplikacji przedstawiający okno dialogowe używane do wstawiania danych przy użyciu obiektu z polami niestandardowymi.

Użyj przycisku Wstaw przykładowe dane, aby załadować przykładowe dane do Cosmos DB.

Zrzut ekranu aplikacji przedstawiający lokalizację przycisku wstawiania przykładowych danych.

Wybierz element Filter Results (Filtruj wyniki) w górnym menu, który ma zostać przekierowany do strony Filter Results (Wyniki filtru). Na tej stronie wypełnij kryteria filtru, aby zademonstrować, jak można utworzyć klauzulę filtru i przejść do Cosmos DB interfejs API tabel.

Zrzut ekranu aplikacji przedstawiający stronę wyników filtrowania i wyróżniony element menu używany do przechodzenia do strony.

Czyszczenie zasobów

Po zakończeniu pracy z przykładową aplikacją należy usunąć wszystkie zasoby platformy Azure powiązane z tym artykułem z konta platformy Azure. Możesz to zrobić, usuwając grupę zasobów.

Grupę zasobów można usunąć przy użyciu Azure Portal, wykonując następujące czynności.

Instrukcje Zrzut ekranu
Aby przejść do grupy zasobów, na pasku wyszukiwania wpisz nazwę grupy zasobów. Następnie na karcie Grupy zasobów wybierz nazwę grupy zasobów. Zrzut ekranu przedstawiający sposób wyszukiwania grupy zasobów.
Wybierz pozycję Usuń grupę zasobów na pasku narzędzi w górnej części strony grupy zasobów. Zrzut ekranu przedstawiający lokalizację przycisku Usuń grupę zasobów.
Zostanie wyświetlone okno dialogowe z prawej strony ekranu z prośbą o potwierdzenie usunięcia grupy zasobów.
  1. Wpisz pełną nazwę grupy zasobów w polu tekstowym, aby potwierdzić usunięcie zgodnie z instrukcjami.
  2. Wybierz przycisk Usuń w dolnej części strony.
Zrzut ekranu przedstawiający okno dialogowe potwierdzenia usunięcia grupy zasobów.

Następne kroki

W tym przewodniku Szybki start wyjaśniono sposób tworzenia konta usługi Azure Cosmos DB, tworzenia tabeli za pomocą Eksploratora danych i uruchamiania aplikacji. Teraz można tworzyć zapytania do danych przy użyciu interfejsu API tabel.