Python 用 Azure Tables クライアント ライブラリ - バージョン 12.4.4

Azure Tables は、HTTP または HTTPS を使用して認証された呼び出しを介して世界中のどこからでもアクセスできる NoSQL データ ストレージ サービスです。 テーブルは、挿入されたデータの量をサポートするために必要に応じてスケーリングされ、複雑でないアクセスを使用してデータを格納できます。 Azure Tables クライアントを使用して、Azure Storage または Cosmos アカウントにアクセスできます。 このドキュメントでは、 について説明します azure-data-tables。

このパッケージは、現在非推奨になった代替 azure-cosmosdb-tables 品であることに注意してください。 詳細については、 移行ガイド を参照してください。

ソースコード | パッケージ (PyPI) | パッケージ (Conda) | API リファレンス ドキュメント | サンプル

免責事項

Python 2.7 の Azure SDK Python パッケージのサポートは、2022 年 1 月 1 日に終了しました。 詳細と質問については、このパッケージを使用するには https://github.com/Azure/azure-sdk-for-python/issues/20691Python 3.7 以降が必要ですを参照してください。詳細については、「 Azure SDK for Python バージョンサポート ポリシー」を参照してください。

作業の開始

Azure Tables SDK は、Azure Storage または CosmosDB アカウントにアクセスできます。

前提条件

• このパッケージを使用するには、Python 3.7 以降が必要です。
• Azure サブスクリプションを持っている必要があります。また、次のいずれかを行う必要があります
  • Azure Storage アカウントまたは
  • Azure Cosmos アカウント。

アカウントを作成する

• 新しいストレージ アカウントを作成するには、Azure Portal、Azure PowerShell、または Azure CLI を使用できます。
• 新しい Cosmos ストレージ アカウントを作成するには、 Azure CLI または Azure Portal を使用できます。

パッケージをインストールする

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

pip install azure-data-tables

クライアントを作成する

Azure Tables ライブラリを使用すると、次の 2 種類のリソースを操作できます。

• アカウント内のテーブル
• これらのテーブル内のエンティティ。 これらのリソースとの対話は、 クライアントのインスタンスから始まります。 クライアント オブジェクトを作成するには、アカウントのテーブル サービス エンドポイント URL と、アカウントにアクセスできる資格情報が必要です。 は endpoint 、 Azure Portal の [アクセス キー] セクションのストレージ アカウントのページにあります。または、次の Azure CLI コマンドを実行します。

# Get the table service URL for the account
az storage account show -n mystorageaccount -g MyResourceGroup --query "primaryEndpoints.table"

アカウント URL を取得したら、それを使用してサービス クライアントを作成できます。

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

テーブル サービス URL の詳細と、Azure Storage のカスタム ドメイン名を構成する方法の詳細については、公式ドキュメントをチェック

資格情報の種類

パラメーターは credential 、使用する承認の種類に応じて、さまざまな形式で指定できます。 Tables ライブラリでは、次の承認がサポートされています。

• 共有キー
• Connection String
• Shared Access Signature Token

共有キーからクライアントを作成する

アカウント 共有キー (アカウント キーまたはアクセス キーとも呼ばれます) を使用するには、キーを文字列として指定します。 これは、 Azure Portal のストレージ アカウントの [アクセス キー] セクションで、または次の Azure CLI コマンドを実行して確認できます。

az storage account keys list -g MyResourceGroup -n MyStorageAccount

資格情報パラメーターとして キーを使用して、クライアントを認証します。

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)

接続文字列からのクライアントの作成

ユース ケースと承認方法によっては、アカウントの URL と資格情報を個別に指定する代わりに、接続文字列を使用してクライアント インスタンスを初期化することをお勧めします。 これを行うには、接続文字列をクライアントの from_connection_string クラス メソッドに渡します。 接続文字列は、 Azure Portal のストレージ アカウントの [アクセス キー] セクションで、または次の Azure CLI コマンドを使用して見つけることができます。

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)

SAS トークンからのクライアントの作成

Shared Access Signature (SAS) トークンを使用するには、トークンを文字列として指定します。 アカウント URL に SAS トークンが含まれている場合は、credential パラメーターを省略します。 Azure Portal の [共有アクセス署名 ] で SAS トークンを生成するか、関数のいずれかを generate_*_sas() 使用してアカウントまたはテーブルの sas トークンを作成できます。

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

主要な概念

Table サービスの一般的な用途は次のとおりです。

• Web スケール アプリケーションにサービスを提供できる数テラバイトの構造化データを格納する
• 複雑な結合、外部キー、またはストアド プロシージャを必要とせず、高速アクセスのために非正規化できるデータセットの格納
• クラスター化インデックスを使用して高速なデータのクエリを実行する
• OData プロトコルと LINQ フィルター式を使用したデータへのアクセス

Azure Tables Service を構成するコンポーネントは次のとおりです。

• アカウント
• エンティティのセットを含むアカウント内のテーブル
• テーブル内のディクショナリとしてのエンティティ

Python 用 Azure Tables クライアント ライブラリを使用すると、専用のクライアント オブジェクトを使用して、これらの各コンポーネントを操作できます。

クライアント

Table Service のさまざまなコンポーネントを操作するために、2 つの異なるクライアントが用意されています。

1. TableServiceClient -
   • アカウント設定を取得して設定する
   • アカウント内のテーブルのクエリ、作成、削除を行います。
   • メソッドを TableClient 使用して特定のテーブルにアクセスするための を get_table_client 取得します。
2. TableClient -
   • 特定のテーブルと対話します (まだ存在する必要はありません)。
   • 指定したテーブル内にエンティティを作成、削除、クエリ、アップサートします。
   • 指定したテーブル自体を作成または削除します。

エンティティ

エンティティは行に似ています。 エンティティには、、 PartitionKey、 RowKeyおよび プロパティのセットがあります。 プロパティは、列に似た名前の値のペアです。 テーブル内のすべてのエンティティは、同じプロパティを持つ必要はありません。 エンティティは、例として次のようなディクショナリとして表すことができます。

entity = {
    'PartitionKey': 'color',
    'RowKey': 'brand',
    'text': 'Marker',
    'color': 'Purple',
    'price': '5'
}

• create_entity - エンティティをテーブルに追加します。
• delete_entity - テーブルからエンティティを削除します。
• update_entity - 既存のエンティティをマージまたは置き換えて、エンティティの情報を更新します。
  • UpdateMode.MERGE は既存のエンティティに新しいプロパティを追加します。既存のプロパティは削除されません
  • UpdateMode.REPLACE は、既存のエンティティを指定されたエンティティに置き換え、送信されたエンティティに含まれていない既存のプロパティを削除します
• query_entities - OData フィルターを使用してテーブル内の既存のエンティティにクエリを実行します。
• get_entity - パーティションキーと行キーでテーブルから特定のエンティティを取得します。
• upsert_entity - テーブル内のエンティティをマージまたは置換するか、エンティティが存在しない場合はエンティティを挿入します。
  • UpdateMode.MERGE は既存のエンティティに新しいプロパティを追加します。既存のプロパティは削除されません
  • UpdateMode.REPLACE は、既存のエンティティを指定されたエンティティに置き換え、送信されたエンティティに含まれていない既存のプロパティを削除します

例

次のセクションでは、次のような最も一般的な Table タスクの一部をカバーするいくつかのコード スニペットを示します。

• テーブルの作成
• エンティティの作成
• エンティティのクエリ

テーブルの作成

アカウントにテーブルを作成し、 を取得 TableClient して、新しく作成されたテーブルに対して操作を実行します。

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)

エンティティの作成

テーブルにエンティティを作成します。

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)

エンティティの照会

テーブル内のエンティティのクエリ:

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

オプションの構成

省略可能なキーワード (keyword)引数は、クライアントレベルと操作ごとのレベルで渡すことができます。 azure-core リファレンス ドキュメント では、再試行、ログ記録、トランスポート プロトコルなどの使用可能な構成について説明しています。

再試行ポリシーの構成

再試行ポリシーを構成するには、クライアントをインスタンス化するときに、次のキーワード (keyword)引数を使用します。

• retry_total (int): 許可する再試行の合計数。 他のカウントよりも優先されます。 要求時に retry_total=0 再試行しない場合は、 を渡します。 既定値は 10 です。
• retry_connect (int): 再試行する接続関連エラーの数。 既定値は 3 です。
• retry_read (int): 読み取りエラーで再試行する回数。 既定値は 3 です。
• retry_status (int): 無効な状態コードで再試行する回数。 既定値は 3 です。
• retry_to_secondary (bool): 要求をセカンダリに再試行する必要があるかどうか (可能な場合)。 これは、RA-GRS アカウントのみが使用され、古いデータを処理できる可能性がある場合にのみ有効にする必要があります。 既定値は False です。

その他のクライアント/操作ごとの構成

その他の省略可能な構成キーワード (keyword)クライアントまたは操作ごとに指定できる引数です。

クライアント キーワード (keyword)引数:

• connection_timeout (int): 必要に応じて、接続と読み取りのタイムアウト値を秒単位で設定します。
• transport (Any): HTTP 要求を送信するためのユーザー指定のトランスポート。

操作ごとのキーワード (keyword)引数:

• raw_response_hook (呼び出し可能): 指定されたコールバックは、サービスから返される応答を使用します。
• raw_request_hook (呼び出し可能): 指定されたコールバックは、サービスに送信される前に要求を使用します。
• client_request_id (str): 要求の省略可能なユーザー指定 ID。
• user_agent (str): 要求と共に送信するユーザー エージェント ヘッダーにカスタム値を追加します。
• logging_enable (bool): DEBUG レベルでログ記録を有効にします。 既定値は False です。 クライアント レベルで渡して、すべての要求に対して有効にすることもできます。
• headers (dict): カスタム ヘッダーをキー、値のペアとして渡します。 例: headers={'CustomValue': value}

トラブルシューティング

全般

Azure Tables クライアントでは、 Azure Core で定義されている例外が発生します。 Python SDK を使用して Azure テーブル ライブラリを操作すると、サービスによって返されるエラーは 、REST API 要求に対して同じ HTTP 状態コードに応答します。 Table サービス操作では、役に立つエラー コードを使用してエラー時に がスローHttpResponseErrorされます。

たとえば、既に存在するテーブルを作成しようとすると、 409 "競合" を示すエラーが返されます。

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

ログの記録

このライブラリでは、ログ記録に標準 のログ ライブラリが使用されます。 HTTP セッションに関する基本情報 (URL、ヘッダーなど) は INFO レベルでログに記録されます。

要求/応答本文、未変換ヘッダーなど、詳細な DEBUG レベルのログは、 引数を使用してクライアントで logging_enable 有効にすることができます。

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 クライアントで有効になっていない場合でも、1 つの操作の詳細なログ記録を有効にすることができます。

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

次のステップ

Table サンプルの使用を開始します。

いくつかの Azure Tables Python SDK サンプルは、SDK の GitHub リポジトリで入手できます。 これらのサンプルでは、テーブルの操作中に一般的に発生するその他のシナリオのコード例を示します。

一般的なシナリオ

これらのコード サンプルは、Azure Tables クライアント ライブラリでの一般的なシナリオ操作を示しています。 サンプルの非同期バージョン (_asyncで追加された python サンプル ファイル) は、非同期操作を示しています。

• テーブルの作成と削除: sample_create_delete_table.py (非同期バージョン)
• テーブルの一覧表示とクエリ: sample_query_tables.py (非同期バージョン)
• エンティティの挿入と削除: sample_insert_delete_entities.py (非同期バージョン)
• エンティティのクエリと一覧表示: sample_query_table.py (非同期バージョン)
• エンティティの更新、アップサート、マージ: sample_update_upsert_merge_entities.py (非同期バージョン)
• 1 つのトランザクションで多数の要求をコミットする: sample_batching.py (非同期バージョン)

その他のドキュメント

Azure Tables の詳細なドキュメントについては、docs.microsoft.com に関 する Azure Tables のドキュメントを参照してください 。

の既知の問題

Cosmos DB テーブル エンドポイントに関連する現在既知の問題の一覧 については、こちらを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。