Erste Schritte mit Azure Table Storage und der Azure Cosmos DB-Tabellen-API mit PythonGet started with Azure Table storage and the Azure Cosmos DB Table API using Python

Tipp

Der Inhalt in diesem Artikel gilt für Azure-Tabellenspeicher und für die Azure Cosmos DB-Tabellen-API.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. Die Azure Cosmos DB-Tabellen-API ist ein Premiumangebot für Tabellenspeicher und bietet Tabellen mit optimiertem Durchsatz, globale Verteilung und automatische sekundäre Indizes.The Azure Cosmos DB Table API is a premium offering for table storage that offers throughput-optimized tables, global distribution, and automatic secondary indexes.

Azure Table Storage und Azure Cosmos DB sind Dienste, die strukturierte NoSQL-Daten in der Cloud speichern und einen Schlüssel-/Attributspeicher mit einem schemalosen Design bieten.Azure Table storage and Azure Cosmos DB are services that store structured NoSQL data in the cloud, providing a key/attribute store with a schemaless design. Aufgrund der Schemalosigkeit von Table Storage und Azure Cosmos DB ist es einfach, Ihre Daten an die Entwicklung Ihrer Anwendungen anzupassen.Because Table storage and Azure Cosmos DB are schemaless, it's easy to adapt your data as the needs of your application evolve. Viele Arten von Anwendungen können schnell und kostengünstig auf Table Storage- und Tabellen-API-Daten zugreifen, und die Kosten liegen in der Regel unter den Kosten herkömmlicher SQL-Lösungen für vergleichbare Datenmengen.Access to Table storage and Table API data is fast and cost-effective for many types of applications, and is typically lower in cost than traditional SQL for similar volumes of data.

Mit Table Storage oder Azure Cosmos DB können Sie flexible Datasets wie Benutzerdaten für Webanwendungen, Adressbücher, Geräteinformationen und andere Arten von Metadaten speichern, die Ihr Dienst benötigt.You can use Table storage or Azure Cosmos DB to store flexible datasets like user data for web applications, address books, device information, or other types of metadata your service requires. Sie können eine beliebige Anzahl von Entitäten in einer Tabelle speichern, und ein Speicherkonto kann eine beliebige Anzahl von Tabellen enthalten (bis zur Speicherkapazitätsgrenze eines Speicherkontos).You can store any number of entities in a table, and a storage account may contain any number of tables, up to the capacity limit of the storage account.

Informationen zu diesem BeispielAbout this sample

In diesem Beispiel erfahren Sie, wie Sie das Azure Cosmos DB Table SDK für Python in allgemeinen Azure Table Storage-Szenarien verwenden.This sample shows you how to use the Azure Cosmos DB Table SDK for Python in common Azure Table storage scenarios. Der Name des SDK weist darauf hin, dass es für Azure Cosmos DB gedacht ist. Es kann aber sowohl mit Azure Cosmos DB als auch mit Azure Table Storage verwendet werden, jeder Dienst hat lediglich einen eindeutigen Endpunkt.The name of the SDK indicates it is for use with Azure Cosmos DB, but it works with both Azure Cosmos DB and Azure Tables storage, each service just has a unique endpoint. Diese Szenarien werden mithilfe von Python-Beispielen untersucht, die Folgendes veranschaulichen:These scenarios are explored using Python examples that illustrate how to:

  • Erstellen und Löschen von TabellenCreate and delete tables
  • Einfügen und Abfragen von EntitätenInsert and query entities
  • Ändern von EntitätenModify entities

Beim Durcharbeiten der Szenarien in diesem Beispiel finden Sie bei Bedarf weiterführende Informationen in der API-Referenz zum Azure Cosmos DB SDK für Python.While working through the scenarios in this sample, you may want to refer to the Azure Cosmos DB SDK for Python API reference.

VoraussetzungenPrerequisites

Für dieses Beispiel benötigen Sie Folgendes:You need the following to complete this sample successfully:

Erstellen eines Azure-DienstkontosCreate an Azure service account

Sie können in Azure Table Storage oder in Azure Cosmos DB mit Tabellen arbeiten.You can work with tables using Azure Table storage or Azure Cosmos DB. Informationen zu den Unterschieden zwischen den Diensten finden Sie unter Tabellenangebote.To learn more about the differences between the services, see Table offerings. Sie müssen ein Konto für den Dienst erstellen, den Sie verwenden werden.You'll need to create an account for the service you're going to use.

Erstellen eines Azure-SpeicherkontosCreate an Azure storage account

Ein Azure-Speicherkonto erstellen Sie am einfachsten im Azure-Portal.The easiest way to create an Azure storage account is by using the Azure portal. Weitere Informationen finden Sie unter Erstellen von Speicherkonten.To learn more, see Create a storage account.

Sie können ein Azure-Speicherkonto auch mit Azure PowerShell oder mit der Azure CLI erstellen.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Wenn Sie zu diesem Zeitpunkt kein Speicherkonto erstellen möchten, können Sie auch den Azure-Speicheremulator zum Ausführen und Testen Ihres Codes in einer lokalen Umgebung verwenden.If you prefer not to create a storage account at this time, you can also use the Azure storage emulator to run and test your code in a local environment. Weitere Informationen finden Sie unter Einsatz des Azure-Speicheremulators für Entwicklung und Tests.For more information, see Use the Azure storage emulator for development and testing.

Erstellen eines Kontos für die Azure Cosmos DB-Tabellen-APICreate an Azure Cosmos DB Table API account

Anweisungen zum Erstellen eines Kontos für die Azure Cosmos DB-Tabellen-API finden Sie unter Schnellstart: Erstellen einer Tabellen-API-App per .NET SDK und Azure Cosmos DB.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Installieren des Azure Cosmos DB Table SDK für PythonInstall the Azure Cosmos DB Table SDK for Python

Nach dem Erstellen eines Speicherkontos installieren Sie im nächsten Schritt das Microsoft Azure Cosmos DB Table SDK für Python.After you've created a Storage account, your next step is to install the Microsoft Azure Cosmos DB Table SDK for Python. Ausführliche Informationen zum Installieren des SDK finden Sie in der Datei README.rst im Repository für das Cosmos DB Table SDK für Python auf GitHub.For details on installing the SDK, refer to the README.rst file in the Cosmos DB Table SDK for Python repository on GitHub.

Importieren der TableService- und der Entity-KlasseImport the TableService and Entity classes

Nutzen Sie zur Verwendung von Entitäten im Azure-Tabellenspeicherdienst in Python die Klassen TableService und Entity.To work with entities in the Azure Table service in Python, you use the TableService and Entity classes. Fügen Sie folgenden Code am Anfang der Python-Datei ein, um beide zu importieren:Add this code near the top your Python file to import both:

from azure.cosmosdb.table.tableservice import TableService
from azure.cosmosdb.table.models import Entity

Herstellen der Verbindung mit dem Azure-TabellenspeicherdienstConnect to Azure Table service

Um eine Verbindung mit dem Azure Storage Table-Dienst herzustellen, erstellen Sie ein TableService-Objekt und übergeben den Speicherkontonamen und den Kontoschlüssel.To connect to Azure Storage Table service, create a TableService object, and pass in your Storage account name and account key. Ersetzen Sie myaccount und mykey durch Ihren Kontonamen und Schlüssel.Replace myaccount and mykey with your account name and key.

table_service = TableService(account_name='myaccount', account_key='mykey')

Herstellen der Verbindung mit Azure Cosmos DBConnect to Azure Cosmos DB

Wenn Sie eine Verbindung mit Azure Cosmos DB herstellen möchten, kopieren Sie die primäre Verbindungszeichenfolge aus dem Azure-Portal und erstellen mithilfe der kopierten Verbindungszeichenfolge ein TableService-Objekt:To connect to Azure Cosmos DB, copy your primary connection string from the Azure portal, and create a TableService object using your copied connection string:

table_service = TableService(connection_string='DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;TableEndpoint=myendpoint;')

Erstellen einer TabelleCreate a table

Rufen Sie zum Erstellen der Tabelle create_table auf.Call create_table to create the table.

table_service.create_table('tasktable')

Hinzufügen einer Entität zu einer TabelleAdd an entity to a table

Zum Hinzufügen einer Entität erstellen Sie zunächst ein Objekt, das die Entität darstellt, und übergeben das Objekt dann an die Methode TableService.insert_entity.To add an entity, you first create an object that represents your entity, then pass the object to the TableService.insert_entity method. Das Entitätsobjekt kann ein Wörterbuch oder ein Objekt des Typs Entity sein und definiert die Eigenschaftennamen und Eigenschaftswerte der Entität.The entity object can be a dictionary or an object of type Entity, and defines your entity's property names and values. Jede Entität muss neben allen anderen Eigenschaften, die Sie für die Entität definieren, die erforderlichen Eigenschaften PartitionKey und RowKey enthalten.Every entity must include the required PartitionKey and RowKey properties, in addition to any other properties you define for the entity.

In diesem Beispiel wird ein Wörterbuchobjekt erstellt, das eine Entität darstellt, und dann an die insert_entity-Methode übergeben, sodass es der Tabelle hinzugefügt wird:This example creates a dictionary object representing an entity, then passes it to the insert_entity method to add it to the table:

task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the trash', 'priority': 200}
table_service.insert_entity('tasktable', task)

In diesem Beispiel wird ein Entity-Objekt erstellt und dann an die insert_entity-Methode übergeben, sodass es der Tabelle hinzugefügt wird:This example creates an Entity object, then passes it to the insert_entity method to add it to the table:

task = Entity()
task.PartitionKey = 'tasksSeattle'
task.RowKey = '002'
task.description = 'Wash the car'
task.priority = 100
table_service.insert_entity('tasktable', task)

PartitionKey und RowKeyPartitionKey and RowKey

Sie müssen für jede Entität eine PartitionKey- und eine RowKey-Eigenschaft angeben.You must specify both a PartitionKey and a RowKey property for every entity. Diese bilden zusammen den Primärschlüssel einer Entität und sind daher die eindeutigen Bezeichner der Entitäten.These are the unique identifiers of your entities, as together they form the primary key of an entity. Diese Werte können sehr viel schneller abgefragt werden als alle anderen Entitätseigenschaften, da nur diese Werte indiziert sind.You can query using these values much faster than you can query any other entity properties because only these properties are indexed.

Der Tabellendienst verwendet PartitionKey für die intelligente Verteilung von Tabellenentitäten auf Speicherknoten.The Table service uses PartitionKey to intelligently distribute table entities across storage nodes. Entitäten mit dem gleichen PartitionKey werden auf dem gleichen Knoten gespeichert.Entities that have the same PartitionKey are stored on the same node. RowKey ist eine eindeutige ID der Entität in der Partition, zu der sie gehört.RowKey is the unique ID of the entity within the partition it belongs to.

Aktualisieren einer EntitätUpdate an entity

Rufen Sie zum Aktualisieren aller Eigenschaftswerte einer Entität die update_entity-Methode auf.To update all of an entity's property values, call the update_entity method. In diesem Beispiel wird gezeigt, wie eine vorhandene Entität durch eine aktualisierte Version ersetzt wird:This example shows how to replace an existing entity with an updated version:

task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the garbage', 'priority': 250}
table_service.update_entity('tasktable', task)

Beim Aktualisierungsvorgang tritt ein Fehler auf, wenn die zu aktualisierende Entität nicht bereits vorhanden ist.If the entity that is being updated doesn't already exist, then the update operation will fail. Verwenden Sie insert_or_replace_entity, wenn Sie eine Entität unabhängig davon speichern möchten, ob sie bereits vorhanden ist.If you want to store an entity whether it exists or not, use insert_or_replace_entity. Der erste Aufruf im folgenden Beispiel ersetzt die existierende Entität.In the following example, the first call will replace the existing entity. Der zweite Aufruf fügt eine neue Entität ein, da keine Entität mit dem angegebenen PartitionKey und RowKey in der Tabelle vorhanden ist.The second call will insert a new entity, since no entity with the specified PartitionKey and RowKey exists in the table.

# Replace the entity created earlier
task = {'PartitionKey': 'tasksSeattle', 'RowKey': '001',
        'description': 'Take out the garbage again', 'priority': 250}
table_service.insert_or_replace_entity('tasktable', task)

# Insert a new entity
task = {'PartitionKey': 'tasksSeattle', 'RowKey': '003',
        'description': 'Buy detergent', 'priority': 300}
table_service.insert_or_replace_entity('tasktable', task)

Tipp

Mit der update_entity-Methode werden alle Eigenschaften und Werte einer vorhandenen Entität ersetzt. Zudem können Sie mit dieser Methode auch Eigenschaften aus einer vorhandenen Entität entfernen.The update_entity method replaces all properties and values of an existing entity, which you can also use to remove properties from an existing entity. Mit der merge_entity-Methode können Sie eine vorhandene Entität mit neuen oder geänderten Eigenschaftswerten aktualisieren, ohne die Entität vollständig ersetzen zu müssen.You can use the merge_entity method to update an existing entity with new or modified property values without completely replacing the entity.

Ändern mehrerer EntitätenModify multiple entities

Um die unteilbare Verarbeitung einer Anforderung durch den Tabellendienst sicherzustellen, können Sie mehrere Vorgänge zusammen in einem Batch senden.To ensure the atomic processing of a request by the Table service, you can submit multiple operations together in a batch. Verwenden Sie zunächst die TableBatch-Klasse, um einem einzelnen Batch mehrere Vorgänge hinzuzufügen.First, use the TableBatch class to add multiple operations to a single batch. Rufen Sie anschließend TableService.commit_batch auf, um die Vorgänge in einem unteilbaren Vorgang zu übermitteln.Next, call TableService.commit_batch to submit the operations in an atomic operation. Alle als Batch zu ändernden Entitäten müssen sich auf derselben Partition befinden.All entities to be modified in batch must be in the same partition.

In diesem Beispiel werden zwei Entitäten als Batch hinzugefügt:This example adds two entities together in a batch:

from azure.cosmosdb.table.tablebatch import TableBatch
batch = TableBatch()
task004 = {'PartitionKey': 'tasksSeattle', 'RowKey': '004',
           'description': 'Go grocery shopping', 'priority': 400}
task005 = {'PartitionKey': 'tasksSeattle', 'RowKey': '005',
           'description': 'Clean the bathroom', 'priority': 100}
batch.insert_entity(task004)
batch.insert_entity(task005)
table_service.commit_batch('tasktable', batch)

Batches können auch mit der Kontext-Manager-Syntax verwendet werden:Batches can also be used with the context manager syntax:

task006 = {'PartitionKey': 'tasksSeattle', 'RowKey': '006',
           'description': 'Go grocery shopping', 'priority': 400}
task007 = {'PartitionKey': 'tasksSeattle', 'RowKey': '007',
           'description': 'Clean the bathroom', 'priority': 100}

with table_service.batch('tasktable') as batch:
    batch.insert_entity(task006)
    batch.insert_entity(task007)

Abfragen einer EntitätQuery for an entity

Zum Abfragen einer Entität in einer Tabelle übergeben Sie die zugehörigen PartitionKey- und RowKey-Elemente an die TableService.get_entity-Methode.To query for an entity in a table, pass its PartitionKey and RowKey to the TableService.get_entity method.

task = table_service.get_entity('tasktable', 'tasksSeattle', '001')
print(task.description)
print(task.priority)

Abfragen einer Gruppe von EntitätenQuery a set of entities

Eine Gruppe von Entitäten können Sie abfragen, indem Sie mit dem filter-Parameter eine Filterzeichenfolge angeben.You can query for a set of entities by supplying a filter string with the filter parameter. In diesem Beispiel werden durch Anwenden eines Filters für PartitionKey alle Aufgaben in Seattle abgefragt:This example finds all tasks in Seattle by applying a filter on PartitionKey:

tasks = table_service.query_entities(
    'tasktable', filter="PartitionKey eq 'tasksSeattle'")
for task in tasks:
    print(task.description)
    print(task.priority)

Abfragen einer Teilmenge von EntitätseigenschaftenQuery a subset of entity properties

Es ist auch möglich, die Eigenschaften einzuschränken, die für jede Entität in einer Abfrage zurückgegeben werden.You can also restrict which properties are returned for each entity in a query. Bei dieser Methode, der sogenannten Projektion, wird die Bandbreite reduziert und die Abfrageleistung kann gesteigert werden, vor allem bei großen Entitäten oder Resultsets.This technique, called projection, reduces bandwidth and can improve query performance, especially for large entities or result sets. Verwenden Sie den select-Parameter, und übergeben Sie die Namen der Eigenschaften, die an den Client zurückgegeben werden sollen.Use the select parameter and pass the names of the properties you want returned to the client.

Mit der Abfrage im folgenden Code werden nur die Beschreibungen von Entitäten in der Tabelle zurückgegeben.The query in the following code returns only the descriptions of entities in the table.

Hinweis

Der folgende Codeausschnitt funktioniert nur mit Azure Storage.The following snippet works only against the Azure Storage. Er wird nicht vom Speicheremulator unterstützt.It is not supported by the storage emulator.

tasks = table_service.query_entities(
    'tasktable', filter="PartitionKey eq 'tasksSeattle'", select='description')
for task in tasks:
    print(task.description)

Löschen einer EntitätDelete an entity

Eine Entität können Sie löschen, indem Sie die zugehörigen PartitionKey- und RowKey-Elemente an die delete_entity-Methode übergeben.Delete an entity by passing its PartitionKey and RowKey to the delete_entity method.

table_service.delete_entity('tasktable', 'tasksSeattle', '001')

Löschen einer TabelleDelete a table

Wenn Sie eine Tabelle und die Entitäten darin nicht mehr benötigen, können Sie die delete_table-Methode aufrufen, um die Tabelle endgültig aus Azure Storage zu löschen.If you no longer need a table or any of the entities within it, call the delete_table method to permanently delete the table from Azure Storage.

table_service.delete_table('tasktable')

Nächste SchritteNext steps