Rövid útmutató: API létrehozása Table-alkalmazáshoz a Python SDK-val és az Azure Cosmos DB-vel
A KÖVETKEZŐKRE VONATKOZIK: 
Asztal
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 érhetik el az Azure Cosmos DB for Table szolgáltatást.
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 használhatja.
Ha nem rendelkezik Azure-előfizetéssel, első lépésként mindössze néhány perc alatt létrehozhat egy ingyenes fiókot.
Mintaalkalmazás
Az oktatóanyag mintaalkalmazása 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 kezdőalkalmazás és egy 2 kész alkalmazás mintamappa található. Az 1-starter-app néhány funkcióval rendelkezik, amelyek a "#TODO" jelöléssel ellátott vonalakkal fejeződnek be. 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 bemutatásához. 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 bemutatásához. 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 tartalmazza az alkalmazásban használt táblákat. Hozzon létre egy fiókot az Azure Portallal, az Azure CLI-vel vagy az Azure PowerShell-lel.
Jelentkezzen be az Azure Portalra , és kövesse az alábbi lépéseket egy Azure Cosmos DB-fiók létrehozásához.
| Utasítások | Képernyőkép |
|---|---|
Az Azure Portalon:
|
|
| Az Azure Cosmos DB lapon 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ókban az alkalmazás használatához. A hagyományos adatbázistól eltérően 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 Portalon hajtsa végre az alábbi lépéseket, hogy létrehozhasson egy táblát az Azure Cosmos DB-fiókban.
| Utasítások | Képernyőkép |
|---|---|
Az Azure Portalon 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
Az Azure Cosmos DB-ben lévő táblázat(ok) eléréséhez az alkalmazásnak szüksége van a Cosmos DB Storage-fiók tábla kapcsolati sztring. 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őkép |
|---|---|
| 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 jelölje 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ékét 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 GitHubon található Data Tables SDK for Python-adattár README.md fájlját.
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ákba.
5 – A Table-ügyfél konfigurálása .env fájlban
Másolja az Azure Cosmos DB-fiókját kapcsolati sztring az Azure Portalról, é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 kezdi, 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 TableServiceClient objektum az Azure Cosmos DB for Table szolgáltatással való kommunikációhoz használt objektum. Egy alkalmazás általában egyetlen TableServiceClient általános, táblánkénti egy-egy TableClient alkalmazással rendelkezik.
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ás összes Azure Cosmos DB-táblaművelete a TableServiceHelper webalkalmazá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 az azure.data.tables Python-ügyfélkódtár objektumaival való munkához.
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 OData-stílusszűrési sztringet adhat át 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é lekérni Chicago összes időjárási adatát (beleértve a 2021. július 2-án éjfélt), akkor 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őoperátorok az Azure-data-tables webhelyén, az Írási szűrők szakaszban tekinthetők meg.
Amikor a request.args paramétert átadja az 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. Ez az egyesített szűrősztring az objektum metódusának query_entitiesTableClient lesz átadva, és csak a szűrősztringnek megfelelő sorok lesznek visszaadva. 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ázatba való felvételének legegyszerűbb módja egy TableEntity objektum használata. Ebben a példában az adatok leképezve lesznek egy bemeneti modell objektumából egy TableEntity objektumba. Az időjárási állomás nevét és megfigyelési dátumát/idejét ábrázoló bemeneti objektum tulajdonságai a tulajdonságokra PartitionKeyRowKey vannak leképezve, amelyek együttesen a tábla sorának egyedi kulcsát alkotják. Ezután a bemeneti modell objektum további tulajdonságai a TableEntity objektum szótártulajdonságaihoz 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 függvényt insert_entity a példaalkalmazásban ú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 hozzáadása TableEntity-objektum használatával
Ha egy 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. Emiatt gyakran előnyösebb a upsert_entity módszer helyett create_entity a sorok táblázathoz való hozzáadásakor. 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 új tulajdonságokat 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. A hagyományos adatbázisokhoz hasonló oszlopok hozzáadásához nem szükséges DDL-utasításokat futtatni, például AZ ALTER TABLE-et.
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ás számára. 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 ilyen új tulajdonságokkal rendelkező objektumok első alkalommal vannak tárolva a táblában, a rendszer automatikusan hozzáadja a megfelelő tulajdonságokat (oszlopokat) a táblához.
Ha egy ilyen objektumot a Table API használatával szeretne beszúrni vagy továbbadni, képezheti le a bővíthető objektum tulajdonságait egy TableEntity objektumba, és szükség szerint használja az create_entityTableClient objektumon lévő metódusokat 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 adjuk át az upsert_entity osztály metódusának TableClient . Frissíti az entitásobjektumot, és a upsert_entity módszerrel 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_entityTableClient objektum metódusát az 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. Például a 2-completed-app mappától kezdve 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áblázatentitással gombra kattintva megnyílik egy párbeszédpanel, amellyel új sort szúrhat be vagy állíthat 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, amely bemutatja, 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 gombbal hozzáadhat egy vagy több új tulajdonságot, és bemutathatja 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
submit_transactionmintaadat-beszúrás működéséhez szükséges függvény kódját.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 találja 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ü Találatok 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 bemutassuk, hogyan hozható létre és adható át egy szűrőzáradék az Azure Cosmos DB for Tablenek.
Az erőforrások eltávolítása
Ha végzett a mintaalkalmazással, el kell távolítania 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áscsoportokat az alábbi lépésekkel törölheti az Azure Portalon .
| Utasítások | Képernyőkép |
|---|---|
| Az erőforráscsoportra való ugráshoz í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árról. | 
|
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 használatával.
Visszajelzés
Hamarosan elérhető: 2024-ben fokozatosan kivezetjük a GitHub-problémákat a tartalom visszajelzési mechanizmusaként, és lecseréljük egy új visszajelzési rendszerre. További információ: https://aka.ms/ContentUserFeedback.
Visszajelzés küldése és megtekintése a következőhöz: