クイックスタート: Python SDK と Azure Cosmos DB で Table 用 API アプリを構築する

[アーティクル]
05/08/2023

適用対象: Table

このクイックスタートでは、Python アプリケーションから Azure Cosmos DB の Table 用 API にアクセスする方法について説明します。 Azure Cosmos DB for Table はスキーマレスデータストアであり、これによりアプリケーションは構造化された NoSQL データをクラウドに格納できます。データはスキーマレスデザインで格納されるので、新しい属性を持つオブジェクトがテーブルに追加されると、新しいプロパティ (列) がテーブルに自動的に追加されます。 Python アプリケーションでは Azure Data Tables SDK for Python パッケージを使用して Azure Cosmos DB for Table にアクセスできます。

前提条件

サンプルアプリケーションは Python 3.7 以降で記述されていますが、原則はすべての Python 3.7 以降のアプリケーションに適用されます。 Visual Studio Code を IDE として使用できます。

Azure サブスクリプションをお持ちでない場合は、開始する前に無料アカウントを作成してください。

サンプルアプリケーション

このチュートリアルのサンプルアプリケーションは、リポジトリ (https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask) からクローンまたはダウンロードできます。

git clone https://github.com/Azure-Samples/msdocs-azure-tables-sdk-python-flask.git

サンプルリポジトリには 1-starter-app と 2-completed-app のサンプルフォルダーが含まれています。 1-starter-app には、"#TODO" とコメントされた (完成させるために更新が必要な) 行を含む機能がいくつか残されています。この記事に示されているコードスニペットは、1-starter-app を完成させるための追加コード (見本) です。

完成したサンプルアプリケーションでは、気象データを例として使用し、Table 用 API の機能をデモンストレーションします。気象観測を表すオブジェクトの格納と取得には Table 用 API を使用します。これには、Table 用 API のスキーマレス機能をデモンストレーションするために、追加のプロパティを持つオブジェクトの格納処理が含まれます。次の画像は、ブラウザーで実行されているローカルアプリケーションを示しています。Azure Cosmos DB for Table に格納されている気象データが表示されています。

1 - Azure Cosmos DB アカウントを作成する

まず、自分のアプリケーションで使用するテーブルが組み込まれる Azure Cosmos DB Tables API アカウントを作成します。 Azure portal、Azure CLI、または Azure PowerShell を使用してアカウントを作成します。

Azure portal にログインし、次の手順に従って Azure Cosmos DB アカウントを作成します。

手順	Screenshot
Azure portal で次の操作を行います。 Azure portal の上部の検索バーに「cosmos db」と入力します。検索バーの下に表示されるメニューの [サービス] で、「Azure Cosmos DB」とラベル付けされた項目を選択します。
[Azure Cosmos DB] ページで、[+作成] を選択します。
[API オプションの選択] ページで、[Azure テーブル] オプションを選択します。
[Azure Cosmos DB アカウントの作成] - [Azure テーブル] ページで、フォームに次のように入力します。 [リソースグループ] の下にある [新規作成] リンクを選択して、`rg-msdocs-tables-sdk-demo` という名前のストレージアカウントの新しいリソースグループを作成します。ストレージアカウントの名前は「`cosmos-msdocs-tables-sdk-demo-XYZ`」とします。ここで XYZ には任意のランダムな 3 文字を使用して、一意のアカウント名を作成します。 Azure Cosmos DB アカウント名の長さは 3 - 44 文字で、小文字、数字、またはハイフン (-) 文字のみを使用できます。ストレージアカウントのリージョンを選択します。 [標準] のパフォーマンスを選択します。 [容量モード] で、この例の [プロビジョニングされたスループット] を選択します。この例の [Free レベル割引の適用] で [適用] を選択します。画面の下部にある [確認と作成] ボタンを選び、概要画面で [作成] を選んで、Azure Cosmos DB アカウントを作成します。このプロセスには数分かかることがあります。

Azure Cosmos DB アカウントを作成するには az cosmosdb create コマンドを使用します。 Azure Cosmos DB 内でテーブルストレージを有効にするため、--capabilities EnableTable オプションを含める必要があります。すべての Azure リソースが 1 つのリソースグループに含まれているようにする必要があるため、次のコードスニペットでは、Azure Cosmos DB アカウントのリソースグループも作成されます。

Azure Cosmos DB アカウント名の長さは 3 ～ 44 文字で、小文字、数字、ハイフン (-) 文字のみを使用できます。 Azure Cosmos DB アカウント名は、Azure 全体で一意である必要があります。

Azure CLI コマンドは、Azure Cloud Shell で、または Azure CLI がインストールされているワークステーション上で実行できます。

通常、Azure Cosmos DB アカウントの作成プロセスが完了するまでには数分かかります。

LOCATION='eastus'
RESOURCE_GROUP_NAME='rg-msdocs-tables-sdk-demo'
COSMOS_ACCOUNT_NAME='cosmos-msdocs-tables-sdk-demo-123'    # change 123 to a unique set of characters for a unique name

az group create \
    --location $LOCATION \
    --name $RESOURCE_GROUP_NAME

az cosmosdb create \
    --name $COSMOS_ACCOUNT_NAME \
    --resource-group $RESOURCE_GROUP_NAME \
    --capabilities EnableTable

Azure Cosmos DB アカウントを作成するには、New-AzCosmosDBAccount コマンドレットを使用します。 Azure Cosmos DB 内でテーブルストレージを有効にするため、-ApiKind "Table" オプションを含める必要があります。すべての Azure リソースが 1 つのリソースグループに含まれているようにする必要があるため、次のコードスニペットでは、Azure Cosmos DB アカウントのリソースグループも作成されます。

Azure PowerShell コマンドは、Azure Cloud Shell、または Azure PowerShell がインストールされているワークステーションで実行できます。

通常、Azure Cosmos DB アカウントの作成プロセスが完了するまでには数分かかります。

$location = 'eastus'
$resourceGroupName = 'rg-msdocs-tables-sdk-demo'
$cosmosAccountName = 'cosmos-msdocs-tables-sdk-demo-123'  # change 123 to a unique set of characters for a unique name

# Create a resource group
New-AzResourceGroup `
    -Location $location `
    -Name $resourceGroupName

# Create an Azure Cosmos DB 
New-AzCosmosDBAccount `
    -Name $cosmosAccountName `
    -ResourceGroupName $resourceGroupName `
    -Location $location `
    -ApiKind "Table"

2 - テーブルを作成する

次に、アプリケーションで使用するテーブルを Azure Cosmos DB アカウント内に作成する必要があります。従来のデータベースとは異なり、指定する必要があるのはテーブルの名前のみであり、テーブルのプロパティ (列) は指定する必要はありません。データがテーブルに読み込まれると、必要に応じてプロパティ (列) が自動的に作成されます。

Azure portal で次の手順を実行して、Azure Cosmos DB アカウント内にテーブルを作成します。

手順	Screenshot
次の Azure portal で、Azure Cosmos DB アカウントの概要ページに移動します。 Azure Cosmos DB アカウントの概要ページに移動するには、上部の検索バーに Azure Cosmos DB アカウントの名前 (cosmos-msdocs-tables-sdk-demo-XYZ) を入力し、リソース見出しの下を確認します。 Azure Cosmos DB アカウントの名前を選び、[概要] ページに進みます。
[概要] ページで、[+テーブルの追加] を選びます。 [新しいテーブル] ダイアログがページの右側からスライドして表示されます。
[新しいテーブル] ダイアログで、次のようにフォームに記入します。テーブル ID として「WeatherData」という名前を入力します。この値はテーブルの名前です。この例では "テーブルスループット" の下で [手動] を選びます。推定 RU/秒で既定値の 400 を使用します。 [OK] ボタンを選択してテーブルを作成します。

Azure Cosmos DB にテーブルを作成するには az cosmosdb table create コマンドを使用します。

COSMOS_TABLE_NAME='WeatherData'

az cosmosdb table create \
    --account-name $COSMOS_ACCOUNT_NAME \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $COSMOS_TABLE_NAME \
    --throughput 400

Azure Cosmos DB にテーブルを作成するには New-AzCosmosDBTable コマンドレットを使用します。

$cosmosTableName = 'WeatherData'

# Create the table for the application to use
New-AzCosmosDBTable `
    -Name $cosmosTableName `
    -AccountName $cosmosAccountName `
    -ResourceGroupName $resourceGroupName

3 - Azure Cosmos DB 接続文字列を取得する

Azure Cosmos DB 内のテーブルにアクセスするには、Cosmos DB Storage アカウントのテーブル接続文字列がアプリに必要です。この接続文字列は、Azure portal、Azure CLI、または Azure PowerShell を使用して取得できます。

手順	Screenshot
Azure Cosmos DB アカウントページの左側にある "設定" ヘッダーの下で [接続文字列] というメニュー項目を見つけて選びます。 Azure Cosmos DB アカウントの接続文字列を取得できるページが表示されます。
[プライマリ接続文字列] の値をコピーして、アプリケーションで使用します。

Azure CLI を使用してプライマリ接続文字列を取得するには、オプション --type connection-strings を指定した az cosmosdb keys list コマンドを使用します。このコマンドは、JMESPath クエリを使用して主テーブル接続文字列のみを表示します。

# This gets the primary connection string
az cosmosdb keys list \
    --type connection-strings \
    --resource-group $RESOURCE_GROUP_NAME \
    --name $COSMOS_ACCOUNT_NAME \
    --query "connectionStrings[?description=='Primary Table Connection String'].connectionString" \
    --output tsv

Azure PowerShell を使用してプライマリ接続文字列を取得するには、Get-AzCosmosDBAccountKey コマンドレットを使用します。

# This gets the primary connection string
$(Get-AzCosmosDBAccountKey `
    -ResourceGroupName $resourceGroupName `
    -Name $cosmosAccountName `
    -Type "ConnectionStrings")."Primary Table Connection String"

Azure Cosmos DB アカウントの接続文字列はアプリのシークレットと見なされ、他のアプリのシークレットやパスワードと同様に保護する必要があります。

4 - Azure Data Tables SDK for Python をインストールする

Azure Cosmos DB アカウントを作成した後は、Microsoft Azure Data Tables SDK for Python をインストールします。 SDK のインストールの詳細については、GitHub の Data Tables SDK for Python リポジトリ内の README.md を参照してください。

pip を使用して Python 用の Azure Tables クライアントライブラリをインストールします。

pip install azure-data-tables

1-starter-app フォルダーまたは 2-completed-app フォルダーに、requirements.txt も忘れずにインストールしてください。

5 - .env ファイルで Table クライアントを構成する

Azure portal から Azure Cosmos DB アカウントの接続文字列をコピーし、コピーした接続文字列を使用して TableServiceClient オブジェクトを作成します。 1-starter-app または 2-completed-app フォルダーに切り替えます。どのアプリから始めるかに関係なく、.env ファイルで環境変数を定義する必要があります。

# Configuration Parameters
conn_str = "A connection string to an Azure Cosmos DB account."
table_name = "WeatherData"
project_root_path = "Project abs path"

Azure SDK は、クライアントオブジェクトを使用して Azure と通信し、Azure に対してさまざまな操作を実行します。 TableServiceClient オブジェクトは、Azure Cosmos DB for Table と通信するために使用されるオブジェクトです。アプリケーションは通常、全体として 1 つの TableServiceClient があり、テーブルごとに 1つの TableClient があります。

たとえば、次のコードでは、環境変数の接続文字列を使用して TableServiceClient オブジェクトを作成します。

self.conn_str = os.getenv("conn_str")
self.table_service = TableServiceClient.from_connection_string(self.conn_str)

6 - Azure Cosmos DB テーブル操作を実装する

サンプルアプリケーションの Azure Cosmos DB テーブル操作はすべて、webapp ディレクトリの helper ファイルにある TableServiceHelper クラスに実装されます。 Python 用 azure.data.tables クライアントライブラリ内のオブジェクトを操作するには、このファイルの先頭で TableServiceClient クラスをインポートする必要があります。

from azure.data.tables import TableServiceClient

TableServiceHelper クラスの先頭に、コンストラクターを作成し、TableClient オブジェクトをクラスに挿入するための TableClient オブジェクトのメンバー変数を追加します。

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)

テーブルから返された行をフィルター処理する

テーブルから返された行をフィルター処理するには、OData スタイルのフィルター文字列を query_entities メソッドに渡します。たとえば、2021 年 7 月 1 日午前 0 時から 2021 年 7 月 2 日午前 0 時 (午前 0 時を含む) までの Chicago の気象記録をすべて取得するには、次のフィルター文字列を渡します。

PartitionKey eq 'Chicago' and RowKey ge '2021-07-01 12:00 AM' and RowKey le '2021-07-02 12:00 AM'

関連する OData フィルター演算子は、azure-data-tables Web サイトの「フィルターの記述」セクションで確認できます。

この request.args パラメータが TableServiceHelper クラスの query_entity メソッドに渡されると、null 以外のプロパティ値ごとにフィルター文字列が作成されます。次に、"and" 句を使用してすべての値を結合することで、結合フィルター文字列が作成されます。この結合フィルター文字列は TableClient オブジェクトの query_entities メソッドに渡されて、フィルター文字列に一致する行だけが返されます。同様のメソッドをコード内で使用して、各自のアプリケーションで必要に応じて適切なフィルター文字列を作成できます。

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)))

TableEntity オブジェクトを使用してデータを挿入する

テーブルにデータを追加する最も簡単な方法は TableEntity オブジェクトを使用する方法です。この例では、データが入力モデルオブジェクトから TableEntity オブジェクトにマップされます。入力オブジェクトで観測所名と観測日時を表すプロパティは、PartitionKey および RowKey プロパティにそれぞれマップされ、これらによりテーブル行の一意キーが形成されます。その後、入力モデルオブジェクトの追加プロパティが TableEntity オブジェクトのディクショナリプロパティにマップされます。最後に TableClient オブジェクトの create_entity メソッドを使用して、テーブルにデータが挿入されます。

サンプルアプリケーションの insert_entity 関数を変更して、次のコードを含めます。

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

TableEntity オブジェクトを使用してデータをアップサートする

テーブルに既に存在するパーティションキーと行キーの組み合わせでそのテーブルに行を挿入しようとすると、エラーが発生します。このため多くの場合、テーブルに行を追加するときには create_entity メソッドの代わりに upsert_entity を使用することが推奨されます。指定されたパーティションキーと行キーの組み合わせがテーブルに既に存在する場合は、upsert_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

可変プロパティを使用してデータを挿入またはアップサートする

Azure Cosmos DB for Table を使用する利点の 1 つは、テーブルに読み込まれるオブジェクトに新しいプロパティが含まれている場合、それらのプロパティがテーブルに自動的に追加され、値が Azure Cosmos DB に格納されることです。従来のデータベースのように、ALTER TABLE などの DDL ステートメントを実行して列を追加する必要はありません。

このモデルを使用すると、時間の経過とともに取り込む必要があるデータを追加または変更する可能性のあるデータソースを扱う場合や、異なる入力によりアプリケーションに異なるデータを提供する場合に、アプリケーションに柔軟性が加わります。サンプルアプリケーションでは、基本的な気象データの他にいくつか追加の値も送信する観測所をシミュレートできます。このような新しいプロパティを持つオブジェクトが初めてテーブルに格納されるときに、対応するプロパティ (列) がテーブルへ自動的に追加されます。

Table 用 API を使用してこのようなオブジェクトを挿入またはアップサートするには、展開可能なオブジェクトのプロパティを TableEntity オブジェクトにマップし、必要に応じて TableClient オブジェクトの create_entity または upsert_entity メソッドを使用します。

サンプルアプリケーションでは、upsert_entity 関数は、変数プロパティを持つデータの挿入またはアップサートの関数を実装することもできます

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

エンティティを更新する

エンティティを更新するには、TableClient オブジェクトの update_entity メソッドを呼び出します。

サンプルアプリケーションでは、このオブジェクトは TableClient クラスの upsert_entity メソッドに渡されます。そのエンティティオブジェクトを更新し、upsert_entity メソッドを使用して更新内容をデータベースに保存します。

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

エンティティを削除する

テーブルからエンティティを削除するには、TableClient オブジェクトの delete_entity メソッドを呼び出します。その際に、このオブジェクトのパーティションキーと行キーを指定します。

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 - コードを実行する

サンプルアプリケーションを実行して、Azure Cosmos DB for Table を操作します。たとえば、要件がインストールされた 2-completed-app フォルダーでは、次のように起動します。

python3 run.py webapp

サンプルアプリケーション実行について詳しくは、サンプルリポジトリルートの README.md ファイルをご覧ください。

アプリケーションを初めて実行する場合にはテーブルが空であるため、データがありません。アプリケーションの上部にあるいずれかのボタンを使用して、テーブルにデータを追加します。

[Insert using Table Entity](テーブルエンティティを使用して挿入) ボタンを選択すると、TableEntity オブジェクトを使用して新しい行を挿入またはアップサートできるダイアログが開きます。

[Insert using Expandable Data](展開可能なデータを使用して挿入) ボタンを選択すると、カスタムプロパティを持つオブジェクトを挿入できるダイアログが表示され、Azure Cosmos DB for Table によって必要に応じてプロパティ (列) がテーブルに自動的に追加される方法が示されます。 [カスタムフィールドの追加] ボタンを使用して、1 つ以上の新しいプロパティを追加し、この機能を示します。

[サンプルデータを挿入] ボタンを使用して、一部のサンプルデータを Azure Cosmos DB テーブルに読み込みます。

1-starter-app サンプルフォルダーの場合は、サンプルデータの挿入を機能させるために、少なくとも submit_transaction 関数のコードを完成させる必要があります。
サンプルデータは、sample_data.json ファイルから読み込まれます。 .env 変数 project_root_path で、このファイルが格納されている場所をアプリに指定します。たとえば、1-starter-app フォルダーまたは 2-completed-app フォルダーからアプリケーションを実行する場合は、project_root_path に "" (空白) を設定します。

上部のメニューの [Filter Results](結果のフィルター処理) 項目を選択すると、[Filter Results](結果のフィルター処理) ページが表示されます。フィルター句を作成して Azure Cosmos DB for Table に渡す方法を示すため、このページでフィルター条件を入力します。

リソースをクリーンアップする

サンプルアプリケーションの使用が完了したら、この記事に関連するすべての Azure リソースを Azure アカウントから削除する必要があります。リソースグループを削除すると、すべてのリソースを削除できます。

Azure portal を使用してリソースグループを削除するには、次の手順を実行します。

手順	Screenshot
リソースグループに進むには、検索バーにリソースグループの名前を入力します。次に [リソースグループ] タブで、リソースグループの名前を選択します。
リソースグループページの上部のツールバーから [リソースグループの削除] を選択します。
リソースグループの削除を確認するダイアログが画面の右側に表示されます。テキストボックスにリソースグループの名前を完全に入力し、指示に従って削除を確認します。ページ下部の [削除] ボタンを選択します。

Azure CLI を使用してリソースグループを削除するには、削除するリソースグループの名前を指定した az group delete コマンドを使用します。リソースグループを削除すると、そのリソースグループに含まれているすべての Azure リソースも削除されます。

az group delete --name $RESOURCE_GROUP_NAME

Azure PowerShell を使用してリソースグループを削除するには、削除するリソースグループの名前を指定した Remove-AzResourceGroup コマンドを使用します。リソースグループを削除すると、そのリソースグループに含まれているすべての Azure リソースも削除されます。

Remove-AzResourceGroup -Name $resourceGroupName

次のステップ

このクイックスタートでは、Azure Cosmos DB アカウントを作成し、データエクスプローラーを使用してテーブルを作成し、アプリを実行する方法を説明しました。これで、Table 用 API を使用してデータに対してクエリを実行できるようになりました。

Table 用 API を使って Azure Cosmos DB に対するクエリを実行する

クイック スタート: Python SDK と Azure Cosmos DB で Table 用 API アプリを構築する