Schnellstart: Erstellen einer API für Table-App mit Python SDK und Azure Cosmos DB
GILT FÜR: Tabelle
Dieser Schnellstart zeigt, wie Sie über eine Python-Anwendung auf die API für Table von Azure Cosmos DB zugreifen. Azure Cosmos DB for Table ist ein schemaloser Datenspeicher, der es Anwendungen ermöglicht, strukturierte NoSQL-Daten in der Cloud zu speichern. Da Daten in einem schemalosen Entwurf gespeichert werden, werden der Tabelle automatisch neue Eigenschaften (Spalten) hinzugefügt, wenn der Tabelle ein Objekt mit einem neuen Attribut hinzugefügt wird. Python-Anwendungen können auf Azure Cosmos DB for Table mithilfe des Pakets Azure Data Tables SDK für Python zugreifen.
Voraussetzungen
Die Beispielanwendung wird in Python 3.7 oder höher geschrieben, die Prinzipien gelten jedoch für alle Anwendungen mit Python 3.7 oder höher. Sie können Visual Studio Code als IDE verwenden.
Wenn Sie kein Azure-Abonnement besitzen, erstellen Sie ein kostenloses Konto, bevor Sie beginnen.
Beispielanwendung
Die Beispielanwendung für dieses Tutorial kann aus dem Repository https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask geklont oder heruntergeladen werden.
git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git
Im Beispiel-Repository sind die Beispielordner 1-starter-app und 2-completed-app enthalten. Der Beispielordner 1-starter-app enthält noch einige Funktionen, die Sie vervollständigen müssen. Die Zeilen sind mit „#TODO“ gekennzeichnet. Die in diesem Artikel angezeigten Code-Ausschnitte sind die vorgeschlagenen Ergänzungen, um den Beispielordner 1-starter-app zu vervollständigen.
Die abgeschlossene Beispielanwendung verwendet Wetterdaten als Beispiel, um die Funktionen der API für Table zu veranschaulichen. Objekte, die Wetterbeobachtungen darstellen, werden mithilfe der API für Table gespeichert und abgerufen, einschließlich der Speicherung von Objekten mit zusätzlichen Eigenschaften, um die schemalosen Funktionen der API für Table zu zeigen. Die folgende Abbildung zeigt die lokale Anwendung, die in einem Browser ausgeführt wird und die in Azure Cosmos DB for Table gespeicherten Wetterdaten anzeigt.
1\. Erstellen eines Azure Cosmos DB-Kontos
Zunächst müssen Sie ein Azure Cosmos DB-Tabellen-API-Konto erstellen, das die in Ihrer Anwendung verwendeten Tabellen enthält. Erstellen Sie ein Konto über das Azure-Portal, die Azure CLI oder Azure PowerShell.
Melden Sie sich beim Azure-Portal an, und führen Sie die folgenden Schritte aus, um ein Azure Cosmos DB-Konto zu erstellen.
2\. Erstellen einer Tabelle
Nun müssen Sie eine Tabelle in Ihrem Azure Cosmos DB-Konto erstellen, das von Ihrer Anwendung verwendet wird. Im Gegensatz zu einer herkömmlichen Datenbank müssen Sie nur den Namen der Tabelle angeben, nicht die Eigenschaften (Spalten) in der Tabelle. Wenn Daten in Ihre Tabelle geladen werden, werden die Eigenschaften (Spalten) bei Bedarf automatisch erstellt.
Führen Sie im Azure-Portal die folgenden Schritte aus, um eine Tabelle in Ihrem Azure Cosmos DB-Konto zu erstellen.
3. Abrufen der Azure Cosmos DB-Verbindungszeichenfolge
Für den Zugriff auf Ihre Tabellen in Azure Cosmos DB benötigt Ihre App die Tabellenverbindungszeichenfolge für das Cosmos DB-Speicherkonto. Die Verbindungszeichenfolge kann mithilfe des Azure-Portals, der Azure CLI oder mit Azure PowerShell abgerufen werden.
4. Installieren des Azure Data Tables SDK für Python
Nach dem Erstellen eines Azure Cosmos DB-Kontos installieren Sie im nächsten Schritt das Microsoft Azure Data Tables SDK für Python. Ausführliche Informationen zum Installieren des SDK finden Sie in der Datei README.rst im Repository für das Data Tables SDK für Python auf GitHub.
Installieren Sie die Azure Tables-Clientbibliothek für Python mit pip:
pip install azure-data-tables
Vergessen Sie nicht, die Datei requirements.txt auch in den Ordnern 1-starter-app oder 2-completed-app zu installieren.
5. Konfigurieren des Tabellen-Clients in der ENV-Datei
Kopieren Sie die Verbindungszeichenfolge des Azure Cosmos DB-Kontos aus dem Azure-Portal, und erstellen Sie mithilfe der kopierten Verbindungszeichenfolge ein TableServiceClient-Objekt. Wechseln Sie zum Ordner 1-starter-app oder 2-completed-app. Unabhängig davon, mit welcher App Sie beginnen, müssen Sie Umgebungsvariablen in einer .env
-Datei definieren.
# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"
Das Azure SDK kommuniziert mit Azure mithilfe von Clientobjekten, um verschiedene Vorgänge in Azure auszuführen. Das TableServiceClient
-Objekt ist das Objekt, das für die Kommunikation mit Azure Cosmos DB for Table verwendet wird. Eine Anwendung verfügt in der Regel insgesamt über ein TableServiceClient
-Element und über ein TableClient
-Element pro Tabelle.
Der folgende Code erstellt beispielsweise ein TableServiceClient
-Objekt mithilfe der Verbindungszeichenfolge aus den Umgebungsvariablen.
self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)
6. Implementieren von Azure Cosmos DB-Tabellenvorgängen
Alle Azure Cosmos DB-Tabellenvorgänge für die Beispiel-App werden in der TableServiceHelper
-Klasse implementiert, die sich im Verzeichnis webapp in der Hilfsdatei befindet. Sie müssen die Klasse TableServiceClient
am Anfang dieser Datei importieren, um mit Objekten in der azure.data.tables-Client-Bibliothek für Python zu arbeiten.
from azure.data.tables import TableServiceClient
Erstellen Sie am Anfang der TableServiceHelper
-Klasse einen Konstruktor, und fügen Sie eine Membervariable für das TableClient
-Objekt hinzu, damit das TableClient
-Objekt in die Klasse eingefügt werden kann.
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)
Filtern von Zeilen, die von einer Tabelle zurückgegeben werden
Um die von einer Tabelle zurückgegebenen Zeilen zu filtern, können Sie eine Filterzeichenfolge im OData-Stil an die query_entities
-Methode übergeben. Wenn Sie beispielsweise alle Wetterwerte für Chicago zwischen 1. Juli 2021 Mitternacht und 2. Juli 2021 Mitternacht (einschließlich) abrufen möchten, übergeben Sie die folgende Filterzeichenfolge.
PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'
Sie können verwandte OData-Filteroperatoren auf der Website „azure-data-tables“ im Abschnitt Schreiben von Filtern anzeigen.
Wenn der request.args-Parameter an die query_entity
-Methode in der TableServiceHelper
-Klasse übergeben wird, wird eine Filterzeichenfolge für jeden Eigenschaftswert erstellt, der nicht NULL ist. Anschließend wird eine kombinierte Filterzeichenfolge erstellt, indem alle Werte mit einer „and“-Klausel verbunden werden. Diese kombinierte Filterzeichenfolge wird an die query_entities
-Methode für das TableClient
-Objekt übergeben, und nur Zeilen, die der Filterzeichenfolge entsprechen, werden zurückgegeben. Sie können eine ähnliche Methode in Ihrem Code verwenden, um für Ihre Anwendung erforderliche geeignete Filterzeichenfolgen zu erstellen.
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)))
Einfügen von Daten mithilfe eines TableEntity-Objekts
Die einfachste Möglichkeit zum Hinzufügen von Daten zu einer Tabelle ist die Verwendung eines TableEntity
-Objekts. In diesem Beispiel werden Daten aus einem Eingabemodellobjekt einem TableEntity
-Objekt zugeordnet. Die Eigenschaften des Eingabeobjekts, die den Namen der Wetterstation und das Datum/die Uhrzeit der Beobachtung darstellen, werden der Eigenschaft PartitionKey
bzw. RowKey
zugeordnet, die zusammen einen eindeutigen Schlüssel für die Zeile in der Tabelle bilden. Anschließend werden die zusätzlichen Eigenschaften des Eingabemodellobjekts Wörterbucheigenschaften für das TableEntity-Objekt zugeordnet. Schließlich wird die create_entity
-Methode für das TableClient
-Objekt verwendet, um Daten in die Tabelle einzufügen.
Ändern Sie die insert_entity
-Funktion in der Beispielanwendung so, dass sie den folgenden Code enthält:
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
Ausführen eines Upserts von Daten mithilfe eines TableEntity-Objekts
Wenn Sie versuchen, eine Zeile in eine Tabelle mit einer Kombination aus Partitionsschlüssel und Zeilenschlüssel einzufügen, die bereits in dieser Tabelle vorhanden ist, erhalten Sie einen Fehler. Aus diesem Grund ist es häufig vorzuziehen, beim Hinzufügen von Zeilen zu einer Tabelle upsert_entity
anstelle der create_entity
-Methode zu verwenden. Wenn die angegebene Kombination aus Partitionsschlüssel und Zeilenschlüssel bereits in der Tabelle vorhanden ist, aktualisiert die upsert_entity
-Methode die vorhandene Zeile. Andernfalls wird die Zeile der Tabelle hinzugefügt.
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
Einfügen oder Upsert von Daten mit variablen Eigenschaften
Einer der Vorteile der Verwendung von Azure Cosmos DB for Table besteht darin, dass beim Laden eines Objekts in eine Tabelle neue Eigenschaften automatisch zur Tabelle hinzugefügt und die Werte in Azure Cosmos DB gespeichert werden. Es besteht keine Notwendigkeit, DDL-Anweisungen wie ALTER TABLE auszuführen, um Spalten hinzuzufügen, wie es bei einer herkömmlichen Datenbank der Fall ist.
Dieses Modell bietet Ihrer Anwendung Flexibilität beim Umgang mit Datenquellen, die im Laufe der Zeit Daten hinzufügen oder ändern können, oder wenn unterschiedliche Eingaben unterschiedliche Daten für Ihre Anwendung bereitstellen. In der Beispielanwendung können wir eine Wetterstation simulieren, die nicht nur die Basiswetterdaten, sondern auch einige zusätzliche Werte sendet. Wenn ein Objekt mit diesen neuen Eigenschaften zum ersten Mal in der Tabelle gespeichert wird, werden der Tabelle automatisch die entsprechenden Eigenschaften (Spalten) hinzugefügt.
Um ein solches Objekt mithilfe der API für Table einzufügen oder ein Upsert auszuführen, ordnen Sie die Eigenschaften des erweiterbaren Objekts einem TableEntity
-Objekt zu und verwenden je nach Bedarf die Methoden create_entity
oder upsert_entity
für das TableClient
-Objekt.
In der Beispielanwendung kann die upsert_entity
-Funktion auch die Einfüge- oder Upsertfunktion für Daten mit variablen Eigenschaften implementieren.
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
Aktualisieren einer Entität
Entitäten können aktualisiert werden, indem die update_entity
-Methode für das TableClient
-Objekt aufgerufen wird.
In der Beispiel-App wird dieses Objekt an die upsert_entity
-Methode in der TableClient
-Klasse übergeben. Dieses Entitätsobjekt wird aktualisiert, und die upsert_entity
-Methode wird verwendet, um die Aktualisierungen der Datenbank zu speichern.
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
Entfernen einer Entität
Um eine Entität aus einer Tabelle zu entfernen, rufen Sie die delete_entity
-Methode für das TableClient
-Objekt mit dem Partitionsschlüssel und Zeilenschlüssel des Objekts auf.
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\. Ausführen des Codes
Führen Sie die Beispielanwendung aus, um mit Azure Cosmos DB for Table zu interagieren. Ab dem Ordner 2-completed-app mit installierten Anforderungen können Sie beispielsweise Folgendes verwenden:
python3 run.py webapp
Weitere Informationen zum Ausführen der Beispielanwendung finden Sie in der Datei README.md im Stammverzeichnis des Beispiel-Repositorys.
Wenn Sie die Anwendung zum ersten Mal ausführen, sind keine Daten vorhanden, weil die Tabelle leer ist. Verwenden Sie eine der Schaltflächen oben in der Anwendung, um der Tabelle Daten hinzuzufügen.
Wenn Sie die Schaltfläche Insert using Table Entity (Mit Tabellenentität einfügen) auswählen, wird ein Dialogfeld geöffnet, in dem Sie eine neue Zeile mithilfe eines TableEntity
-Objekts einfügen oder ein Upsert ausführen können.
Wenn Sie auf die Schaltfläche Mit erweiterbaren Daten einfügen klicken, wird ein Dialogfeld geöffnet, in dem Sie ein Objekt mit benutzerdefinierten Eigenschaften einfügen können. Dies zeigt, wie Azure Cosmos DB for Table bei Bedarf automatisch Eigenschaften (Spalten) zur Tabelle hinzufügt. Verwenden Sie die Schaltfläche Add Custom Field (Benutzerdefiniertes Feld hinzufügen), um mindestens eine neue Eigenschaft hinzuzufügen und diese Funktion zu veranschaulichen.
Verwenden Sie die Schaltfläche Beispieldaten einfügen, um einige Beispieldaten in Ihre Azure Cosmos DB-Tabelle zu laden.
Für den Beispielordner 1-starter-app müssen Sie mindestens den Code für die Funktion
submit_transaction
vervollständigen, damit die Beispieldaten eingefügt werden können.Die Beispieldaten werden aus einer sample_data.json-Datei geladen. Die Variable .env
project_root_path
teilt der App mit, wo diese Datei zu finden ist. Wenn Sie die Anwendung beispielsweise aus dem Ordner 1-starter-app oder 2-completed-app ausführen, legen Sieproject_root_path
auf "" (leer) fest.
Wählen Sie im oberen Menü das Element Filter Results (Filterergebnisse) aus, um zur Seite „Filter Results“ zu gelangen. Füllen Sie auf dieser Seite die Filterkriterien aus, um zu zeigen, wie eine Filterklausel erstellt und an Azure Cosmos DB for Table übergeben werden kann.
Bereinigen von Ressourcen
Wenn Sie die Beispielanwendung abgeschlossen haben, sollten Sie alle Azure-Ressourcen im Zusammenhang mit diesem Artikel aus Ihrem Azure-Konto entfernen. Sie können alle Ressourcen entfernen, indem Sie die Ressourcengruppe löschen.
Eine Ressourcengruppe kann über das Azure-Portal wie folgt gelöscht werden.
Nächste Schritte
In diesem Schnellstart haben Sie gelernt, wie Sie ein Azure Cosmos DB-Konto erstellen, eine Tabelle mit dem Daten-Explorer erstellen und eine App ausführen. Jetzt können Sie Ihre Daten mithilfe der API für Table abfragen.