Szybki start: tworzenie interfejsu API dla aplikacji tabel przy użyciu zestawu PYTHON SDK i usługi Azure Cosmos DB
DOTYCZY:
Tabeli
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, 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 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, ale zasady mają zastosowanie do wszystkich aplikacji języka Python 3.7 lub nowszych. Można użyć Visual Studio Code jako środowiska IDE.
Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto .
Przykładowa aplikacja
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 znajdują się 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 pogodowe 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 lokalną aplikację działającą w przeglądarce, wyświetlającą dane pogodowe przechowywane w usłudze Azure Cosmos DB for Table.
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 przy użyciu Azure Portal, interfejsu wiersza polecenia platformy Azure lub Azure PowerShell.
Zaloguj się do 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 mogła jej używać. 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ą automatycznie tworzone zgodnie z potrzebami.
W Azure Portal wykonaj następujące kroki, aby utworzyć tabelę na koncie usługi Azure Cosmos DB.
| Instrukcje | Zrzut ekranu |
|---|---|
W 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 wysunie się z prawej strony. | 
|
W oknie dialogowym Nowa tabela wypełnij formularz w następujący sposób.
|
|
3 — Pobieranie parametrów połączenia usługi Azure Cosmos DB
Aby uzyskać dostęp do tabel w usłudze Azure Cosmos DB, aplikacja potrzebuje parametrów połączenia tabeli dla konta usługi Cosmos DB Storage. Parametry połączenia można pobrać przy użyciu 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 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 usłudze GitHub.
Zainstaluj bibliotekę klienta tabel platformy Azure dla języka Python przy użyciu narzędzia pip:
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 parametry połączenia konta usługi Azure Cosmos DB z Azure Portal i utwórz obiekt TableServiceClient przy użyciu skopiowanych parametrów 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 for Table. Aplikacja zazwyczaj będzie mieć pojedynczą TableServiceClient ogólną wartość i będzie zawierać jedną tabelę TableClient .
Na przykład poniższy kod tworzy TableServiceClient obiekt przy użyciu parametrów 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 tabeli 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 . Należy 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 pogodowe 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'
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 z klauzulą "and". Ten połączony ciąg filtru jest przekazywany do query_entities metody w TableClient obiekcie i zwracane są 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.
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 obiektu TableClient służy 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
Dane upsert używające 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 for Table 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 przechowywane 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ę pogodową, 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 or upsert_entity w TableClient obiekcie odpowiednio.
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 w TableClient 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ę obiektu TableClient 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 korzystać z usługi Azure Cosmos DB for Table. 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 upsert nowego wiersza przy użyciu TableEntity obiektu.
Wybranie przycisku Wstaw przy użyciu danych rozwijanych powoduje wyświetlenie okna dialogowego umożliwiającego wstawianie obiektu z właściwościami niestandardowymi, co pokazuje, jak usługa Azure Cosmos DB for Table 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 1-starter-app należy wykonać co najmniej kod dla
submit_transactionfunkcji wstawiania przykładowych 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 filtrowania. Na tej stronie wypełnij kryteria filtrowania, aby pokazać, jak można skompilować i przekazać klauzulę filtru do usługi Azure Cosmos DB for Table.
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. Wszystkie zasoby można usunąć, 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. | 
|
| 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.