Rozpoczynanie pracy z usługą Azure Table Storage oraz interfejsem API tabel usługi Azure Cosmos DB przy użyciu języka PythonGet started with Azure Table storage and the Azure Cosmos DB Table API using Python

Porada

Zawartość tego artykułu dotyczy magazynu tabel Azure i interfejsu API tabeli w usłudze Azure Cosmos DB.The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. Interfejs API tabeli w usłudze Azure Cosmos DB jest ofertą Premium służącą do przechowywania tabel, która zapewnia tabele zoptymalizowane pod kątem przepływności, ich globalną dystrybucję i automatyczne indeksy pomocnicze.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 i Azure Cosmos DB to usługi umożliwiające przechowywanie danych NoSQL ze strukturą w chmurze, udostępniając magazyn par klucz-atrybut z projektem bez schematu.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. Ponieważ usługi Table Storage i Azure Cosmos DB nie mają schematu, można łatwo dostosować dane do zmieniających się potrzeb aplikacji.Because Table storage and Azure Cosmos DB are schemaless, it's easy to adapt your data as the needs of your application evolve. W przypadku wielu typów aplikacji dostęp do danych w usłudze Table Storage i interfejsie API tabel jest szybki i ekonomiczny, jest też zazwyczaj tańszy od tradycyjnego rozwiązania SQL dla podobnych ilości danych.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.

Usługi Table Storage i Azure Cosmos DB umożliwiają przechowywanie elastycznych zestawów danych, takich jak dane użytkowników aplikacji internetowych, książki adresowe, informacje o urządzeniach i inne typy metadanych, których wymaga Twoja usługa.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. W tabeli można przechowywać dowolną liczbę jednostek, a konto magazynu może zawierać dowolną liczbę tabel w granicach pojemności konta magazynu.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.

Informacje o tym przykładzieAbout this sample

Ten przykład pokazuje, jak zastosować zestaw SDK tabel usługi Azure Cosmos DB dla języka Python w kilku typowych scenariuszach związanych z usługą Azure Table Storage.This sample shows you how to use the Azure Cosmos DB Table SDK for Python in common Azure Table storage scenarios. Nazwa zestawu SDK wskazuje, że powinien być używany z usługą Azure Cosmos DB, ale działa zarówno z usługą Azure Cosmos DB, jak i z usługą Azure Table Storage. Każda z nich ma po prostu unikatowy punkt końcowy.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. Scenariusze są tu przedstawione za pomocą przykładów w języku Python, które ilustrują sposób wykonywania następujących czynności:These scenarios are explored using Python examples that illustrate how to:

  • Tworzenie i usuwanie tabelCreate and delete tables
  • Wstawianie jednostek i wykonywanie zapytańInsert and query entities
  • Modyfikowanie jednostekModify entities

Podczas pracy ze scenariuszami w tym przykładzie może być przydatna dokumentacja interfejsu API zestawu SDK usługi Azure Cosmos DB dla języka Python.While working through the scenarios in this sample, you may want to refer to the Azure Cosmos DB SDK for Python API reference.

Wymagania wstępnePrerequisites

Do pomyślnego ukończenia pracy z przykładem wymagane są następujące elementy:You need the following to complete this sample successfully:

Tworzenie konta usługi AzureCreate an Azure service account

Do pracy z tabelami można używać usługi Azure Table Storage lub Azure Cosmos DB.You can work with tables using Azure Table storage or Azure Cosmos DB. Aby dowiedzieć się więcej o różnicach między usługami, zobacz temat oferty tabeli.To learn more about the differences between the services, see Table offerings. Aby móc korzystać z wybranej usługi, musisz w niej utworzyć konto.You'll need to create an account for the service you're going to use.

Tworzenie konta usługi Azure StorageCreate an Azure storage account

Najprostszym sposobem utworzenia konta magazynu platformy Azure jest użycie witryny Azure portal.The easiest way to create an Azure storage account is by using the Azure portal. Więcej informacji można znaleźć w temacie Tworzenie konta magazynu.To learn more, see Create a storage account.

Możesz utworzyć konto usługi Azure Storage przy użyciu programu Azure PowerShell lub interfejsu wiersza polecenia platformy Azure.You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

Jeśli nie chcesz teraz tworzyć konta magazynu, możesz także użyć emulatora usługi Azure Storage do uruchomienia i testowania kodu w środowisku lokalnym.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. Aby uzyskać więcej informacji, zobacz Używanie emulatora magazynu platformy Azure do tworzenia i testowania.For more information, see Use the Azure storage emulator for development and testing.

Tworzenie konta interfejsu API tabel usługi Azure Cosmos DBCreate an Azure Cosmos DB Table API account

Aby uzyskać instrukcje dotyczące tworzenia konta interfejsu API tabeli usługi Azure Cosmos DB, zobacz Tworzenie konta bazy danych.For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Instalowanie zestawu SDK tabel usługi Azure Cosmos DB dla języka PythonInstall the Azure Cosmos DB Table SDK for Python

Po utworzeniu konta usługi Azure Storage następnym krokiem jest zainstalowanie zestawu SDK tabel usługi Microsoft Azure Cosmos DB dla języka Python.After you've created a Storage account, your next step is to install the Microsoft Azure Cosmos DB Table SDK for Python. Aby uzyskać więcej informacji na temat instalowania zestawu SDK, zapoznaj się z plikiem README.rst w repozytorium zestawu SDK usługi Azure Cosmos DB dla języka Python w witrynie GitHub.For details on installing the SDK, refer to the README.rst file in the Cosmos DB Table SDK for Python repository on GitHub.

Importowanie klas TableService i EntityImport the TableService and Entity classes

W języku Python do pracy z jednostkami w usłudze Azure Table Storage są używane klasy TableService i Entity.To work with entities in the Azure Table service in Python, you use the TableService and Entity classes. Dodaj następujący kod na początku pliku Python, aby zaimportować obie te klasy: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

Łączenie się z usługą Azure Table StorageConnect to Azure Table service

Aby nawiązać połączenie z usługą Azure Table Storage, utwórz obiekt TableService i przekaż nazwę konta oraz klucz konta usługi Azure Storage.To connect to Azure Storage Table service, create a TableService object, and pass in your Storage account name and account key. Zastąp wartości myaccount i mykey nazwą i kluczem konta.Replace myaccount and mykey with your account name and key.

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

Łączenie z usługą Azure Cosmos DBConnect to Azure Cosmos DB

Aby nawiązać połączenie z usługą Azure Cosmos DB, skopiuj podstawowe parametry połączenia z witryny Azure Portal, a następnie użyj ich, aby utworzyć obiekt TableService: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;')

Tworzenie tabeliCreate a table

Wywołaj metodęcreate_table, aby utworzyć tabelę.Call create_table to create the table.

table_service.create_table('tasktable')

Dodawanie jednostki do tabeliAdd an entity to a table

Aby dodać jednostkę, musisz najpierw utworzyć obiekt, który reprezentuje jednostkę, a następnie przekazać ten obiekt do metody 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. Obiekt jednostki może być słownikiem lub obiektem typu Entity. Definiuje on nazwy i wartości właściwości jednostki.The entity object can be a dictionary or an object of type Entity, and defines your entity's property names and values. Każda jednostka musi zawierać wymagane właściwości PartitionKey i RowKey, oprócz innych właściwości zdefiniowanych dla jednostki.Every entity must include the required PartitionKey and RowKey properties, in addition to any other properties you define for the entity.

W tym przykładzie tworzony jest obiekt słownika reprezentujący jednostkę, który jest następnie przekazywany do metody insert_entity w celu dodania jednostki do tabeli: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)

W tym przykładzie tworzony jest obiekt Entity, który następnie jest przekazywany do metody insert_entity w celu dodania jednostki do tabeli: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)

Właściwości PartitionKey i RowKeyPartitionKey and RowKey

Należy pamiętać, że dla każdej jednostki konieczne jest określenie właściwości PartitionKey i RowKey.You must specify both a PartitionKey and a RowKey property for every entity. Są to unikatowe identyfikatory jednostek, które wspólnie tworzą klucz podstawowy jednostki.These are the unique identifiers of your entities, as together they form the primary key of an entity. Zapytania dotyczące tych wartości są wykonywane znacznie szybciej niż zapytania dotyczące innych właściwości jednostki, ponieważ tylko te właściwości są indeksowane.You can query using these values much faster than you can query any other entity properties because only these properties are indexed.

W usłudze Table Storage właściwość PartitionKey jest używana do inteligentnego rozłożenia jednostki tabeli pomiędzy węzłami magazynu.The Table service uses PartitionKey to intelligently distribute table entities across storage nodes. Obiekty z taką samą wartością PartitionKey są przechowywane w tym samym węźle.Entities that have the same PartitionKey are stored on the same node. Właściwość RowKey to unikatowy identyfikator jednostki w ramach partycji, do której należy.RowKey is the unique ID of the entity within the partition it belongs to.

Aktualizowanie jednostkiUpdate an entity

Aby zaktualizować wszystkie wartości właściwości jednostki, należy wywołać metodę update_entity.To update all of an entity's property values, call the update_entity method. W tym przykładzie pokazano, jak zastąpić istniejącą jednostkę zaktualizowaną wersją: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)

Jeśli aktualizowana jednostka jeszcze nie istnieje, to aktualizacja zakończy się niepowodzeniem.If the entity that is being updated doesn't already exist, then the update operation will fail. Jeśli chcesz zapisać jednostkę bez względu na to, czy istnieje czy nie, użyj metody insert_or_replace_entity.If you want to store an entity whether it exists or not, use insert_or_replace_entity. W poniższym przykładzie pierwsze wywołanie spowoduje zastąpienie istniejącej jednostki.In the following example, the first call will replace the existing entity. Drugie wywołanie spowoduje wstawienie nowej jednostki, ponieważ w tabeli nie istnieje żadna jednostka z podanymi wartościami PartitionKey i RowKey.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)

Porada

Metoda Update_entity zastępuje wszystkie właściwości i wartości istniejącej jednostki. Umożliwia także usunięcie właściwości z istniejącej jednostki.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. Możesz użyć metody merge_entity, aby zaktualizować istniejącą jednostkę przy użyciu nowych lub zmodyfikowanych wartości właściwości, bez całkowitego zastępowania jednostki.You can use the merge_entity method to update an existing entity with new or modified property values without completely replacing the entity.

Modyfikowanie wielu jednostekModify multiple entities

Aby zapewnić niepodzielne przetwarzanie żądania przez usługę Table Storage, warto przesłać jednocześnie wiele operacji w partii.To ensure the atomic processing of a request by the Table service, you can submit multiple operations together in a batch. Najpierw należy użyć klasy TableBatch, aby dodać wiele operacji do jednej partii.First, use the TableBatch class to add multiple operations to a single batch. Następnie należy wywołać metodę TableService. commit_batch, aby przesłać niepodzielną partię operacji.Next, call TableService.commit_batch to submit the operations in an atomic operation. Wszystkie jednostki, które mają być zmodyfikowane w ramach partii, muszą należeć do tej samej partycji.All entities to be modified in batch must be in the same partition.

W tym przykładzie dodano dwie jednostki do partii: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)

Partii można również użyć, korzystając ze składni menedżera kontekstu: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)

Wykonywanie zapytania względem jednostkiQuery for an entity

Aby wykonać zapytanie dotyczące jednostki w tabeli, przekaż wartości PartitionKey i RowKey do metody TableService.get_entity.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)

Wykonywanie zapytania względem zestawu jednostekQuery a set of entities

Możesz wykonać zapytanie dotyczące zestawu jednostek, podając ciąg filtru przy użyciu parametru filter.You can query for a set of entities by supplying a filter string with the filter parameter. W tym przykładzie znalezione zostaną wszystkie zadania w lokalizacji Seattle przy użyciu filtru wartości PartitionKey: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)

Tworzenie zapytania do podzbioru właściwości jednostkiQuery a subset of entity properties

Możesz również ograniczyć zestaw właściwości zwracanych dla każdej jednostki w zapytaniu.You can also restrict which properties are returned for each entity in a query. Ta technika, zwana projekcją, zmniejsza użycie przepustowości i może poprawiać wydajność zapytań, zwłaszcza w przypadku dużych jednostek lub zestawów wyników.This technique, called projection, reduces bandwidth and can improve query performance, especially for large entities or result sets. Użyj parametru select i wprowadź nazwy właściwości, które chcesz zwrócić do klienta.Use the select parameter and pass the names of the properties you want returned to the client.

Zapytanie w poniższym kodzie zwraca wyłącznie opisy jednostek w tabeli.The query in the following code returns only the descriptions of entities in the table.

Uwaga

Poniższy fragment kodu działa tylko w usłudze Azure Storage.The following snippet works only against the Azure Storage. Nie jest obsługiwany przez emulator usługi Azure Storage.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)

Usuwanie jednostkiDelete an entity

Aby usunąć jednostkę, przekaż jej wartości PartitionKey i RowKey do metody delete_entity.Delete an entity by passing its PartitionKey and RowKey to the delete_entity method.

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

Usuwanie tabeliDelete a table

Jeśli nie potrzebujesz już tabeli ani żadnych jednostek, które się w niej znajdują, wywołaj metodę delete_table, aby trwale usunąć tabelę z usługi Azure Storage.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')

Następne krokiNext steps