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.
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.
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.
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_transaction
wstawiania 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.
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.