Snabbstart: Skapa ett API för tabellapp med Python SDK och Azure Cosmos DB
GÄLLER FÖR: 
Bord
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, men 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 kan du skapa ettkostnadsfritt konto innan du börjar.
Programexempel
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
En 1-starter-app - och 2-completed-app-exempelmapp ingår i exempellagringsplatsen. 1-starter-appen har vissa funktioner kvar att 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-portalen, Azure CLI eller Azure PowerShell.
Logga in på Azure-portalen 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. | 
|
| På sidan Välj API-alternativ väljer du alternativet Azure Table. | 
|
På sidan Skapa Azure Cosmos DB-konto – Azure Table 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-portalen utför du följande steg för att skapa en tabell i ditt Azure Cosmos DB-konto.
| Instruktioner | Skärmbild |
|---|---|
I Azure-portalen 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-niska veze
För att komma åt dina tabeller i Azure Cosmos DB behöver din app tabellen niska veze för Cosmos DB Storage-kontot. Niska veze kan hämtas med hjälp av Azure-portalen, Azure CLI eller Azure PowerShell.
| Instruktioner | Skärmbild |
|---|---|
| Till vänster på sidan för Azure Cosmos DB-kontot letar du upp menyalternativet Med namnet Anslutningssträngar under rubriken Inställningar och väljer det. Du kommer till en sida där du kan hämta niska veze 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 ditt Azure Cosmos DB-konto niska veze från Azure-portalen och skapa ett TableServiceClient-objekt med den kopierade niska veze. 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 det kommer att ha en TableClient per tabell.
Följande kod skapar till exempel ett TableServiceClient objekt med hjälp av niska veze 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 TableClient objektet 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 raderna som returneras från en tabell kan du skicka en filtersträng i query_entities OData-format till metoden. Om du till exempel vill få 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. Sedan 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 konstruera 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 i TableEntity-objektet. Slutligen create_entity används metoden för TableClient objektet 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 fel. Därför är det ofta bättre att använda upsert_entity metoden i stället för create_entity när du lägger till rader i en tabell. Om den angivna kombinationen av partitionsnyckel/radnyckel redan finns i tabellen upsert_entity uppdaterar 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 öka 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 tabell 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 öka 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 TableClient objektet.
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 README.md-filen 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 utöka en ny rad med hjälp av ett TableEntity objekt.
När du väljer knappen Infoga med expanderbara data visas en dialogruta där du kan infoga ett objekt med anpassade egenskaper, vilket visar hur Azure Cosmos DB för tabell automatiskt lägger till egenskaper (kolumner) i tabellen när det behövs. 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 några exempeldata i din Azure Cosmos DB-tabell.
För exempelmappen 1-starter-app måste du åtminstone slutföra koden för funktionen för
submit_transactionatt 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 som ska tas 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 for Table.
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-portalen 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 visas 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 Tabell.