Python を使用して Azure Table Storage と Azure Cosmos DB Table API を使用するGet started with Azure Table storage and the Azure Cosmos DB Table API using Python

適用対象: Table API

ヒント

この記事の内容の適用対象は、Azure Table Storage および Azure Cosmos DB Table API です。The content in this article applies to Azure Table storage and the Azure Cosmos DB Table API. Azure Cosmos DB Table API は、スループット最適化テーブル、グローバル配布、自動セカンダリ インデックスを提供する Table Storage 用の Premium オファーです。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 と Azure Cosmos DB は、NoSQL の構造化データをクラウド内に格納するサービスです。スキーマレスのデザインでキー/属性ストアを実現します。The Azure Table storage and the Azure Cosmos DB are services that store structured NoSQL data in the cloud, providing a key/attribute store with a schemaless design. Table Storage と Azure Cosmos DB はスキーマがないため、アプリケーションの進化のニーズに合わせてデータを容易に修正できます。Because Table storage and Azure Cosmos DB are schemaless, it's easy to adapt your data as the needs of your application evolve. Table Storage と Table API のデータへのアクセスは、多くの種類のアプリケーションにとって高速でコスト効率に優れ、また一般に、ほぼ同じ容量のデータの場合、従来の SQL と比較して低コストです。Access to the 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.

Table Storage または Azure Cosmos DB を使用すると、Web アプリケーションのユーザー データ、アドレス帳、デバイス情報、サービスに必要なその他の種類のメタデータなど、柔軟なデータセットを格納できます。You can use the Table storage or the 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. ストレージ アカウントの容量の上限を超えない限り、テーブルには任意の数のエンティティを保存でき、ストレージ アカウントには任意の数のテーブルを含めることができます。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.

このサンプルについてAbout this sample

このサンプルでは、Azure Table Storage の一般的な用途における Azure Cosmos DB Table SDK for Python の使い方について説明します。This sample shows you how to use the Azure Cosmos DB Table SDK for Python in common Azure Table storage scenarios. SDK の名前は、Azure Cosmos DB で使うことを示していますが、パッケージは Azure Cosmos DB と Azure Tables ストレージの両方に使うことができます。また、各サービスは一意のエンドポイントを持っています。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. 次の方法を示す Python の例を使って、これらのシナリオについて説明します。These scenarios are explored using Python examples that illustrate how to:

  • テーブルの作成と削除Create and delete tables
  • エンティティの挿入とクエリInsert and query entities
  • エンティティの変更Modify entities

このサンプルでシナリオに従って作業するときに、Azure Cosmos DB SDK for Python API のリファレンスを参照できます。While working through the scenarios in this sample, you may want to refer to the Azure Cosmos DB SDK for Python API reference.

前提条件Prerequisites

このサンプルの作業を行うためには、次のものが必要になります。You need the following to complete this sample successfully:

Azure サービス アカウントを作成するCreate an Azure service account

Azure Table ストレージまたは Azure Cosmos DB を使用してテーブルを操作できます。You can work with tables using the Azure Table storage or the Azure Cosmos DB. これらの 2 つのサービスのテーブル サービスの違いの詳細については、Table のサービスに関する記事をご覧ください。To learn more about the differences between table offerings in these two services, see the Table offerings article. 使用するサービスのアカウントを作成する必要があります。You'll need to create an account for the service you're going to use. 以下のセクションでは、Azure Table ストレージと Azure Cosmos DB アカウントの両方を作成する方法について説明しますが、そのうちの 1 つのみを使用できます。The following sections show how to create both Azure Table storage and the Azure Cosmos DB account, however you can just use one of them.

Azure Storage アカウントを作成するCreate an Azure storage account

Azure ストレージ アカウントを作成する最も簡単な方法は、Azure portal を利用することです。The easiest way to create an Azure storage account is by using the Azure portal. 詳細については、「 ストレージ アカウントの作成」を参照してください。To learn more, see Create a storage account.

Azure PowerShell または Azure CLI を使って、Azure Storage アカウントを作成することもできます。You can also create an Azure storage account by using Azure PowerShell or Azure CLI.

現時点でストレージ アカウントを作成しない場合は、Azure Storage エミュレーターを使って、ローカル環境でコードの実行とテストを行うこともできます。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. 詳細については、「開発とテストのための Azure のストレージ エミュレーター使用」を参照してください。For more information, see Use the Azure Storage Emulator for development and testing.

Azure Cosmos DB Table API アカウントを作成するCreate an Azure Cosmos DB Table API account

Azure Cosmos DB Table API アカウントの作成手順については、「データベース アカウントの作成」を参照してください。For instructions on creating an Azure Cosmos DB Table API account, see Create a database account.

Azure Cosmos DB Table SDK for Python をインストールするInstall the Azure Cosmos DB Table SDK for Python

Storage アカウントを作成した後は、Microsoft Azure Cosmos DB Table SDK for Python をインストールします。After you've created a Storage account, your next step is to install the Microsoft Azure Cosmos DB Table SDK for Python. SDK のインストールについて詳しくは、GitHub の Cosmos DB Table SDK for Python リポジトリ内の README.rst をご覧ください。For details on installing the SDK, refer to the README.rst file in the Cosmos DB Table SDK for Python repository on GitHub.

TableService クラスと Entity クラスをインポートするImport the TableService and Entity classes

Python で Azure Table service のエンティティを扱うには、TableServiceEntity クラスを使います。To work with entities in the Azure Table service in Python, you use the TableService and Entity classes. 次のコードを Python ファイルの先頭付近に追加して、両方をインポートします。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

Azure Table service に接続するConnect to Azure Table service

Azure Storage Table service に接続するには、TableService オブジェクトを作成し、お使いの Storage アカウントの名前とアカウント キーを渡します。To connect to Azure Storage Table service, create a TableService object, and pass in your Storage account name and account key. myaccountmykey をアカウント名とキーに置き換えます。Replace myaccount and mykey with your account name and key.

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

Azure Cosmos DB への接続Connect to Azure Cosmos DB

Azure Cosmos DB に接続するには、Azure Portal からプライマリ接続文字列をコピーし、コピーした接続文字列を使って 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;')

テーブルを作成するCreate a table

テーブルを作成するには、create_table を呼び出します。Call create_table to create the table.

table_service.create_table('tasktable')

エンティティをテーブルに追加するAdd an entity to a table

エンティティを追加するには、最初にエンティティを表すオブジェクトを作成してから、そのオブジェクトを 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. エンティティ オブジェクトには、ディクショナリまたは Entity 型のオブジェクトが可能で、エンティティのプロパティの名前と値を定義します。The entity object can be a dictionary or an object of type Entity, and defines your entity's property names and values. エンティティに定義するその他のプロパティの他に、すべてのエンティティに必須の PartitionKey と RowKey のプロパティを含める必要があります。Every entity must include the required PartitionKey and RowKey properties, in addition to any other properties you define for the entity.

この例では、エンティティを表すディクショナリ オブジェクトを作成し、それを insert_entity メソッドに渡してテーブルに追加します。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)

この例では、Entity オブジェクトを作成し、それを insert_entity メソッドに渡してテーブルに追加します。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 と RowKeyPartitionKey and RowKey

すべてのエンティティに PartitionKeyRowKey を指定する必要があります。You must specify both a PartitionKey and a RowKey property for every entity. これらは共にエンティティのプライマリ キーを形成するため、エンティティの一意の識別子です。These are the unique identifiers of your entities, as together they form the primary key of an entity. これらのプロパティのみがインデックス付けされているため、これらの値を使用すると、他のエンティティのプロパティでクエリを実行するよりもずっと高速にクエリを実行できます。You can query using these values much faster than you can query any other entity properties because only these properties are indexed.

Table service は PartitionKey を使用してインテリジェントにテーブル エンティティをストレージ ノード全体に分散させます。The Table service uses PartitionKey to intelligently distribute table entities across storage nodes. PartitionKey が同じエンティティは同じノードに格納されます。Entities that have the same PartitionKey are stored on the same node. RowKey は、エンティティが属するパーティション内のエンティティの一意の ID です。RowKey is the unique ID of the entity within the partition it belongs to.

エンティティを更新するUpdate an entity

エンティティのプロパティの値をすべて更新するには、update_entity メソッドを呼び出します。To update all of an entity's property values, call the update_entity method. この例は、既存のエンティティを更新されたバージョンに置き換える方法を示しています。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)

更新されるエンティティが存在しない場合、更新操作は失敗します。If the entity that is being updated doesn't already exist, then the update operation will fail. エンティティが存在するかどうかにかかわらず、エンティティを格納する場合は、insert_or_replace_entity を使用します。If you want to store an entity whether it exists or not, use insert_or_replace_entity. 次の例では、最初の呼び出しで既存のエンティティを置き換えます。In the following example, the first call will replace the existing entity. 2 番目の呼び出しでは、指定された PartitionKey と 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)

ヒント

update_entity メソッドは、既存のエンティティのすべてのプロパティと値を置き換えます。既存のエンティティからプロパティを削除するのにも使用できます。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. merge_entity メソッドを使用すると、エンティティを完全に置き換えることなく、既存のエンティティを新しい、または変更されたプロパティ値で置き換えることができます。You can use the merge_entity method to update an existing entity with new or modified property values without completely replacing the entity.

複数のエンティティを変更するModify multiple entities

Table service による要求のアトミック処理を保証するため、複数の操作をまとめてバッチで送信できます。To ensure the atomic processing of a request by the Table service, you can submit multiple operations together in a batch. まず、TableBatch クラスを使用して、1 つのバッチに複数の操作を追加します。First, use the TableBatch class to add multiple operations to a single batch. 次に、TableService.commit_batch を呼び出して、操作をアトミック操作で送信します。Next, call TableService.commit_batch to submit the operations in an atomic operation. バッチで変更されるすべてのエンティティが同じパーティション内にある必要があります。All entities to be modified in batch must be in the same partition.

この例では、2 つのエンティティをバッチでまとめて追加します。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 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)

エンティティを照会するQuery for an entity

テーブル内のエンティティに対してクエリを実行するには、その PartitionKey と RowKey を 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)

エンティティのセットを照会するQuery a set of entities

filter パラメーターにフィルター文字列を指定することで、一連のエンティティに対してクエリを実行できます。You can query for a set of entities by supplying a filter string with the filter parameter. この例では、PartitionKey にフィルターを適用して、Seattle 内のすべてのタスクを検索します。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)

エンティティ プロパティのサブセットを照会するQuery a subset of entity properties

クエリの各エンティティに返すプロパティを制限することもできます。You can also restrict which properties are returned for each entity in a query. プロジェクション と呼ばれるこの方法では、帯域幅の使用が削減され、クエリのパフォーマンスが向上します。特に、大量のエンティティや結果セットがある場合に役立ちます。This technique, called projection, reduces bandwidth and can improve query performance, especially for large entities or result sets. select パラメーターを使用して、クライアントに返すプロパティの名前を渡します。Use the select parameter and pass the names of the properties you want returned to the client.

次のコードのクエリは、テーブル内のエンティティの説明だけを返します。The query in the following code returns only the descriptions of entities in the table.

注意

次のスニペットは、Azure Storage に対してのみ機能します。The following snippet works only against the 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)

エンティティを削除するDelete an entity

エンティティを削除するには、エンティティの PartitionKeyRowKeydelete_entity メソッドに渡します。Delete an entity by passing its PartitionKey and RowKey to the delete_entity method.

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

テーブルを削除するDelete a table

不要になったテーブルまたはテーブル内のエンティティがある場合、delete_table メソッドを呼び出して、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')

次のステップNext steps