Rychlý start: Vytvoření rozhraní API pro aplikaci Table pomocí sady Python SDK a Azure Cosmos DB
PLATÍ PRO:
Tabulka
V tomto rychlém startu se dozvíte, jak získat přístup k rozhraní API služby Azure Cosmos DB pro table z aplikace v Pythonu. Azure Cosmos DB for Table je úložiště dat bez schématu, které aplikacím umožňuje 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ž tyto principy platí pro všechny aplikace Pythonu 3.7 nebo novější. Jako integrované vývojové prostředí (IDE) můžete použít Visual Studio Code .
Pokud nemáte předplatné Azure, vytvořte si před zahájením bezplatného účtu .
Ukázková aplikace
Ukázkovou aplikaci pro tento kurz můžete naklonovat nebo stáhnout 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
V ukázkovém úložišti je zahrnutá složka 1-starter-app a 2-completed-app sample. V aplikaci 1-starter-app vám zbyly některé funkce, které vám zbývají k dokončení s řádky označenými jako "#TODO". Fragmenty kódu uvedené v tomto článku jsou navrhované doplňky pro dokončení 1-starter-app.
Dokončená ukázková aplikace používá data o počasí jako příklad 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 pro table bez schémat. Následující obrázek znázorňuje místní aplikaci spuštěnou v prohlížeči a 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 tabulek služby Azure Cosmos DB, který bude obsahovat tabulky použité ve vaší aplikaci. Vytvořte účet pomocí Azure Portal, Azure CLI nebo Azure PowerShell.
Přihlaste se k Azure Portal a pomocí těchto kroků 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 Vybrat možnost rozhraní API zvolte možnost Azure Table . | 
|
Na stránce Vytvoření účtu 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.
V Azure Portal proveďte následující kroky a vytvořte tabulku uvnitř účtu služby Azure Cosmos DB.
| Pokyny | Snímek obrazovky |
|---|---|
V 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 vysune z pravé strany stránky. | 
|
V dialogovém okně Nová tabulka vyplňte formulář následujícím způsobem.
|
|
3. Získání připojovacího řetězce služby Azure Cosmos DB
Pro přístup k tabulce ve službě Azure Cosmos DB potřebuje vaše aplikace připojovací řetězec tabulky pro účet služby Cosmos DB Storage. Připojovací řetězec je možné načíst pomocí Azure Portal, Azure CLI nebo Azure PowerShell.
| 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. Budete přesměrováni 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 (PRIMÁRNÍ PŘIPOJOVACÍ ŘETĚZEC ), kterou chcete použít ve své aplikaci. | 
|
4. Instalace sady Azure Data Tables SDK pro Python
Po vytvoření účtu služby Azure Cosmos DB je vaším 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 sady Data Tables SDK pro Python na GitHubu.
Nainstalujte klientskou knihovnu Azure Tables pro Python pomocí pip:
pip install azure-data-tables
Nezapomeňte také nainstalovat requirements.txt do složek 1-starter-app nebo 2-completed-app .
5– Konfigurace klienta tabulky v souboru .env
Zkopírujte připojovací řetězec účtu služby Azure Cosmos DB z Azure Portal a pomocí zkopírovaného připojovacího řetězce vytvořte objekt TableServiceClient. Přepněte do složky 1-starter-app nebo 2-completed-app . Bez ohledu na to, s jakou aplikací začínáte, musíte v .env souboru definovat proměnné prostředí.
# 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ů za účelem provádění různých operací v Azure. Objekt TableServiceClient je objekt, který se používá ke komunikaci se službou Azure Cosmos DB for Table. Aplikace bude mít obvykle jeden TableServiceClient celek a bude mít hodnotu TableClient pro každou tabulku.
Například následující kód vytvoří TableServiceClient objekt pomocí připojovacího řetězce 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í s tabulkami 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 importovat 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 proměnnou člena objektu TableClient , aby bylo možné TableClient objekt vložit 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šechny údaje o počasí v Chicagu 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 si můžete prohlédnout na webu azure-data-tables v části Zápis filtrů.
Když 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ří kombinovaný řetězec filtru spojením všech hodnot do klauzule "a". 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 můžete použít v kódu k vytvoření vhodných řetězců filtru podle požadavků 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žít TableEntity objekt. 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 , které společně tvoří jedinečný klíč pro řádek v tabulce. Další vlastnosti objektu vstupního modelu se pak mapují na vlastnosti slovníku objektu TableEntity. Nakonec metoda create_entity objektu TableClient slouží 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
Upsertování dat pomocí objektu TableEntity
Pokud se pokusíte vložit řádek do tabulky s kombinací klíče oddílu a klíče řádku, která už v této tabulce existuje, zobrazí se chyba. Z tohoto důvodu je při přidávání řádků do tabulky často vhodnější použít metodu upsert_entitycreate_entity místo metody . Pokud daná kombinace klíče oddílu a klíče řá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 for Table je to, že pokud objekt načítaný do tabulky obsahuje nové vlastnosti, pak se tyto vlastnosti 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, abyste mohli přidávat sloupce jako v tradiční databázi.
Tento model poskytuje vaší aplikaci flexibilitu při práci se zdroji dat, které můžou přidávat nebo upravovat data, která je potřeba zachytit v průběhu času, nebo když různé vstupy poskytují aplikaci různá data. V ukázkové aplikaci můžeme simulovat meteorologická stanice, která odesílá nejen základní data o počasí, ale také některé další 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 upsertovat takový objekt pomocí rozhraní API pro tabulku, namapujte vlastnosti rozbalitelného objektu na TableEntity objekt a použijte create_entity metody nebo upsert_entity u objektu TableClient podle potřeby.
V ukázkové aplikaci upsert_entity může funkce také implementovat funkci vkládání nebo upsertování dat s vlastnostmi proměnné.
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 u objektu TableClient .
V ukázkové aplikaci se tento objekt předá upsert_entity metodě ve TableClient třídě . Aktualizuje objekt entity a použije metodu upsert_entity uložení aktualizací 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 metodu delete_entity pro TableClient objekt s klíčem oddílu a klíčem řá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 ve složce 2-completed-app 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 upsertovat nový řádek pomocí objektu TableEntity .
Když vyberete tlačítko Vložit pomocí rozbalitelných dat, zobrazí se dialogové okno, které vám umožní vložit objekt s vlastními vlastnostmi, které demonstruje, jak Služba Azure Cosmos DB pro tabulku v případě potřeby automaticky přidává 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 ukázková data do tabulky Azure Cosmos DB.
Pro ukázkovou složku 1-starter-app budete muset alespoň dokončit kód funkce,
submit_transactionaby vložení ukázkových dat fungovalo.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 aplikaci spouštíte ze složky 1-starter-app nebo 2-completed-app , nastavteproject_root_pathna hodnotu (prázdné).
V horní nabídce vyberte položku Filtrovat výsledky a přejděte na stránku Filtrovat výsledky. Na této stránce vyplňte kritéria filtru, abyste si ukázali, jak lze sestavit klauzuli filtru a předat ji do služby Azure Cosmos DB for Table.
Vyčištění prostředků
Až ukázkovou aplikaci dokončíte, měli byste ze svého účtu Azure odebrat všechny prostředky Azure související s tímto článkem. Odstraněním skupiny prostředků můžete odebrat všechny prostředky.
Skupinu prostředků je možné odstranit pomocí Azure Portal následujícím způsobem.
| Pokyny | Snímek obrazovky |
|---|---|
| Do skupiny prostředků přejdete tak, že do panelu hledání zadáte název skupiny prostředků. Pak 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ů. | 
|
Napravo na obrazovce 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ď můžete data dotazovat pomocí rozhraní API pro tabulku.