Rychlý start: Vytvoření aplikace API pro tabulky pomocí sady Python SDK a Azure Cosmos DB
PLATÍ PRO: 
Stůl
V tomto rychlém startu se dozvíte, jak získat přístup k rozhraní API služby Azure Cosmos DB pro tabulky z aplikace v Pythonu. Azure Cosmos DB for Table je úložiště dat bez schématu, které umožňuje aplikacím ukládat strukturovaná data NoSQL v cloudu. Vzhledem k tomu, že data jsou uložená v návrhu bez schématu, při přidání objektu s novým atributem do tabulky se do tabulky automaticky přidají nové vlastnosti (sloupce). Aplikace Pythonu mají přístup ke službě Azure Cosmos DB for Table pomocí balíčku Azure Data Tables SDK pro Python .
Požadavky
Ukázková aplikace je napsaná v Pythonu 3.7 nebo novějším, i když se principy vztahují na všechny aplikace Pythonu 3.7 nebo novější. Visual Studio Code můžete použít jako integrované vývojové prostředí (IDE).
Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet před tím, než začnete.
Ukázková aplikace
Ukázková aplikace pro tento kurz může být naklonována nebo stažena z úložiště 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
Ukázkové úložiště obsahuje 1-starter-app a 2-completed-app sample folder. 1-starter-app obsahuje některé funkce, které vám zbývá dokončit s řádky označenými jako "#TODO". Fragmenty kódu uvedené v tomto článku představují navrhované doplňky pro dokončení 1-starter-appu.
Dokončená ukázková aplikace používá jako příklad data o počasí k předvedení možností rozhraní API pro tabulku. Objekty představující pozorování počasí se ukládají a načítají pomocí rozhraní API pro tabulku, včetně ukládání objektů s dalšími vlastnostmi, které demonstrují možnosti rozhraní API for Table bez schématu. Následující obrázek ukazuje místní aplikaci spuštěnou v prohlížeči, která zobrazuje data o počasí uložená ve službě Azure Cosmos DB for Table.
1. Vytvoření účtu služby Azure Cosmos DB
Nejprve musíte vytvořit účet rozhraní API pro tabulky azure Cosmos DB, který bude obsahovat tabulky použité ve vaší aplikaci. Vytvořte účet pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu.
Přihlaste se k webu Azure Portal a následujícím postupem vytvořte účet služby Azure Cosmos DB.
| Pokyny | Snímek obrazovky |
|---|---|
Na webu Azure Portal:
|
|
| Na stránce Azure Cosmos DB vyberte +Vytvořit. | 
|
| Na stránce s možností Vybrat rozhraní API zvolte možnost Azure Table. | 
|
Na stránce Vytvořit účet služby Azure Cosmos DB – Tabulka Azure vyplňte formulář následujícím způsobem.
|
|
2. Vytvoření tabulky
Dále musíte vytvořit tabulku v rámci účtu služby Azure Cosmos DB, kterou bude vaše aplikace používat. Na rozdíl od tradiční databáze stačí zadat pouze název tabulky, nikoli vlastnosti (sloupce) v tabulce. Při načítání dat do tabulky se vlastnosti (sloupce) automaticky vytvoří podle potřeby.
Na webu Azure Portal proveďte následující kroky a vytvořte tabulku uvnitř účtu služby Azure Cosmos DB.
| Pokyny | Snímek obrazovky |
|---|---|
Na webu Azure Portal přejděte na stránku přehledu účtu služby Azure Cosmos DB.
|
|
| Na stránce Přehled vyberte +Přidat tabulku. Dialogové okno Nová tabulka se posune z pravé strany stránky. | 
|
V dialogovém okně Nová tabulka vyplňte formulář následujícím způsobem.
|
|
3. Získání služby Azure Cosmos DB připojovací řetězec
Pro přístup k tabulce ve službě Azure Cosmos DB potřebuje vaše aplikace tabulku připojovací řetězec pro účet úložiště Cosmos DB. Připojovací řetězec je možné načíst pomocí webu Azure Portal, Azure CLI nebo Azure PowerShellu.
| Pokyny | Snímek obrazovky |
|---|---|
| Na levé straně stránky účtu služby Azure Cosmos DB vyhledejte položku nabídky s názvem Připojovací řetězce pod záhlavím Nastavení a vyberte ji. Přejdete na stránku, kde můžete načíst připojovací řetězec pro účet služby Azure Cosmos DB. | 
|
| Zkopírujte hodnotu PRIMARY CONNECTION STRING, která se má použít ve vaší aplikaci. | 
|
4. Instalace sady Azure Data Tables SDK pro Python
Po vytvoření účtu služby Azure Cosmos DB je dalším krokem instalace sady Microsoft Azure Data Tables SDK pro Python. Podrobnosti o instalaci sady SDK najdete v souboru README.md v úložišti Sdk pro tabulky dat pro Python na GitHubu.
Nainstalujte klientskou knihovnu Azure Tables pro Python pomocí pipu:
pip install azure-data-tables
Nezapomeňte také nainstalovat requirements.txt do 1-starter-app nebo 2-completed-app složek.
5. Konfigurace klienta tabulky v souboru .env
Zkopírujte účet služby Azure Cosmos DB připojovací řetězec z webu Azure Portal a vytvořte objekt TableServiceClient pomocí zkopírovaného připojovací řetězec. Přepněte do složky 1-starter-app nebo 2-completed-app . Bez ohledu na to, kterou aplikaci začínáte, je potřeba definovat proměnné prostředí v .env souboru.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Sada Azure SDK komunikuje s Azure pomocí klientských objektů ke spouštění různých operací v Azure. Objekt TableServiceClient je objekt používaný ke komunikaci se službou Azure Cosmos DB for Table. Aplikace má obvykle jeden TableServiceClient celek a bude mít každou TableClient tabulku.
Například následující kód vytvoří TableServiceClient objekt pomocí připojovací řetězec z proměnné prostředí.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6. Implementace operací tabulek Azure Cosmos DB
Všechny operace tabulek Azure Cosmos DB pro ukázkovou aplikaci se implementují ve TableServiceHelper třídě umístěné v pomocném souboru v adresáři webové aplikace . Abyste mohli pracovat s objekty v klientské knihovně azure.data.tables pro Python, budete muset naimportovat TableServiceClient třídu v horní části tohoto souboru.
from azure.data.tables import TableServiceClient
Na začátku TableServiceHelper třídy vytvořte konstruktor a přidejte členovou proměnnou objektu TableClient , aby TableClient byl objekt vložen do třídy.
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)
Filtrování řádků vrácených z tabulky
Pokud chcete filtrovat řádky vrácené z tabulky, můžete metodě query_entities předat řetězec filtru stylu OData. Pokud byste například chtěli získat všechna čtení počasí pro Chicago mezi půlnocí 1. července 2021 a půlnocí 2. července 2021 (včetně), předali byste následující řetězec filtru.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
Související operátory filtru OData můžete zobrazit na webu azure-data-tables v části Zápis filtrů.
Pokud je parametr request.args předán query_entity metodě ve TableServiceHelper třídě, vytvoří řetězec filtru pro každou hodnotu vlastnosti, která není null. Potom vytvoří sloučený filtrovací řetězec spojením všech hodnot společně s klauzulí "and". Tento kombinovaný řetězec filtru se předá query_entities metodě objektu TableClient a vrátí se pouze řádky odpovídající řetězci filtru. Podobnou metodu v kódu můžete použít k vytvoření vhodných řetězců filtru podle potřeby vaší aplikace.
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)))
Vložení dat pomocí objektu TableEntity
Nejjednodušší způsob, jak přidat data do tabulky, je použití objektu TableEntity . V tomto příkladu se data mapují ze vstupního objektu TableEntity modelu na objekt. Vlastnosti vstupního objektu představující název meteorologické stanice a datum a čas pozorování jsou mapovány na PartitionKey vlastnosti a RowKey vlastnosti, které společně tvoří jedinečný klíč pro řádek v tabulce. Pak se další vlastnosti vstupního objektu modelu mapují na vlastnosti slovníku u objektu TableEntity. Nakonec se create_entity metoda objektu TableClient používá k vložení dat do tabulky.
insert_entity Upravte funkci v ukázkové aplikaci tak, aby obsahovala následující kód.
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 data pomocí objektu TableEntity
Pokud se pokusíte vložit řádek do tabulky s kombinací klíče oddílu nebo řádku, která už v této tabulce existuje, zobrazí se chyba. Z tohoto důvodu je často vhodnější použít upsert_entity místo create_entity metody při přidávání řádků do tabulky. Pokud daná kombinace klíče oddílu nebo řádku již v tabulce existuje, upsert_entity metoda aktualizuje existující řádek. V opačném případě se řádek přidá do tabulky.
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
Vložení nebo upsertování dat s vlastnostmi proměnné
Jednou z výhod použití služby Azure Cosmos DB pro tabulku je, že pokud objekt načtený do tabulky obsahuje jakékoli nové vlastnosti, tyto vlastnosti se automaticky přidají do tabulky a hodnoty uložené ve službě Azure Cosmos DB. Není nutné spouštět příkazy DDL, jako je ALTER TABLE, a přidávat sloupce jako v tradiční databázi.
Tento model dává vaší aplikaci flexibilitu při práci se zdroji dat, které můžou přidávat nebo upravovat data, která je potřeba zachytávat v průběhu času nebo když různé vstupy poskytují různým datům vaší aplikaci. V ukázkové aplikaci můžeme simulovat meteorologická stanice, která odesílá nejen základní data o počasí, ale také některé dodatečné hodnoty. Když je objekt s těmito novými vlastnostmi poprvé uložen v tabulce, odpovídající vlastnosti (sloupce) se automaticky přidají do tabulky.
Chcete-li vložit nebo přenést takový objekt pomocí rozhraní API pro tabulku, namapujte vlastnosti rozbalitelného objektu TableEntity na objekt a podle potřeby použijte create_entity nebo upsert_entity metody objektu TableClient .
V ukázkové aplikaci upsert_entity může funkce také implementovat funkci vložení nebo upsert dat s proměnnými vlastnostmi.
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
Aktualizace entity
Entity lze aktualizovat voláním update_entity metody objektu TableClient .
V ukázkové aplikaci se tento objekt předá upsert_entity metodě ve TableClient třídě. Aktualizuje objekt entity a pomocí upsert_entity metody uloží aktualizace do databáze.
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
Odebrání entity
Pokud chcete odebrat entitu z tabulky, zavolejte delete_entity metodu TableClient objektu pomocí klíče oddílu a klíče řádku objektu.
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. Spuštění kódu
Spusťte ukázkovou aplikaci pro interakci se službou Azure Cosmos DB for Table. Například počínaje 2 dokončenou složkou aplikace s nainstalovanými požadavky můžete použít:
python3 run.py webapp
Další informace o spuštění ukázkové aplikace najdete v souboru README.md v kořenovém adresáři ukázkového úložiště.
Při prvním spuštění aplikace nebudou k dispozici žádná data, protože tabulka je prázdná. Pomocí libovolného tlačítka v horní části aplikace přidejte data do tabulky.
Výběrem tlačítka Vložit pomocí entity tabulky se otevře dialogové okno, ve kterém můžete vložit nebo vložit nový řádek pomocí objektu TableEntity .
Když vyberete tlačítko Vložit pomocí rozbalitelného data, zobrazí se dialogové okno, které umožňuje vložit objekt s vlastními vlastnostmi a ukazuje, jak Azure Cosmos DB pro tabulku v případě potřeby automaticky přidá do tabulky vlastnosti (sloupce). Pomocí tlačítka Přidat vlastní pole přidejte jednu nebo více nových vlastností a předveďte tuto funkci.
Pomocí tlačítka Vložit ukázková data načtěte do tabulky Azure Cosmos DB ukázková data.
Pro ukázkovou složku 1-starter-app budete muset alespoň dokončit kód funkce pro
submit_transactionvložení ukázkových dat.Ukázková data se načtou ze souboru sample_data.json . Proměnná
project_root_path.env říká aplikaci, kde má tento soubor najít. Pokud například spouštíte aplikaci ze složky 1-starter-app nebo 2-completed-app , nastavteproject_root_pathna "" (prázdné).
V horní nabídce vyberte položku Filtrovat výsledky, která se má přesunout na stránku Filtrovat výsledky. Na této stránce vyplňte kritéria filtru, abyste ukázali, jak lze vytvořit a předat klauzuli filtru do služby Azure Cosmos DB for Table.
Vyčištění prostředků
Až budete s ukázkovou aplikací hotovi, měli byste ze svého účtu Azure odebrat všechny prostředky Azure související s tímto článkem. Všechny prostředky můžete odebrat odstraněním skupiny prostředků.
Skupinu prostředků můžete odstranit pomocí webu Azure Portal následujícím způsobem.
| Pokyny | Snímek obrazovky |
|---|---|
| Pokud chcete přejít do skupiny prostředků, zadejte na panelu hledání název skupiny prostředků. Potom na kartě Skupiny prostředků vyberte název skupiny prostředků. | 
|
| Na panelu nástrojů v horní části stránky skupiny prostředků vyberte Odstranit skupinu prostředků. | 
|
V pravé části obrazovky se zobrazí dialogové okno s žádostí o potvrzení odstranění skupiny prostředků.
|
|
Další kroky
V tomto rychlém startu jste se seznámili s postupem vytvoření databázového účtu Azure Cosmos DB, vytvoření tabulky pomocí Průzkumníka dat a spuštění aplikace. Teď se můžete dotazovat na data pomocí rozhraní API pro tabulku.