Quickstart: Een API voor Tabel-app bouwen met Python SDK en Azure Cosmos DB
VAN TOEPASSING OP:
Tabel
In deze quickstart ziet u hoe u toegang hebt tot de Azure Cosmos DB-API voor Table vanuit een Python-toepassing. Azure Cosmos DB for Table is een schemaloos gegevensarchief waarmee toepassingen gestructureerde NoSQL-gegevens in de cloud kunnen opslaan. Omdat gegevens worden opgeslagen in een schemaloos ontwerp, worden nieuwe eigenschappen (kolommen) automatisch aan de tabel toegevoegd wanneer een object met een nieuw kenmerk aan de tabel wordt toegevoegd. Python-toepassingen hebben toegang tot Azure Cosmos DB for Table met behulp van het Pakket Azure Data Tables SDK voor Python .
Vereisten
De voorbeeldtoepassing is geschreven in Python 3.7 of hoger, hoewel de principes van toepassing zijn op alle Python 3.7+-toepassingen. U kunt Visual Studio Code gebruiken als een IDE.
Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.
Voorbeeldtoepassing
De voorbeeldtoepassing voor deze zelfstudie kan worden gekloond of gedownload uit de opslagplaats 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
Een map 1-starter-app en 2-completed-app-voorbeeldmap zijn opgenomen in de voorbeeldopslagplaats. De 1-starter-app heeft nog enkele functionaliteit die u kunt voltooien met regels die zijn gemarkeerd als '#TODO'. De codefragmenten die in dit artikel worden weergegeven, zijn de voorgestelde toevoegingen om de 1-starter-app te voltooien.
De voltooide voorbeeldtoepassing gebruikt weergegevens als voorbeeld om de mogelijkheden van de API voor Table te demonstreren. Objecten die weerobservaties vertegenwoordigen, worden opgeslagen en opgehaald met behulp van de API voor Tabel, inclusief het opslaan van objecten met extra eigenschappen om de schemaloze mogelijkheden van de API voor Tabel te demonstreren. In de volgende afbeelding ziet u de lokale toepassing die wordt uitgevoerd in een browser, met de weergegevens die zijn opgeslagen in Azure Cosmos DB for Table.
1 - Een Azure Cosmos DB-account maken
U moet eerst een Azure Cosmos DB Tables-API-account maken dat de tabel(en) bevat die in uw toepassing worden gebruikt. Maak een account met de Azure Portal, Azure CLI of Azure PowerShell.
Meld u aan bij de Azure Portal en volg deze stappen om een Azure Cosmos DB-account te maken.
| Instructies | Schermopname |
|---|---|
In Azure Portal:
|
|
| Selecteer +Maken op de pagina Azure Cosmos DB. | 
|
| Kies op de pagina API-optie selecteren de optie Azure-tabel . | 
|
Vul op de pagina Azure Cosmos DB-account maken - Azure Table het formulier als volgt in.
|
|
2 - Een tabel maken
Vervolgens moet u een tabel in uw Azure Cosmos DB-account maken die uw toepassing kan gebruiken. In tegenstelling tot een traditionele database hoeft u alleen de naam van de tabel op te geven, niet de eigenschappen (kolommen) in de tabel. Wanneer gegevens in de tabel worden geladen, worden de eigenschappen (kolommen) automatisch gemaakt als dat nodig is.
Voer in de Azure Portal de volgende stappen uit om een tabel te maken in uw Azure Cosmos DB-account.
| Instructies | Schermopname |
|---|---|
Ga in de Azure Portal naar de overzichtspagina voor het Azure Cosmos DB-account.
|
|
| Selecteer op de pagina Overzichtde optie +Tabel toevoegen. Het dialoogvenster Nieuwe tabel schuift vanaf de rechterkant van de pagina uit. | 
|
Vul in het dialoogvenster Nieuwe tabel het formulier als volgt in.
|
|
3 - Azure Cosmos DB-connection string ophalen
Voor toegang tot uw tabel(s) in Azure Cosmos DB heeft uw app de tabel connection string voor het Cosmos DB Storage-account nodig. De connection string kan worden opgehaald met behulp van de Azure Portal, Azure CLI of Azure PowerShell.
| Instructies | Schermopname |
|---|---|
| Zoek aan de linkerkant van de Azure Cosmos DB-accountpagina het menu-item met de naam Verbindingsreeksen onder de kop Instellingen en selecteer deze. U wordt naar een pagina geleid waar u de connection string voor het Azure Cosmos DB-account kunt ophalen. | 
|
| Kopieer de waarde van PRIMARY CONNECTION STRING voor gebruik in uw toepassing. | 
|
4 - Installeer de Azure Data Tables SDK voor Python
Nadat u een Azure Cosmos DB-account hebt gemaakt, is de volgende stap het installeren van de Microsoft Azure Data Tables SDK voor Python. Raadpleeg voor meer informatie over het installeren van de SDK het README.md-bestand in de opslagplaats Data Tables SDK voor Python op GitHub.
Installeer de Azure Tables-clientbibliotheek voor Python met pip:
pip install azure-data-tables
Vergeet niet om ook de requirements.txt te installeren in de mappen 1-starter-app of twee voltooide apps .
5 - De tabelclient configureren in een .env-bestand
Kopieer uw Azure Cosmos DB-account connection string van de Azure Portal en maak een TableServiceClient-object met behulp van uw gekopieerde connection string. Schakel over naar de map 1-starter-app of 2-completed-app . Ongeacht met welke app u begint, moet u omgevingsvariabelen in een .env bestand definiëren.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
De Azure SDK communiceert met Azure met behulp van clientobjecten om verschillende bewerkingen uit te voeren op Azure. Het TableServiceClient object is het object dat wordt gebruikt om te communiceren met de Azure Cosmos DB for Table. Een toepassing heeft doorgaans één TableServiceClient algemeen en een TableClient per tabel.
Met de volgende code wordt bijvoorbeeld een TableServiceClient -object gemaakt met behulp van de connection string van de omgevingsvariabele.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6 - Azure Cosmos DB-tabelbewerkingen implementeren
Alle Azure Cosmos DB-tabelbewerkingen voor de voorbeeld-app worden geïmplementeerd in de klasse die zich in het TableServiceHelperhelperbestand onder de map web-app bevindt. U moet de TableServiceClient klasse bovenaan dit bestand importeren om te werken met objecten in de clientbibliotheek azure.data.tables voor Python.
from azure.data.tables import TableServiceClient
Maak aan het begin van de TableServiceHelper klasse een constructor en voeg een lidvariabele toe voor het TableClient object, zodat het TableClient object in de klasse kan worden geïnjecteerd.
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)
Rijen filteren die worden geretourneerd uit een tabel
Als u de rijen wilt filteren die uit een tabel worden geretourneerd, kunt u een OData-filterreeks doorgeven aan de query_entities methode. Als u bijvoorbeeld alle weerwaarden voor Chicago wilt ophalen tussen 1 middernacht 2021 en middernacht 2 juli 2021 (inclusief), geeft u de volgende filtertekenreeks door.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
U kunt gerelateerde OData-filteroperators weergeven op de website azure-data-tables in de sectie Filters schrijven.
Wanneer de parameter request.args wordt doorgegeven aan de query_entity methode in de TableServiceHelper klasse, wordt er een filtertekenreeks gemaakt voor elke niet-null-eigenschapswaarde. Vervolgens wordt een gecombineerde filtertekenreeks gemaakt door alle waarden samen te voegen met een 'and'-component. Deze gecombineerde filtertekenreeks wordt doorgegeven aan de query_entities methode voor het TableClient object en alleen rijen die overeenkomen met de filtertekenreeks worden geretourneerd. U kunt een vergelijkbare methode in uw code gebruiken om geschikte filtertekenreeksen te maken zoals vereist door uw toepassing.
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)))
Gegevens invoegen met behulp van een TableEntity-object
De eenvoudigste manier om gegevens toe te voegen aan een tabel is met behulp van een TableEntity -object. In dit voorbeeld worden gegevens van een invoermodelobject toegewezen aan een TableEntity object. De eigenschappen op het invoerobject dat de naam van het weerstation en de observatiedatum/-tijd vertegenwoordigt, worden toegewezen aan respectievelijk de PartitionKey eigenschappen en RowKey , die samen een unieke sleutel vormen voor de rij in de tabel. Vervolgens worden de extra eigenschappen van het invoermodelobject toegewezen aan woordenlijsteigenschappen in het object TableEntity. Ten slotte wordt de create_entity methode voor het TableClient object gebruikt om gegevens in de tabel in te voegen.
Wijzig de insert_entity functie in de voorbeeldtoepassing zodat deze de volgende code bevat.
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
Gegevens upsert met behulp van een TableEntity-object
Als u probeert een rij in te voegen in een tabel met een combinatie van partitiesleutel en rijsleutel die al in die tabel bestaat, krijgt u een foutmelding. Daarom is het vaak beter om de in plaats van de upsert_entitycreate_entity methode te gebruiken bij het toevoegen van rijen aan een tabel. Als de opgegeven combinatie van partitiesleutel/rijsleutel al in de tabel bestaat, werkt de upsert_entity methode de bestaande rij bij. Anders wordt de rij toegevoegd aan de tabel.
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
Gegevens invoegen of upserten met variabele eigenschappen
Een van de voordelen van het gebruik van Azure Cosmos DB for Table is dat als een object dat in een tabel wordt geladen, nieuwe eigenschappen bevat, deze eigenschappen automatisch worden toegevoegd aan de tabel en de waarden die zijn opgeslagen in Azure Cosmos DB. Het is niet nodig om DDL-instructies zoals ALTER TABLE uit te voeren om kolommen toe te voegen, zoals in een traditionele database.
Dit model biedt uw toepassing flexibiliteit wanneer u te maken krijgt met gegevensbronnen die in de loop van de tijd kunnen toevoegen of wijzigen welke gegevens moeten worden vastgelegd, of wanneer verschillende invoer verschillende gegevens voor uw toepassing bieden. In de voorbeeldtoepassing kunnen we een weerstation simuleren dat niet alleen de basisweergegevens verzendt, maar ook enkele extra waarden. Wanneer een object met deze nieuwe eigenschappen voor het eerst in de tabel wordt opgeslagen, worden de bijbehorende eigenschappen (kolommen) automatisch toegevoegd aan de tabel.
Als u een dergelijk object wilt invoegen of upsert met behulp van de API voor Tabel, wijst u de eigenschappen van het uitbreidbare object toe aan een TableEntity object en gebruikt u de create_entity methoden of upsert_entity voor het TableClient object.
In de voorbeeldtoepassing kan de upsert_entity functie ook de functie van het invoegen of upserten van gegevens met variabele eigenschappen implementeren
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
Een entiteit bijwerken
Entiteiten kunnen worden bijgewerkt door de update_entity methode voor het TableClient object aan te roepen.
In de voorbeeld-app wordt dit object doorgegeven aan de upsert_entity methode in de TableClient klasse . Het werkt dat entiteitsobject bij en gebruikt de upsert_entity methode om de updates op te slaan in de database.
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
Een entiteit verwijderen
Als u een entiteit uit een tabel wilt verwijderen, roept u de delete_entity methode voor het TableClient object aan met de partitiesleutel en rijsleutel van het object.
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 - De code uitvoeren
Voer de voorbeeldtoepassing uit om te communiceren met Azure Cosmos DB for Table. Als u bijvoorbeeld begint in de map 2-completed-app en de vereisten zijn geïnstalleerd, kunt u het volgende gebruiken:
python3 run.py webapp
Zie het README.md-bestand in de hoofdmap van de voorbeeldopslagplaats voor meer informatie over het uitvoeren van de voorbeeldtoepassing.
De eerste keer dat u de toepassing uitvoert, zijn er geen gegevens omdat de tabel leeg is. Gebruik een van de knoppen bovenaan de toepassing om gegevens toe te voegen aan de tabel.
Als u de knop Invoegen met tabelentiteit selecteert, wordt een dialoogvenster geopend waarin u een nieuwe rij kunt invoegen of een upsert met behulp van een TableEntity object.
Als u de knop Invoegen met uitvouwbare gegevens selecteert, wordt een dialoogvenster geopend waarin u een object met aangepaste eigenschappen kunt invoegen, waarmee wordt gedemonstreerd hoe in Azure Cosmos DB voor tabel automatisch eigenschappen (kolommen) aan de tabel worden toegevoegd wanneer dat nodig is. Gebruik de knop Aangepast veld toevoegen om een of meer nieuwe eigenschappen toe te voegen en deze mogelijkheid te demonstreren.
Gebruik de knop Voorbeeldgegevens invoegen om enkele voorbeeldgegevens in uw Azure Cosmos DB-tabel te laden.
Voor de map 1-starter-app-voorbeeld moet u ten minste de code voor de
submit_transactionfunctie voltooien om de voorbeeldgegevensinvoeging te laten werken.De voorbeeldgegevens worden geladen vanuit een sample_data.json-bestand . De variabele
project_root_path.env vertelt de app waar dit bestand moet worden gevonden. Als u bijvoorbeeld de toepassing uitvoert vanuit de map 1-starter-app of 2-completed-app , stelt u inproject_root_pathop '' (leeg).
Selecteer het item Resultaten filteren in het bovenste menu om naar de pagina Resultaten filteren te gaan. Vul op deze pagina de filtercriteria in om te laten zien hoe een filtercomponent kan worden gemaakt en doorgegeven aan de Azure Cosmos DB for Table.
Resources opschonen
Wanneer u klaar bent met de voorbeeldtoepassing, moet u alle Azure-resources met betrekking tot dit artikel verwijderen uit uw Azure-account. U kunt alle resources verwijderen door de resourcegroep te verwijderen.
Een resourcegroep kan als volgt worden verwijderd met behulp van de Azure Portal.
| Instructies | Schermopname |
|---|---|
| Als u naar de resourcegroep wilt gaan, typt u in de zoekbalk de naam van de resourcegroep. Selecteer vervolgens op het tabblad Resourcegroepen de naam van de resourcegroep. | 
|
| Selecteer Resourcegroep verwijderen op de werkbalk bovenaan de pagina van de resourcegroep. | 
|
Er verschijnt een dialoogvenster aan de rechterkant van het scherm waarin u wordt gevraagd om het verwijderen van de resourcegroep te bevestigen.
|
|
Volgende stappen
In deze Quick Start hebt u geleerd hoe u een Azure Cosmos DB-account kunt maken, hebt u een tabel gemaakt met de Data Explorer en hebt u een app uitgevoerd. U kunt nu een query uitvoeren op uw gegevens met behulp van de API voor Tabel.