Snabbstart: Skapa ett API för tabellapp med Python SDK och Azure Cosmos DB
GÄLLER FÖR:
Tabell
Den här snabbstarten visar hur du kommer åt Azure Cosmos DB API för tabell från ett Python-program. Azure Cosmos DB for Table är ett schemalöst datalager som gör att program kan lagra strukturerade NoSQL-data i molnet. Eftersom data lagras i en schemalös design läggs nya egenskaper (kolumner) automatiskt till i tabellen när ett objekt med ett nytt attribut läggs till i tabellen. Python-program kan komma åt Azure Cosmos DB for Table med hjälp av Azure Data Tables SDK för Python-paketet .
Förutsättningar
Exempelprogrammet är skrivet i Python 3.7 eller senare, även om principerna gäller för alla Python 3.7+-program. Du kan använda Visual Studio Code som en IDE.
Om du inte har en Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.
Exempelprogram
Exempelprogrammet för den här självstudien kan klonas eller laddas ned från lagringsplatsen 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
Exempelmappen 1-starter-app och 2-completed-app ingår i exempellagringsplatsen. 1-starter-appen har vissa funktioner kvar som du kan slutföra med rader markerade "#TODO". Kodfragmenten som visas i den här artikeln är de föreslagna tilläggen för att slutföra 1-starter-appen.
Det färdiga exempelprogrammet använder väderdata som exempel för att demonstrera funktionerna i API:et för tabell. Objekt som representerar väderobservationer lagras och hämtas med hjälp av API:et för tabell, inklusive lagring av objekt med extra egenskaper för att demonstrera de schemalösa funktionerna i API:et för tabell. Följande bild visar det lokala programmet som körs i en webbläsare och visar väderdata som lagras i Azure Cosmos DB for Table.
1 – Skapa ett Azure Cosmos DB-konto
Du måste först skapa ett Azure Cosmos DB Tables API-konto som innehåller de tabeller som används i ditt program. Skapa ett konto med Azure Portal, Azure CLI eller Azure PowerShell.
Logga in på Azure Portal och följ dessa steg för att skapa ett Azure Cosmos DB-konto.
| Instruktioner | Skärmbild |
|---|---|
I Azure-portalen:
|
|
| På sidan Azure Cosmos DB väljer du +Skapa. | 
|
| Välj alternativet Azure Table på sidan Välj API-alternativ. | 
|
På sidan Skapa Azure Cosmos DB-konto – Azure-tabell fyller du i formuläret på följande sätt.
|
|
2 – Skapa en tabell
Därefter måste du skapa en tabell i ditt Azure Cosmos DB-konto som programmet ska använda. Till skillnad från en traditionell databas behöver du bara ange namnet på tabellen, inte egenskaperna (kolumnerna) i tabellen. När data läses in i tabellen skapas egenskaperna (kolumnerna) automatiskt efter behov.
I Azure Portal utför du följande steg för att skapa en tabell i ditt Azure Cosmos DB-konto.
| Instruktioner | Skärmbild |
|---|---|
I Azure Portal går du till översiktssidan för Azure Cosmos DB-kontot.
|
|
| På sidan Översikt väljer du +Lägg till tabell. Dialogrutan Ny tabell visas till höger på sidan. | 
|
I dialogrutan Ny tabell fyller du i formuläret på följande sätt.
|
|
3 – Hämta Azure Cosmos DB-anslutningssträng
För att komma åt dina tabeller i Azure Cosmos DB behöver din app tabellanslutningssträngen för Cosmos DB Storage-kontot. Anslutningssträngen kan hämtas med hjälp av Azure Portal, Azure CLI eller Azure PowerShell.
| Instruktioner | Skärmbild |
|---|---|
| Till vänster på azure Cosmos DB-kontosidan letar du upp menyalternativet Anslutningssträngar under rubriken Inställningar och väljer det. Du kommer till en sida där du kan hämta anslutningssträngen för Azure Cosmos DB-kontot. | 
|
| Kopiera värdet PRIMÄR ANSLUTNINGSSTRÄNG som ska användas i ditt program. | 
|
4 – Installera Azure Data Tables SDK för Python
När du har skapat ett Azure Cosmos DB-konto är nästa steg att installera Microsoft Azure Data Tables SDK för Python. Mer information om hur du installerar SDK finns i filen README.md i Data Tables SDK för Python-lagringsplatsen på GitHub.
Installera Azure Tables-klientbiblioteket för Python med pip:
pip install azure-data-tables
Glöm inte att även installera requirements.txt i mapparna 1-starter-app eller 2-completed-app .
5 – Konfigurera tabellklienten i en .env-fil
Kopiera anslutningssträngen för Ditt Azure Cosmos DB-konto från Azure Portal och skapa ett TableServiceClient-objekt med hjälp av den kopierade anslutningssträngen. Växla till mappen 1-starter-app eller 2-completed-app . Oavsett vilken app du börjar med måste du definiera miljövariabler i en .env fil.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Azure SDK kommunicerar med Azure med hjälp av klientobjekt för att köra olika åtgärder mot Azure. Objektet TableServiceClient är det objekt som används för att kommunicera med Azure Cosmos DB för Table. Ett program har vanligtvis en enda TableServiceClient övergripande och har en TableClient per tabell.
Följande kod skapar till exempel ett TableServiceClient -objekt med hjälp av anslutningssträngen från miljövariabeln.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 – Implementera tabellåtgärder i Azure Cosmos DB
Alla Azure Cosmos DB-tabellåtgärder för exempelappen implementeras i TableServiceHelper klassen som finns i hjälpfilen under katalogen webapp . Du måste importera TableServiceClient klassen överst i den här filen för att arbeta med objekt i klientbiblioteket azure.data.tables för Python.
from azure.data.tables import TableServiceClient
I början av TableServiceHelper klassen skapar du en konstruktor och lägger till en medlemsvariabel för objektet så TableClient att objektet TableClient kan matas in i klassen .
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)
Filtrera rader som returneras från en tabell
Om du vill filtrera de rader som returneras från en tabell kan du skicka en filtersträng för OData-format till query_entities metoden . Om du till exempel vill hämta alla väderavläsningar för Chicago mellan midnatt 1 juli 2021 och midnatt 2 juli 2021 (inklusive) skickar du följande filtersträng.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
Du kan visa relaterade OData-filteroperatorer på webbplatsen azure-data-tables i avsnittet Skriva filter.
När parametern request.args skickas till query_entity metoden i TableServiceHelper klassen skapas en filtersträng för varje egenskapsvärde som inte är null. Därefter skapas en kombinerad filtersträng genom att alla värden kopplas ihop med en "och"-sats. Den här kombinerade filtersträngen query_entities skickas till metoden på TableClient objektet och endast rader som matchar filtersträngen returneras. Du kan använda en liknande metod i koden för att skapa lämpliga filtersträngar som krävs av ditt program.
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)))
Infoga data med ett TableEntity-objekt
Det enklaste sättet att lägga till data i en tabell är att använda ett TableEntity -objekt. I det här exemplet mappas data från ett indatamodellobjekt till ett TableEntity objekt. Egenskaperna för indataobjektet som representerar väderstationens namn och datum/tid för observation mappas till PartitionKey egenskaperna och RowKey , som tillsammans utgör en unik nyckel för raden i tabellen. Sedan mappas de extra egenskaperna för indatamodellobjektet till ordlisteegenskaper för TableEntity-objektet. Slutligen create_entity används metoden för objektet TableClient för att infoga data i tabellen.
insert_entity Ändra funktionen i exempelprogrammet så att den innehåller följande 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-data med ett TableEntity-objekt
Om du försöker infoga en rad i en tabell med en kombination av partitionsnyckel/radnyckel som redan finns i tabellen får du ett felmeddelande. Därför är det ofta bättre att använda upsert_entity i stället för create_entity metoden när du lägger till rader i en tabell. Om den angivna kombinationen av partitionsnyckel/radnyckel redan finns i tabellen uppdaterar upsert_entity metoden den befintliga raden. Annars läggs raden till i tabellen.
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
Infoga eller upsert-data med variabelegenskaper
En av fördelarna med att använda Azure Cosmos DB for Table är att om ett objekt som läses in i en tabell innehåller nya egenskaper läggs dessa egenskaper automatiskt till i tabellen och värdena som lagras i Azure Cosmos DB. Du behöver inte köra DDL-instruktioner som ALTER TABLE för att lägga till kolumner som i en traditionell databas.
Den här modellen ger ditt program flexibilitet när du hanterar datakällor som kan lägga till eller ändra vilka data som behöver samlas in över tid eller när olika indata ger olika data till ditt program. I exempelprogrammet kan vi simulera en väderstation som inte bara skickar basväderdata utan även några extra värden. När ett objekt med dessa nya egenskaper lagras i tabellen för första gången läggs motsvarande egenskaper (kolumner) automatiskt till i tabellen.
Om du vill infoga eller utöka ett sådant objekt med hjälp av API:et för Table mappar du egenskaperna för det expanderbara objektet till ett TableEntity objekt och använder create_entity metoderna eller upsert_entity på TableClient objektet efter behov.
I exempelprogrammet upsert_entity kan funktionen även implementera funktionen för att infoga eller upsert-data med variabelegenskaper
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
Uppdatera en entitet
Entiteter kan uppdateras genom att anropa update_entity -metoden för -objektet TableClient .
I exempelappen skickas det här objektet till upsert_entity -metoden i TableClient klassen . Den uppdaterar entitetsobjektet och använder upsert_entity metoden för att spara uppdateringarna i databasen.
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
Ta bort en entitet
Om du vill ta bort en entitet från en tabell anropar delete_entity du -metoden för TableClient objektet med partitionsnyckeln och radnyckeln för objektet.
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 – Kör koden
Kör exempelprogrammet för att interagera med Azure Cosmos DB for Table. Om du till exempel börjar i mappen 2-completed-app , med installerade krav, kan du använda:
python3 run.py webapp
Mer information om hur du kör exempelprogrammet finns i filen README.md i exempellagringsplatsens rot .
Första gången du kör programmet finns det inga data eftersom tabellen är tom. Använd någon av knapparna överst i programmet för att lägga till data i tabellen.
Om du väljer knappen Infoga med tabellentitet öppnas en dialogruta där du kan infoga eller upsert en ny rad med hjälp av ett TableEntity -objekt.
Om du väljer knappen Infoga med expanderbara data öppnas en dialogruta där du kan infoga ett objekt med anpassade egenskaper, som visar hur Azure Cosmos DB för tabell automatiskt lägger till egenskaper (kolumner) i tabellen vid behov. Använd knappen Lägg till anpassat fält för att lägga till en eller flera nya egenskaper och demonstrera den här funktionen.
Använd knappen Infoga exempeldata för att läsa in exempeldata i din Azure Cosmos DB-tabell.
För exempelmappen 1-starter-app måste du minst slutföra koden för
submit_transactionfunktionen för att exempeldatainfogningen ska fungera.Exempeldata läses in från en sample_data.json-fil . Variabeln
project_root_path.env talar om för appen var den här filen ska hittas. Om du till exempel kör programmet från mappen 1-starter-app eller 2-completed-app anger duproject_root_pathtill "" (tom).
Välj alternativet Filtrera resultat på den översta menyn för att gå till sidan Filterresultat. På den här sidan fyller du i filtervillkoren för att visa hur en filtersats kan skapas och skickas till Azure Cosmos DB för tabell.
Rensa resurser
När du är klar med exempelprogrammet bör du ta bort alla Azure-resurser som är relaterade till den här artikeln från ditt Azure-konto. Du kan ta bort alla resurser genom att ta bort resursgruppen.
Du kan ta bort en resursgrupp med hjälp av Azure Portal genom att göra följande.
| Instruktioner | Skärmbild |
|---|---|
| Om du vill gå till resursgruppen skriver du namnet på resursgruppen i sökfältet. På fliken Resursgrupper väljer du sedan namnet på resursgruppen. | 
|
| Välj Ta bort resursgrupp i verktygsfältet överst på resursgruppssidan. | 
|
En dialogruta öppnas från höger på skärmen där du uppmanas att bekräfta borttagningen av resursgruppen.
|
|
Nästa steg
I den här snabbstarten har du fått lära dig att skapa ett Azure Cosmos DB-konto, skapa en tabell med datautforskaren och att köra en app. Nu kan du köra frågor mot dina data med hjälp av API:et för Table.