Rövid útmutató: API létrehozása Table-alkalmazáshoz a Python SDK és az Azure Cosmos DB használatával
A KÖVETKEZŐKRE VONATKOZIK:
Táblázat
Ez a rövid útmutató bemutatja, hogyan érheti el a Tablehez készült Azure Cosmos DB API-t egy Python-alkalmazásból. Az Azure Cosmos DB for Table egy séma nélküli adattár, amely lehetővé teszi, hogy az alkalmazások strukturált NoSQL-adatokat tároljanak a felhőben. Mivel az adatok séma nélküli kialakításban vannak tárolva, a rendszer automatikusan új tulajdonságokat (oszlopokat) ad hozzá a táblához, amikor egy új attribútummal rendelkező objektumot ad hozzá a táblához. A Python-alkalmazások az Azure Data Tables SDK for Python-csomag használatával férhetnek hozzá a Táblához készült Azure Cosmos DB-hez .
Előfeltételek
A mintaalkalmazás Python 3.7-ben vagy újabb verzióban van megírva, bár az alapelvek minden Python 3.7+-alkalmazásra érvényesek. A Visual Studio Code-ot IDE-ként is használhatja.
Ha nem rendelkezik Azure-előfizetéssel, a kezdés előtt hozzon létre egy ingyenes fiókot .
Mintaalkalmazás
Az oktatóanyaghoz tartozó mintaalkalmazás klónozható vagy letölthető az adattárból 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
A mintaadattárban egy 1-starter-app és 2-completed-app mintamappa található. Az 1-starter-app néhány funkcióval rendelkezik, amelyek "#TODO" jelöléssel ellátott sorokkal fejeződnek be. Az ebben a cikkben bemutatott kódrészletek az 1-starter-app befejezéséhez javasolt kiegészítések.
A kész mintaalkalmazás időjárási adatokat használ példaként a Table API képességeinek szemléltetésére. Az időjárás-megfigyeléseket képviselő objektumok tárolása és lekérése a Table API használatával történik, beleértve az objektumok további tulajdonságokkal való tárolását a Table API séma nélküli képességeinek szemléltetéséhez. Az alábbi képen egy böngészőben futó helyi alkalmazás látható, amely az Azure Cosmos DB for Tableben tárolt időjárási adatokat jeleníti meg.
1 – Azure Cosmos DB-fiók létrehozása
Először létre kell hoznia egy Azure Cosmos DB Tables API-fiókot, amely az alkalmazásban használt táblákat fogja tartalmazni. Hozzon létre egy fiókot a Azure Portal, az Azure CLI vagy az Azure PowerShell használatával.
Jelentkezzen be a Azure Portal, és kövesse az alábbi lépéseket egy Azure Cosmos DB-fiók létrehozásához.
| Utasítások | Képernyőfelvétel |
|---|---|
Az Azure Portalon:
|
|
| Az Azure Cosmos DB oldalon válassza a +Létrehozás lehetőséget. | 
|
| Az API kiválasztása lapon válassza az Azure Table lehetőséget. | 
|
Az Azure Cosmos DB-fiók létrehozása – Azure Table lapon töltse ki az űrlapot az alábbiak szerint.
|
|
2 – Tábla létrehozása
Ezután létre kell hoznia egy táblát az Azure Cosmos DB-fiókjában az alkalmazás használatához. A hagyományos adatbázisokkal ellentétben csak a tábla nevét kell megadnia, a táblában lévő tulajdonságokat (oszlopokat) nem. Az adatok táblázatba való betöltésekor a tulajdonságok (oszlopok) szükség szerint automatikusan létrejönnek.
Az Azure Portal végezze el az alábbi lépéseket egy tábla Létrehozásához az Azure Cosmos DB-fiókban.
| Utasítások | Képernyőfelvétel |
|---|---|
A Azure Portal lépjen az Azure Cosmos DB-fiók áttekintési oldalára.
|
|
| Az Áttekintés lapon válassza a +Táblázat hozzáadása lehetőséget. Az Új táblázat párbeszédpanel kicsúszik a lap jobb oldaláról. | 
|
Az Új táblázat párbeszédpanelen töltse ki az űrlapot az alábbiak szerint.
|
|
3 – Azure Cosmos DB-kapcsolati sztring lekérése
A táblák Azure Cosmos DB-ben való eléréséhez az alkalmazásnak szüksége van a Cosmos DB Storage-fiókhoz kapcsolati sztring táblára. A kapcsolati sztring az Azure Portal, az Azure CLI vagy az Azure PowerShell használatával kérhetők le.
| Utasítások | Képernyőfelvétel |
|---|---|
| Az Azure Cosmos DB-fiók oldalának bal oldalán keresse meg a Kapcsolati sztringek nevű menüelemet a Beállítások fejléc alatt, és válassza ki. A rendszer egy olyan oldalra kerül, ahol lekérheti az Azure Cosmos DB-fiók kapcsolati sztring. | 
|
| Másolja ki az ELSŐDLEGES KAPCSOLATI SZTRING értéket az alkalmazásban való használathoz. | 
|
4 – Az Azure Data Tables SDK for Python telepítése
Miután létrehozott egy Azure Cosmos DB-fiókot, a következő lépés a Pythonhoz készült Microsoft Azure Data Tables SDK telepítése. Az SDK telepítésével kapcsolatos részletekért tekintse meg a README.md fájlt a GitHubon található Data Tables SDK for Python-adattárban.
Telepítse a Pythonhoz készült Azure Tables ügyfélkódtárat a pip használatával:
pip install azure-data-tables
Ne felejtse el telepíteni a requirements.txt is az 1-starter-app vagy a 2-completed-app mappába.
5 – A Table-ügyfél konfigurálása .env fájlban
Másolja ki az Azure Cosmos DB-fiókját kapcsolati sztring a Azure Portal, és hozzon létre egy TableServiceClient objektumot a másolt kapcsolati sztring használatával. Váltson az 1-starter-app vagy a 2-completed-app mappára. Függetlenül attól, hogy melyik alkalmazással kezd, környezeti változókat kell definiálnia egy .env fájlban.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Az Azure SDK ügyfélobjektumok használatával kommunikál az Azure-ral különböző műveletek végrehajtásához az Azure-on. Az TableServiceClient objektum az Az Azure Cosmos DB for Table szolgáltatással való kommunikációhoz használt objektum. Az alkalmazások általában egyetlen TableServiceClient átfogóval rendelkeznek, és táblázatonként egy-egy TableClient alkalmazással rendelkeznek.
Az alábbi kód például létrehoz egy TableServiceClient objektumot a környezeti változó kapcsolati sztring használatával.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 – Azure Cosmos DB-táblaműveletek implementálása
A mintaalkalmazáshoz tartozó Összes Azure Cosmos DB-táblaművelet a TableServiceHelperwebalkalmazás könyvtárában található segédfájlban található osztályban van implementálva. Importálnia kell a TableServiceClient fájl tetején található osztályt, hogy a Pythonhoz készült azure.data.tables ügyfélkódtárban lévő objektumokkal működjön együtt.
from azure.data.tables import TableServiceClient
Az osztály elején TableServiceHelper hozzon létre egy konstruktort, és adjon hozzá egy tagváltozót az TableClient objektumhoz, hogy az TableClient objektumot be lehessen szúrni az osztályba.
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)
Táblázatból visszaadott sorok szűrése
A táblázatból visszaadott sorok szűréséhez átadhat egy OData-stílusú szűrősztringet a query_entities metódusnak. Ha például 2021. július 1. éjfél és 2021. július 2. éjfél között szeretné megkapni a Békéscsaba összes időjárási adatát (beleértve a 2021. július 2-án éjfélt), a következő szűrősztringet kell megadnia.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
A kapcsolódó OData-szűrőműveleteket az azure-data-tables webhelyen, a Szűrők írása szakaszban tekintheti meg.
Amikor a request.args paramétert átadja a query_entityTableServiceHelper osztály metódusának, minden nem null tulajdonságértékhez létrehoz egy szűrősztringet. Ezután létrehoz egy kombinált szűrősztringet úgy, hogy az összes értéket egy "és" záradékkal összekapcsolja. Ezt az egyesített szűrősztringet a rendszer átadja az query_entitiesTableClient objektum metódusának, és csak a szűrősztringnek megfelelő sorokat adja vissza. A kódban egy hasonló módszerrel megfelelő szűrősztringeket hozhat létre az alkalmazás által megkövetelt módon.
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)))
Adatok beszúrása TableEntity objektummal
Az adatok táblázathoz való hozzáadásának legegyszerűbb módja egy TableEntity objektum használata. Ebben a példában az adatok egy bemeneti modell objektumából egy TableEntity objektumba lesznek leképezve. Az időjárási állomás nevét és a megfigyelési dátumot/időt ábrázoló bemeneti objektum tulajdonságai a és RowKey a tulajdonságokra PartitionKey vannak leképezve, amelyek együttesen a tábla sorának egyedi kulcsát alkotják. Ezután a bemeneti modell objektumának extra tulajdonságai a TableEntity objektum szótártulajdonságainak lesznek megfeleltetve. Végül az create_entity objektum metódusával TableClient adatokat szúrhat be a táblába.
Módosítsa a insert_entity példaalkalmazás függvényét úgy, hogy az tartalmazza a következő kódot.
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
Adatok mentése TableEntity objektum használatával
Ha olyan táblába próbál beszúrni egy sort, amelyben már létezik partíciókulcs/sorkulcs kombináció, hibaüzenet jelenik meg. Ezért gyakran célszerű a metódus helyett create_entity használni a upsert_entity metódust, amikor sorokat ad hozzá egy táblához. Ha a megadott partíciókulcs/sorkulcs kombináció már létezik a táblában, a upsert_entity metódus frissíti a meglévő sort. Ellenkező esetben a sor hozzá lesz adva a táblához.
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
Adatok beszúrása vagy frissítése változó tulajdonságokkal
Az Azure Cosmos DB for Table használatának egyik előnye, hogy ha egy táblába betöltött objektum bármilyen új tulajdonságot tartalmaz, akkor a rendszer automatikusan hozzáadja ezeket a tulajdonságokat a táblához és az Azure Cosmos DB-ben tárolt értékekhez. Az oszlopok hozzáadásához nem szükséges DDL-utasításokat futtatni, például az ALTER TABLE-et, mint egy hagyományos adatbázisban.
Ez a modell rugalmasságot biztosít az alkalmazásnak az olyan adatforrások kezelésekor, amelyek hozzáadhatják vagy módosíthatják, hogy milyen adatokat kell rögzíteni az idő múlásával, vagy amikor a különböző bemenetek eltérő adatokat biztosítanak az alkalmazásnak. A mintaalkalmazásban olyan időjárási állomást szimulálhatunk, amely nem csak az alap időjárási adatokat, hanem néhány további értéket is küld. Ha az új tulajdonsággal rendelkező objektumot először tárolja a tábla, a rendszer automatikusan hozzáadja a megfelelő tulajdonságokat (oszlopokat) a táblához.
Ha egy ilyen objektumot a Table API-val szeretne beszúrni vagy bővíteni, képezheti le a bővíthető objektum tulajdonságait egy TableEntity objektumba, és szükség szerint használja az create_entity objektumon található TableClient vagy upsert_entity metódusokat.
A mintaalkalmazásban a upsert_entity függvény a változó tulajdonságokkal rendelkező adatok beszúrásának vagy frissítésének függvényét is implementálhatja
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
Entitás frissítése
Az entitások frissíthetők az objektum metódusának update_entityTableClient meghívásával.
A mintaalkalmazásban ezt az objektumot a osztály metódusa TableClient továbbítjaupsert_entity. Frissíti az entitásobjektumot, és a metódussal upsert_entity menti a frissítéseket az adatbázisba.
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
Entitás eltávolítása
Ha el szeretne távolítani egy entitást egy táblából, hívja meg az delete_entity objektum metódusát az TableClient objektum partíciókulcsával és sorkulcsával.
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 – A kód futtatása
Futtassa a mintaalkalmazást az Azure Cosmos DB for Table használatához. A 2-completed-app mappából kiindulva például a telepített követelményekkel a következőt használhatja:
python3 run.py webapp
A mintaalkalmazás futtatásával kapcsolatos további információkért tekintse meg a mintaadattár gyökerében található README.md fájlt.
Az alkalmazás első futtatásakor nem lesznek adatok, mert a tábla üres. Az alkalmazás tetején található gombok bármelyikével adatokat adhat hozzá a táblához.
A Beszúrás táblaentitás használatával gombra kattintva megnyílik egy párbeszédpanel, amellyel új sort szúrhat be vagy szúrhat be egy TableEntity objektummal.
Ha a Beszúrás bővíthető adatokkal gombot választja, megjelenik egy párbeszédpanel, amellyel egyéni tulajdonságokkal rendelkező objektumot szúrhat be. Ez azt mutatja be, hogy az Azure Cosmos DB for Table hogyan adja hozzá automatikusan a tulajdonságokat (oszlopokat) a táblához, ha szükséges. Az Egyéni mező hozzáadása gomb használatával adjon hozzá egy vagy több új tulajdonságot, és mutassa be ezt a képességet.
A Mintaadatok beszúrása gombbal betölthet néhány mintaadatot az Azure Cosmos DB-táblába.
Az 1-starter-app mintamappához legalább be kell fejeznie a függvény kódját ahhoz, hogy a
submit_transactionmintaadat-beszúrás működjön.A mintaadatok egy sample_data.json fájlból töltődnek be. Az .env változó
project_root_pathmegadja az alkalmazásnak, hogy hol keresse meg ezt a fájlt. Ha például az alkalmazást az 1-starter-app vagy a 2-completed-app mappából futtatja, állítsaproject_root_path"" (üres) értékre.
Válassza ki a felső menü Eredmények szűrése elemét, és lépjen az Eredmények szűrése lapra. Ezen a lapon töltse ki a szűrési feltételeket, hogy bemutassa, hogyan hozható létre és adható át a szűrő záradéka a tablehez készült Azure Cosmos DB-nek.
Az erőforrások eltávolítása
Ha végzett a mintaalkalmazással, távolítsa el a cikkhez kapcsolódó összes Azure-erőforrást az Azure-fiókjából. Az összes erőforrást eltávolíthatja az erőforráscsoport törlésével.
Az erőforráscsoport az Azure Portal használatával törölhető az alábbi módon.
| Utasítások | Képernyőfelvétel |
|---|---|
| Ha az erőforráscsoportra szeretne lépni, írja be az erőforráscsoport nevét a keresősávba. Ezután az Erőforráscsoportok lapon válassza ki az erőforráscsoport nevét. | 
|
| Válassza az Erőforráscsoport törlése lehetőséget az erőforráscsoport lap tetején található eszköztáron. | 
|
A képernyő jobb oldalán megjelenik egy párbeszédpanel, amely arra kéri, hogy erősítse meg az erőforráscsoport törlését.
|
|
Következő lépések
Ebben a rövid útmutatóban bemutattuk, hogyan lehet Azure Cosmos DB-fiókot létrehozni, hogyan lehet az Adatkezelő segítségével táblát készíteni, és hogyan lehet futtatni az alkalmazást. Most már lekérdezheti az adatokat a Table API-val.