Quickstart: Een API voor Table-app bouwen met Python SDK en Azure Cosmos DB
VAN TOEPASSING OP: Tafel
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 schemaloze gegevensopslag waarmee toepassingen gestructureerde NoSQL-gegevens in de cloud kunnen opslaan. Omdat gegevens worden opgeslagen in een schemaloos ontwerp, worden nieuwe eigenschappen (kolommen) automatisch toegevoegd aan de tabel wanneer een object met een nieuw kenmerk wordt toegevoegd aan de tabel. Python-toepassingen hebben toegang tot De Azure Cosmos DB for Table met behulp van de Azure Data Tables SDK voor Python-pakket .
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
De voorbeeldmap 1 starter-app en 2 voltooide apps 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 maakt gebruik van 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 Table, waaronder het opslaan van objecten met extra eigenschappen om de schemaloze mogelijkheden van de API voor Table te demonstreren. In de volgende afbeelding ziet u de lokale toepassing die wordt uitgevoerd in een browser, waarin de weergegevens worden weergegeven 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 tabellen bevat die in uw toepassing worden gebruikt. Maak een account met Azure Portal, Azure CLI of Azure PowerShell.
Meld u aan bij Azure Portal en volg deze stappen om een Azure Cosmos DB-account te maken.
2 - Een tabel maken
Vervolgens moet u een tabel maken in uw Azure Cosmos DB-account om uw toepassing te kunnen 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 uw tabel worden geladen, worden de eigenschappen (kolommen) automatisch zo nodig gemaakt.
Voer in Azure Portal de volgende stappen uit om een tabel in uw Azure Cosmos DB-account te maken.
3 - Azure Cosmos DB-verbindingsreeks ophalen
Voor toegang tot uw tabellen in Azure Cosmos DB heeft uw app de tabel verbindingsreeks nodig voor het Cosmos DB Storage-account. De verbindingsreeks kunnen worden opgehaald met behulp van Azure Portal, Azure CLI of Azure PowerShell.
4 - De Azure Data Tables SDK voor Python installeren
Nadat u een Azure Cosmos DB-account hebt gemaakt, moet u de Microsoft Azure Data Tables SDK voor Python installeren. Raadpleeg het README.md-bestand in de Data Tables SDK voor Python-opslagplaats op GitHub voor meer informatie over het installeren van de SDK.
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 2 voltooide apps .
5 - De tabelclient configureren in een .env-bestand
Kopieer uw Azure Cosmos DB-account verbindingsreeks vanuit Azure Portal en maak een TableServiceClient-object met behulp van uw gekopieerde verbindingsreeks. Schakel over naar de map 1 starter-app of 2 voltooide apps . Ongeacht met welke app u begint, moet u omgevingsvariabelen definiëren in een .env
bestand.
# 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 Azure Cosmos DB for Table. Een toepassing heeft doorgaans één TableServiceClient
algemeen en heeft een TableClient
per tabel.
Met de volgende code wordt bijvoorbeeld een TableServiceClient
object gemaakt met behulp van de verbindingsreeks uit 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 TableServiceHelper
klasse in het Helper-bestand onder de web-app-map. U moet de TableServiceClient
klasse boven aan dit bestand importeren om te kunnen 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 worden geretourneerd uit een tabel, kunt u een OData-stijlfiltertekenreeks doorgeven aan de query_entities
methode. Als u bijvoorbeeld alle weermetingen voor Chicago tussen middernacht 1 juli 2021 en middernacht van 2 juli 2021 (inclusief) wilt ophalen, 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 van 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 'en'-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 filterreeksen te maken zoals vereist voor 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 door een TableEntity
object te gebruiken. In dit voorbeeld worden gegevens toegewezen van een invoermodelobject aan een TableEntity
object. De eigenschappen van het invoerobject die de naam van het weerstation en de datum/tijd van de observatie vertegenwoordigen, worden toegewezen aan respectievelijk de PartitionKey
eigenschappen, 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
Upsert-gegevens met behulp van een TableEntity-object
Als u probeert een rij in te voegen in een tabel met een combinatie van partitiesleutel/rijtoetsen die al in die tabel bestaat, krijgt u een foutmelding. Daarom is het vaak beter om de upsert_entity
in plaats van de create_entity
methode te gebruiken bij het toevoegen van rijen aan een tabel. Als de opgegeven combinatie van partitiesleutel/rijsleutel al bestaat in de tabel, 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 upsert met variabele eigenschappen
Een van de voordelen van het gebruik van Azure Cosmos DB for Table is dat als een object dat wordt geladen in een tabel nieuwe eigenschappen bevat, deze eigenschappen automatisch worden toegevoegd aan de tabel en de waarden die zijn opgeslagen in Azure Cosmos DB. U hoeft DDL-instructies zoals ALTER TABLE niet uit te voeren om kolommen toe te voegen zoals in een traditionele database.
Dit model biedt uw toepassing flexibiliteit bij het omgaan met gegevensbronnen die kunnen toevoegen of wijzigen welke gegevens in de loop van de tijd moeten worden vastgelegd of wanneer verschillende invoergegevens verschillende gegevens aan uw toepassing leveren. 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 uitvouwbare object toe aan een TableEntity
object en gebruikt u de create_entity
of upsert_entity
methoden voor het TableClient
object, indien van toepassing.
In de voorbeeldtoepassing kan de upsert_entity
functie ook de functie van invoeg- of upsert-gegevens implementeren met variabele eigenschappen
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 - Voer de code uit
Voer de voorbeeldtoepassing uit om te communiceren met Azure Cosmos DB for Table. Als u bijvoorbeeld begint in de map met twee voltooide apps , waarbij de vereisten zijn geïnstalleerd, kunt u het volgende gebruiken:
python3 run.py webapp
Zie het bestand README.md 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 aan de tabel toe te voegen.
Als u de knop Invoegen met tabelentiteit selecteert, wordt een dialoogvenster geopend waarin u een nieuwe rij kunt invoegen of een nieuwe rij kunt invoegen met behulp van een TableEntity
object.
Als u de knop Invoegen selecteert met de knop Uitvouwbare gegevens, wordt een dialoogvenster geopend waarmee u een object met aangepaste eigenschappen kunt invoegen, zodat wordt gedemonstreerd hoe eigenschappen (kolommen) automatisch worden toegevoegd aan de tabel 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 voorbeeldmap 1-starter-app moet u ten minste de code voor de
submit_transaction
functie voltooien om de voorbeeldgegevens in te voegen.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 voltooide apps , stelt uproject_root_path
in op '' (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 gebouwd en doorgegeven aan de Azure Cosmos DB for Table.
Resources opschonen
Wanneer u klaar bent met de voorbeeldtoepassing, moet u alle Azure-resources verwijderen die betrekking hebben op dit artikel uit uw Azure-account. U kunt alle resources verwijderen door de resourcegroep te verwijderen.
U kunt een resourcegroep verwijderen met behulp van Azure Portal door het volgende te doen.
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 query's uitvoeren op uw gegevens met behulp van de API voor Table.
Feedback
https://aka.ms/ContentUserFeedback.
Binnenkort: Gedurende 2024 worden GitHub Issues uitgefaseerd als het feedbackmechanisme voor inhoud. Dit wordt vervangen door een nieuw feedbacksysteem. Ga voor meer informatie naar:Feedback verzenden en bekijken voor