Share via

Azure Tables-Clientbibliothek für Python – Version 12.4.4

  • Artikel

Azure Tables ist ein NoSQL-Datenspeicherdienst, auf den von überall auf der Welt über authentifizierte Aufrufe über HTTP oder HTTPS zugegriffen werden kann. Tabellen werden nach Bedarf skaliert, um die menge der eingefügten Daten zu unterstützen und das Speichern von Daten mit nicht komplexem Zugriff zu ermöglichen. Der Azure Tables-Client kann für den Zugriff auf Azure Storage- oder Cosmos-Konten verwendet werden. Dieses Dokument behandelt azure-data-tables.

Bitte beachten Sie, dass dieses Paket ein Ersatz ist, für azure-cosmosdb-tables das jetzt veraltet ist. Weitere Informationen finden Sie im Migrationsleitfaden .

Quellcode | Paket (PyPI) | Paket (Conda) | API-Referenzdokumentation | Proben

Haftungsausschluss

Die Unterstützung von Python-Paketen für Das Azure SDK für Python 2.7 wurde am 01. Januar 2022 eingestellt. Weitere Informationen und Fragen finden Sie unter https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 oder höher ist erforderlich, um dieses Paket zu verwenden. Weitere Informationen finden Sie unter Supportrichtlinie für Azure SDK für Python-Versionen.

Erste Schritte

Das Azure Tables SDK kann auf ein Azure Storage- oder CosmosDB-Konto zugreifen.

Voraussetzungen

Erstellen eines Kontos

Installieren des Pakets

Installieren Sie die Azure Tables-Clientbibliothek für Python mit pip:

pip install azure-data-tables

Erstellen des Clients

Mit der Azure Tables-Bibliothek können Sie mit zwei Arten von Ressourcen interagieren:

  • die Tabellen in Ihrem Konto
  • die Entitäten in diesen Tabellen. Die Interaktion mit diesen Ressourcen beginnt mit einer instance eines Clients. Zum Erstellen eines Clientobjekts benötigen Sie die Tabellendienstendpunkt-URL des Kontos und anmeldeinformationen, mit denen Sie auf das Konto zugreifen können. Die endpoint finden Sie auf der Seite für Ihr Speicherkonto im Azure-Portal im Abschnitt "Zugriffsschlüssel" oder indem Sie den folgenden Azure CLI-Befehl ausführen:
# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

Sobald Sie über die Konto-URL verfügen, kann sie zum Erstellen des Dienstclients verwendet werden:

from azure.data.tables import TableServiceClient
service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net/", credential=credential)

Weitere Informationen zu Tabellendienst-URLs und zum Konfigurieren benutzerdefinierter Domänennamen für Azure Storage finden Sie in der offiziellen Dokumentation.

Anmeldeinformationen

Der credential Parameter kann in verschiedenen Formen bereitgestellt werden, abhängig von der Art der Autorisierung, die Sie verwenden möchten. Die Tabellenbibliothek unterstützt die folgenden Autorisierungen:

  • Gemeinsam verwendeter Schlüssel
  • Verbindungszeichenfolge
  • Shared Access Signature Token
Erstellen des Clients aus einem freigegebenen Schlüssel

Um einen freigegebenen Kontoschlüssel (auch als Kontoschlüssel oder Zugriffsschlüssel bezeichnet) zu verwenden, geben Sie den Schlüssel als Zeichenfolge an. Dies finden Sie in Ihrem Speicherkonto im Azure-Portal im Abschnitt "Zugriffsschlüssel" oder indem Sie den folgenden Azure CLI-Befehl ausführen:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Verwenden Sie den Schlüssel als Anmeldeinformationsparameter, um den Client zu authentifizieren:

from azure.core.credentials import AzureNamedKeyCredential
from azure.data.tables import TableServiceClient

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")

service = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=credential)
Erstellen des Clients aus einer Verbindungszeichenfolge

Je nach Anwendungsfall und Autorisierungsmethode können Sie es vorziehen, einen Client instance mit einer Verbindungszeichenfolge zu initialisieren, anstatt die Konto-URL und die Anmeldeinformationen separat bereitzustellen. Übergeben Sie dazu die Verbindungszeichenfolge an die Klassenmethode des from_connection_string Clients. Die Verbindungszeichenfolge finden Sie in Ihrem Speicherkonto im Azure-Portal im Abschnitt "Zugriffsschlüssel" oder mit dem folgenden Azure CLI-Befehl:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

from azure.data.tables import TableServiceClient
connection_string = "DefaultEndpointsProtocol=https;AccountName=<my_account_name>;AccountKey=<my_account_key>;EndpointSuffix=core.windows.net"
service = TableServiceClient.from_connection_string(conn_str=connection_string)
Erstellen des Clients aus einem SAS-Token

Um ein SAS-Token (Shared Access Signature) zu verwenden, geben Sie das Token als Zeichenfolge an. Wenn Ihre Konto-URL das SAS-Token enthält, lassen Sie den Parameter mit Anmeldeinformationen aus. Sie können ein SAS-Token im Azure-Portal unter Shared Access Signature generieren oder eine der generate_*_sas() Funktionen verwenden, um ein SAS-Token für das Konto oder die Tabelle zu erstellen:

from datetime import datetime, timedelta
from azure.data.tables import TableServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions
from azure.core.credentials import AzureNamedKeyCredential, AzureSasCredential

credential = AzureNamedKeyCredential("my_account_name", "my_access_key")
sas_token = generate_account_sas(
    credential,
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1),
)

table_service_client = TableServiceClient(endpoint="https://<my_account_name>.table.core.windows.net", credential=AzureSasCredential(sas_token))

Wichtige Begriffe

Zu den gängigen Verwendungen des Tabellendiensts gehören:

  • Speicherung strukturierter Daten in TB-Größe zur Verarbeitung webbasierter Anwendungen
  • Speichern von Datasets, die keine komplexen Joins, Fremdschlüssel oder gespeicherten Prozeduren erfordern und für den schnellen Zugriff denormisiert werden können
  • Schnelle Datenabfrage mithilfe eines gruppierten Index
  • Zugreifen auf Daten mit dem OData-Protokoll und LINQ-Filterausdrücken

Der Azure Tables Service besteht aus den folgenden Komponenten:

  • Das Konto
  • Eine Tabelle innerhalb des Kontos, die eine Gruppe von Entitäten enthält
  • Eine Entität innerhalb einer Tabelle als Wörterbuch

Mit der Azure Tables-Clientbibliothek für Python können Sie mit jeder dieser Komponenten über ein dediziertes Clientobjekt interagieren.

Clients

Für die Interaktion mit den verschiedenen Komponenten des Tabellendiensts werden zwei verschiedene Clients bereitgestellt:

  1. TableServiceClient -
    • Abrufen und Festlegen der Kontoeinstellung
    • Abfragen, Erstellen und Löschen von Tabellen innerhalb des Kontos.
    • Rufen Sie einen ab TableClient , um mithilfe der get_table_client -Methode auf eine bestimmte Tabelle zuzugreifen.
  2. TableClient -
    • Interagiert mit einer bestimmten Tabelle (die noch nicht vorhanden sein muss).
    • Erstellen, Löschen, Abfragen und Upsert-Entitäten innerhalb der angegebenen Tabelle.
    • Erstellen oder löschen Sie die angegebene Tabelle selbst.

Entitäten

Entitäten sind Zeilen ähnlich. Eine Entität verfügt über eine PartitionKey- , - RowKeyund eine Reihe von Eigenschaften. Eine Eigenschaft ist ein Name-Wert-Paar, ähnlich einer Spalte. Jede Entität in einer Tabelle muss nicht über dieselben Eigenschaften verfügen. Entitäten können als Beispiel als Wörterbücher dargestellt werden:

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}
  • create_entity : Fügen Sie der Tabelle eine Entität hinzu.
  • delete_entity : Löschen Sie eine Entität aus der Tabelle.
  • update_entity : Aktualisieren Sie die Informationen einer Entität, indem Sie die vorhandene Entität entweder zusammenführen oder ersetzen.
    • UpdateMode.MERGE fügt einer vorhandenen Entität neue Eigenschaften hinzu, es werden keine vorhandenen Eigenschaften gelöscht.
    • UpdateMode.REPLACE ersetzt die vorhandene Entität durch die angegebene Entität und löscht alle vorhandenen Eigenschaften, die nicht in der übermittelten Entität enthalten sind.
  • query_entities : Abfragen vorhandener Entitäten in einer Tabelle mithilfe von OData-Filtern.
  • get_entity : Abrufen einer bestimmten Entität aus einer Tabelle nach Partition und Zeilenschlüssel.
  • upsert_entity : Führen Sie eine Entität in einer Tabelle zusammen, oder ersetzen Sie sie, oder fügt die Entität ein, wenn die Entität nicht vorhanden ist.
    • UpdateMode.MERGE fügt einer vorhandenen Entität neue Eigenschaften hinzu, es werden keine vorhandenen Eigenschaften gelöscht.
    • UpdateMode.REPLACE ersetzt die vorhandene Entität durch die angegebene Entität und löscht alle vorhandenen Eigenschaften, die nicht in der übermittelten Entität enthalten sind.

Beispiele

Die folgenden Abschnitte enthalten mehrere Codeausschnitte, die einige der gängigsten Tabellenaufgaben abdecken, einschließlich:

Erstellen einer Tabelle

Erstellen Sie eine Tabelle in Ihrem Konto, und rufen Sie eine ab TableClient , um Vorgänge für die neu erstellte Tabelle auszuführen:

from azure.data.tables import TableServiceClient
table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_name = "myTable"
table_client = table_service_client.create_table(table_name=table_name)

Erstellen von Entitäten

Erstellen Sie Entitäten in der Tabelle:

from azure.data.tables import TableServiceClient
from datetime import datetime

PRODUCT_ID = u'001234'
PRODUCT_NAME = u'RedMarker'

my_entity = {
    u'PartitionKey': PRODUCT_NAME,
    u'RowKey': PRODUCT_ID,
    u'Stock': 15,
    u'Price': 9.99,
    u'Comments': u"great product",
    u'OnSale': True,
    u'ReducedPrice': 7.99,
    u'PurchaseDate': datetime(1973, 10, 4),
    u'BinaryRepresentation': b'product_name'
}

table_service_client = TableServiceClient.from_connection_string(conn_str="<connection_string>")
table_client = table_service_client.get_table_client(table_name="myTable")

entity = table_client.create_entity(entity=my_entity)

Abfragen von Entitäten

Abfragen von Entitäten in der Tabelle:

from azure.data.tables import TableClient
my_filter = "PartitionKey eq 'RedMarker'"
table_client = TableClient.from_connection_string(conn_str="<connection_string>", table_name="myTable")
entities = table_client.query_entities(my_filter)
for entity in entities:
    for key in entity.keys():
        print("Key: {}, Value: {}".format(key, entity[key]))

Optionale Konfiguration

Optionale Schlüsselwort (keyword) Argumente können auf Client- und Vorgangsebene übergeben werden. In der Azure Core-Referenzdokumentation werden verfügbare Konfigurationen für Wiederholungen, Protokollierung, Transportprotokolle und vieles mehr beschrieben.

Konfiguration der Wiederholungsrichtlinie

Verwenden Sie die folgenden Schlüsselwort (keyword) Argumente, wenn Sie einen Client instanziieren, um die Wiederholungsrichtlinie zu konfigurieren:

  • retry_total (int): Gesamtzahl der zuzulassenden Wiederholungen. Hat Vorrang vor anderen Zählungen. retry_total=0 Übergeben Sie, wenn Sie bei Anforderungen keinen Wiederholungsversuch durchführen möchten. Der Standardwert ist 10.
  • retry_connect (int): Gibt an, wie viele Verbindungsfehler wiederholt werden sollen. Der Standardwert ist 3.
  • retry_read (int): Gibt an, wie oft bei Lesefehlern wiederholt werden soll. Der Standardwert ist 3.
  • retry_status (int): Gibt an, wie oft bei fehlerhaften status Codes wiederholt werden soll. Der Standardwert ist 3.
  • retry_to_secondary (bool): Gibt an, ob die Anforderung ggf. an die sekundäre Anforderung wiederholt werden soll. Dies sollte nur aktiviert werden, wenn RA-GRS-Konten verwendet werden, und möglicherweise veraltete Daten können verarbeitet werden. Wird standardmäßig auf False festgelegt.

Andere Client-/Pro-Operation-Konfiguration

Andere optionale Konfiguration Schlüsselwort (keyword) Argumente, die auf dem Client oder pro Vorgang angegeben werden können.

Client Schlüsselwort (keyword) Argumente:

  • connection_timeout (int): Legt optional den Timeoutwert für Verbindungs- und Lesevorgänge in Sekunden fest.
  • transport (Any): Vom Benutzer bereitgestellter Transport zum Senden der HTTP-Anforderung.

Pro Vorgang Schlüsselwort (keyword) Argumente:

  • raw_response_hook (aufrufbar): Der angegebene Rückruf verwendet die vom Dienst zurückgegebene Antwort.
  • raw_request_hook (aufrufbar): Der angegebene Rückruf verwendet die Anforderung, bevor er an den Dienst gesendet wird.
  • client_request_id (str): Optionale vom Benutzer angegebene Identifizierung der Anforderung.
  • user_agent (str): Fügt den benutzerdefinierten Wert an den User-Agent-Header an, der mit der Anforderung gesendet werden soll.
  • logging_enable (bool): Aktiviert die Protokollierung auf DEBUG-Ebene. Der Standardwert lautet „False“. Kann auch auf Clientebene übergeben werden, um es für alle Anforderungen zu aktivieren.
  • headers (dict): Übergeben Sie benutzerdefinierte Header als Schlüssel- und Wertpaare. Beispiel: headers={'CustomValue': value}

Problembehandlung

Allgemein

Azure Tables-Clients lösen in Azure Core definierte Ausnahmen aus. Wenn Sie mit der Azure-Tabellenbibliothek mithilfe des Python SDK interagieren, reagieren vom Dienst zurückgegebene Fehler auf dieselben HTTP-status Codes für REST-API-Anforderungen. Die Tabellendienstvorgänge lösen bei HttpResponseError Einem Fehler einen mit hilfreichen Fehlercodes aus.

Wenn Sie beispielsweise versuchen, eine bereits vorhandene Tabelle zu erstellen, wird ein 409 Fehler zurückgegeben, der auf "Conflict" hinweist.

from azure.data.tables import TableServiceClient
from azure.core.exceptions import HttpResponseError
table_name = 'YourTableName'

service_client = TableServiceClient.from_connection_string(connection_string)

# Create the table if it does not already exist
tc = service_client.create_table_if_not_exists(table_name)

try:
    service_client.create_table(table_name)
except HttpResponseError:
    print("Table with name {} already exists".format(table_name))

Protokollierung

Diese Bibliothek verwendet die Standardprotokollbibliothek für die Protokollierung. Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf INFO-Ebene protokolliert.

Eine detaillierte Protokollierung auf DEBUG-Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf einem Client mit dem logging_enable -Argument aktiviert werden:

import sys
import logging
from azure.data.tables import TableServiceClient
# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = TableServiceClient.from_connection_string("your_connection_string", logging_enable=True)

logging_enable Auf ähnliche Weise kann die detaillierte Protokollierung für einen einzelnen Vorgang aktiviert werden, auch wenn sie für den Client nicht aktiviert ist:

service_client.create_entity(entity=my_entity, logging_enable=True)

Nächste Schritte

Erste Schritte mit unseren Tabellenbeispielen.

Im GitHub-Repository des SDK stehen Ihnen mehrere Python SDK-Beispiele für Azure Tables zur Verfügung. Diese Beispiele enthalten Beispielcode für zusätzliche Szenarien, die häufig bei der Arbeit mit Tabellen auftreten.

Häufige Szenarios

Diese Codebeispiele zeigen allgemeine Szenariovorgänge mit der Azure Tables-Clientbibliothek. Die asynchronen Versionen der Beispiele (die Python-Beispieldateien, die mit _async angefügt werden) zeigen asynchrone Vorgänge an.

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure-Tabellen finden Sie in der Dokumentation zu Azure-Tabellen auf docs.microsoft.com.

Bekannte Probleme

Eine Liste der derzeit bekannten Probleme im Zusammenhang mit Cosmos DB-Tabellenendpunkten finden Sie hier.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe