Szybki start: tworzenie interfejsu API dla aplikacji tabel przy użyciu zestawu PYTHON SDK i usługi Azure Cosmos DB
DOTYCZY: 
Stół
W tym przewodniku Szybki start pokazano, jak uzyskać dostęp do interfejsu API usługi Azure Cosmos DB dla tabeli z poziomu aplikacji języka Python. Usługa Azure Cosmos DB for Table to bez schematu magazyn danych umożliwiający 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 języka Python mogą uzyskiwać dostęp do usługi Azure Cosmos DB for Table przy użyciu zestawu SDK tabel danych platformy Azure dla języka Python .
Wymagania wstępne
Przykładowa aplikacja jest napisana w języku Python w wersji 3.7 lub nowszej, chociaż zasady dotyczą wszystkich aplikacji języka Python w wersji 3.7 lub nowszej. Możesz użyć programu Visual Studio Code jako środowiska IDE.
Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.
Aplikacja przykładowa
Przykładowa aplikacja dla tego samouczka może zostać sklonowana lub pobrana z repozytorium https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.
git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git
Przykładowy folder 1-starter-app i 2-completed-app są zawarte w przykładowym repozytorium. Aplikacja 1-starter-app ma pewne funkcje do ukończenia z wierszami oznaczonymi jako "#TODO". Fragmenty kodu pokazane w tym artykule to sugerowane dodatki do ukończenia aplikacji 1-starter-app.
Ukończona przykładowa aplikacja używa danych pogodowych jako przykładu, aby zademonstrować możliwości interfejsu API dla tabeli. Obiekty reprezentujące obserwacje pogody są przechowywane i pobierane przy użyciu interfejsu API dla tabeli, w tym przechowywania obiektów z dodatkowymi właściwościami w celu zademonstrowania możliwości bez schematu interfejsu API dla tabeli. Na poniższej ilustracji przedstawiono aplikację lokalną działającą w przeglądarce z wyświetlonymi danymi pogodowymi przechowywanymi w usłudze Azure Cosmos DB dla tabeli.
1 — Tworzenie konta usługi Azure Cosmos DB
Najpierw musisz utworzyć konto interfejsu API tabel usługi Azure Cosmos DB, które będzie zawierać tabele używane w aplikacji. Utwórz konto za pomocą witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell.
Zaloguj się do witryny Azure Portal i wykonaj następujące kroki, aby utworzyć konto usługi Azure Cosmos DB.
| Instrukcje | Zrzut ekranu |
|---|---|
W witrynie Azure Portal:
|
|
| Na stronie usługi Azure Cosmos DB wybierz pozycję +Utwórz. | 
|
| Na stronie Wybierz interfejs API wybierz opcję Tabela platformy Azure. | 
|
Na stronie Tworzenie konta usługi Azure Cosmos DB — Tabela platformy Azure wypełnij formularz w następujący sposób.
|
|
2 — Tworzenie tabeli
Następnie należy utworzyć tabelę na koncie usługi Azure Cosmos DB, aby aplikacja była używana. W przeciwieństwie do tradycyjnej bazy danych wystarczy określić nazwę tabeli, a nie właściwości (kolumny) w tabeli. Gdy dane są ładowane do tabeli, właściwości (kolumny) są tworzone automatycznie zgodnie z potrzebami.
W witrynie Azure Portal wykonaj następujące kroki, aby utworzyć tabelę na koncie usługi Azure Cosmos DB.
| Instrukcje | Zrzut ekranu |
|---|---|
W witrynie Azure Portal przejdź do strony przeglądu konta usługi Azure Cosmos DB.
|
|
| Na stronie Przegląd wybierz pozycję +Dodaj tabelę. Okno dialogowe Nowa tabela jest wysuwane z prawej strony. | 
|
W oknie dialogowym Nowa tabela wypełnij formularz w następujący sposób.
|
|
3 — Uzyskiwanie parametry połączenia usługi Azure Cosmos DB
Aby uzyskać dostęp do tabel w usłudze Azure Cosmos DB, aplikacja wymaga tabeli parametry połączenia dla konta usługi Cosmos DB Storage. Parametry połączenia można pobrać przy użyciu witryny Azure Portal, interfejsu wiersza polecenia platformy Azure lub programu Azure PowerShell.
| Instrukcje | Zrzut ekranu |
|---|---|
| Po lewej stronie strony konta usługi Azure Cosmos DB znajdź element menu o nazwie Parametry połączenia w nagłówku Ustawienia i wybierz go. Nastąpi przekierowanie do strony, na której można pobrać parametry połączenia dla konta usługi Azure Cosmos DB. | 
|
| Skopiuj wartość PODSTAWOWE PARAMETRY POŁĄCZENIA do użycia w aplikacji. | 
|
4 — Instalowanie zestawu SDK tabel danych platformy Azure dla języka Python
Po utworzeniu konta usługi Azure Cosmos DB następnym krokiem jest zainstalowanie zestawu SDK tabel danych platformy Microsoft Azure dla języka Python. Aby uzyskać szczegółowe informacje na temat instalowania zestawu SDK, zapoznaj się z plikiem README.md w repozytorium Tabele danych dla języka Python w witrynie GitHub.
Zainstaluj bibliotekę klienta tabel platformy Azure dla języka Python za pomocą narzędzia:
pip install azure-data-tables
Nie zapomnij również zainstalować requirements.txt w folderach 1-starter-app lub 2-completed-app .
5 — Konfigurowanie klienta tabeli w pliku env
Skopiuj konto usługi Azure Cosmos DB parametry połączenia z witryny Azure Portal i utwórz obiekt TableServiceClient przy użyciu skopiowanego parametry połączenia. Przejdź do folderu 1-starter-app lub 2-completed-app . Niezależnie od tego, z którą aplikacją zaczynasz, musisz zdefiniować zmienne środowiskowe w .env pliku.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Zestaw Azure SDK komunikuje się z platformą Azure przy użyciu obiektów klienta w celu wykonywania różnych operacji na platformie Azure. Obiekt TableServiceClient jest obiektem używanym do komunikowania się z usługą Azure Cosmos DB dla tabeli. Aplikacja zazwyczaj ma jeden TableServiceClient ogólny rozmiar i będzie mieć tabelę TableClient .
Na przykład poniższy kod tworzy TableServiceClient obiekt przy użyciu parametry połączenia ze zmiennej środowiskowej.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 — Implementowanie operacji tabel usługi Azure Cosmos DB
Wszystkie operacje tabeli usługi Azure Cosmos DB dla przykładowej aplikacji są implementowane w klasie znajdującej TableServiceHelper się w pliku pomocnika w katalogu aplikacji internetowej. Musisz zaimportować klasę TableServiceClient w górnej części tego pliku, aby pracować z obiektami w bibliotece klienta azure.data.tables dla języka Python.
from azure.data.tables import TableServiceClient
Na początku TableServiceHelper klasy utwórz konstruktor i dodaj zmienną składową dla TableClient obiektu, aby umożliwić TableClient wstrzyknięcie obiektu do klasy.
def __init__(self, table_name=None, conn_str=None):
self.table_name = table_name if table_name else os.getenv("table_name")
self.conn_str = conn_str if conn_str else os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
self.table_client = self.table_service.get_table_client(self.table_name)
Filtrowanie wierszy zwracanych z tabeli
Aby filtrować wiersze zwracane z tabeli, możesz przekazać ciąg filtru stylu OData do query_entities metody . Jeśli na przykład chcesz uzyskać wszystkie odczyty pogody dla Chicago między północą 1 lipca 2021 r. a północą 2 lipca 2021 r. (włącznie), przekaż 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'
Powiązane operatory filtrów OData można wyświetlić w witrynie internetowej azure-data-tables w sekcji Pisanie filtrów.
Gdy parametr request.args jest przekazywany do query_entity metody w TableServiceHelper klasie, tworzy ciąg filtru dla każdej wartości właściwości innej niż null. Następnie tworzy połączony ciąg filtru, łącząc wszystkie wartości wraz z klauzulą "and". Ten połączony ciąg filtru jest przekazywany do metody w TableClient obiekcie i zwracane są tylko wiersze pasujące do query_entities ciągu filtru. Możesz użyć podobnej metody w kodzie, aby utworzyć odpowiednie ciągi filtru zgodnie z wymaganiami aplikacji.
def query_entity(self, params):
filters = []
if params.get("partitionKey"):
filters.append("PartitionKey eq '{}'".format(params.get("partitionKey")))
if params.get("rowKeyDateStart") and params.get("rowKeyTimeStart"):
filters.append("RowKey ge '{} {}'".format(params.get("rowKeyDateStart"), params.get("rowKeyTimeStart")))
if params.get("rowKeyDateEnd") and params.get("rowKeyTimeEnd"):
filters.append("RowKey le '{} {}'".format(params.get("rowKeyDateEnd"), params.get("rowKeyTimeEnd")))
if params.get("minTemperature"):
filters.append("Temperature ge {}".format(params.get("minTemperature")))
if params.get("maxTemperature"):
filters.append("Temperature le {}".format(params.get("maxTemperature")))
if params.get("minPrecipitation"):
filters.append("Precipitation ge {}".format(params.get("minPrecipitation")))
if params.get("maxPrecipitation"):
filters.append("Precipitation le {}".format(params.get("maxPrecipitation")))
return list(self.table_client.query_entities(" and ".join(filters)))
Wstawianie danych przy użyciu obiektu TableEntity
Najprostszym sposobem dodawania danych do tabeli jest użycie TableEntity obiektu . W tym przykładzie dane są mapowane z obiektu modelu wejściowego TableEntity na obiekt. Właściwości obiektu wejściowego reprezentującego nazwę stacji pogodowej i datę/godzinę obserwacji są mapowane odpowiednio na PartitionKey właściwości 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 w obiekcie TableEntity. create_entity Na koniec metoda w TableClient obiekcie jest używana do wstawiania danych do tabeli.
Zmodyfikuj insert_entity funkcję w przykładowej aplikacji, aby zawierała następujący kod.
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
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 zaleca się użycie upsert_entity metody zamiast create_entity metody podczas dodawania wierszy do tabeli. Jeśli dana kombinacja klucza partycji/klucza wiersza już istnieje w tabeli, upsert_entity metoda aktualizuje istniejący wiersz. W przeciwnym razie wiersz zostanie dodany do tabeli.
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Wstawianie lub upsert danych z właściwościami zmiennych
Jedną z zalet korzystania z usługi Azure Cosmos DB dla tabeli 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 usłudze Azure Cosmos DB. Nie ma potrzeby uruchamiania instrukcji DDL, takich jak ALTER TABLE, aby dodać kolumny tak jak w tradycyjnej bazie danych.
Ten model zapewnia elastyczność aplikacji podczas pracy ze źródłami danych, które mogą dodawać lub modyfikować dane, które muszą 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ę pogody, która wysyła nie tylko podstawowe dane pogodowe, ale także kilka dodatkowych wartości. Gdy obiekt z tymi nowymi właściwościami jest przechowywany w tabeli po raz pierwszy, odpowiednie właściwości (kolumny) są automatycznie dodawane do tabeli.
Aby wstawić lub upsert taki obiekt przy użyciu interfejsu API dla tabeli, zamapuj właściwości obiektu rozszerzalnego na TableEntity obiekt i użyj create_entity metod lub upsert_entity w odpowiedni sposób.TableClient
W przykładowej aplikacji upsert_entity funkcja może również zaimplementować funkcję wstawiania lub upsert danych z właściwościami zmiennych
def insert_entity(self):
entity = self.deserialize()
return self.table_client.create_entity(entity)
def upsert_entity(self):
entity = self.deserialize()
return self.table_client.upsert_entity(entity)
@staticmethod
def deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = "{} {}".format(params.pop("ObservationDate"), params.pop("ObservationTime"))
return params
Aktualizowanie jednostki
Jednostki można zaktualizować, wywołując metodę update_entity TableClient w obiekcie .
W przykładowej aplikacji ten obiekt jest przekazywany do upsert_entity metody w TableClient klasie . Aktualizuje ten obiekt jednostki i używa upsert_entity metody zapisywania aktualizacji w bazie danych.
def update_entity(self):
entity = self.update_deserialize()
return self.table_client.update_entity(entity)
@staticmethod
def update_deserialize():
params = {key: request.form.get(key) for key in request.form.keys()}
params["PartitionKey"] = params.pop("StationName")
params["RowKey"] = params.pop("ObservationDate")
return params
Usuwanie jednostki
Aby usunąć jednostkę z tabeli, wywołaj delete_entity metodę w TableClient obiekcie przy użyciu klucza partycji i klucza wiersza obiektu.
def delete_entity(self):
partition_key = request.form.get("StationName")
row_key = request.form.get("ObservationDate")
return self.table_client.delete_entity(partition_key, row_key)
7 — Uruchamianie kodu
Uruchom przykładową aplikację, aby wchodzić w interakcje z usługą Azure Cosmos DB dla tabeli. Na przykład, począwszy od folderu 2-completed-app z zainstalowanymi wymaganiami, można użyć:
python3 run.py webapp
Aby uzyskać więcej informacji na temat uruchamiania przykładowej aplikacji, zobacz plik README.md w katalogu głównym przykładowego repozytorium.
Przy pierwszym uruchomieniu aplikacji nie będzie żadnych danych, ponieważ tabela jest pusta. Użyj dowolnych przycisków w górnej części aplikacji, aby dodać dane do tabeli.
Wybranie przycisku Wstaw przy użyciu jednostki tabeli powoduje otwarcie okna dialogowego umożliwiającego wstawianie lub upert nowego wiersza przy użyciu TableEntity obiektu.
Wybranie przycisku Wstaw przy użyciu danych rozwijanych powoduje wyświetlenie okna dialogowego, które umożliwia wstawienie obiektu z właściwościami niestandardowymi, pokazując, jak usługa Azure Cosmos DB dla tabeli 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ść.
Użyj przycisku Wstaw przykładowe dane, aby załadować przykładowe dane do tabeli usługi Azure Cosmos DB.
W przypadku folderu przykładowego aplikacji 1-starter-app należy wykonać co najmniej kod dla funkcji przykładowej
submit_transactionwstawiania danych do pracy.Przykładowe dane są ładowane z pliku sample_data.json . Zmienna
project_root_path.env informuje aplikację, gdzie można znaleźć ten plik. Jeśli na przykład uruchamiasz aplikację z folderu 1-starter-app lub 2-completed-app , ustaw wartośćproject_root_path"" (pusta).
Wybierz element Filtruj wyniki w górnym menu, który ma zostać przeniesiony do strony Wyniki filtru. Na tej stronie wypełnij kryteria filtrowania, aby pokazać, jak można skompilować i przekazać klauzulę filtru do usługi Azure Cosmos DB dla tabeli.
Czyszczenie zasobów
Po zakończeniu pracy z przykładową aplikacją należy usunąć wszystkie zasoby platformy Azure związane z tym artykułem z konta platformy Azure. Wszystkie zasoby można usunąć, usuwając grupę zasobów.
Grupę zasobów można usunąć przy użyciu witryny 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. | 
|
| Wybierz pozycję Usuń grupę zasobów na pasku narzędzi w górnej części strony grupy zasobów. | 
|
Po prawej stronie ekranu zostanie wyświetlone okno dialogowe z prośbą o potwierdzenie 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żesz wykonywać zapytania dotyczące danych przy użyciu interfejsu API dla tabeli.
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla