Python 用 Azure DataLake サービス クライアント ライブラリ - バージョン 12.14.0
概要
Python 用のこのプレビュー パッケージには、Storage SDK で使用できる ADLS Gen2 固有の API サポートが含まれています。 これには次のものが含まれます
- 階層型名前空間対応 (HNS) ストレージ アカウントの新しいディレクトリ レベル操作 (作成、名前変更、削除)。 HNS が有効なアカウントの場合、名前の変更/移動操作はアトミックです。
- 階層型名前空間が有効な (HNS) アカウントのアクセス許可関連の操作 (ACL の取得/設定)。
ソースコード | パッケージ (PyPi) | パッケージ (Conda) | API リファレンス ドキュメント | 製品ドキュメント | サンプル
作業の開始
前提条件
- このパッケージを使用するには、Python 3.7 以降が必要です。 詳細については、 Azure SDK for Python バージョンのサポート ポリシーに関するページを参照してください。
- このパッケージを使用するには、 Azure サブスクリプション と Azure ストレージ アカウント が必要です。
パッケージをインストールする
pip を使用して Python 用 Azure DataLake Storage クライアント ライブラリをインストールします。
pip install azure-storage-file-datalake --pre
ストレージ アカウントの作成
新しいストレージ アカウントを作成する場合は、Azure Portal、Azure PowerShell、または Azure CLI を使用できます。
# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2
# Install the extension 'Storage-Preview'
az extension add --name storage-preview
# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true
クライアントを認証する
DataLake Storage との対話は、DataLakeServiceClient クラスのインスタンスから始まります。 クライアント オブジェクトをインスタンス化するには、既存のストレージ アカウント、その URL、資格情報が必要です。
資格情報の取得
クライアントを認証するには、いくつかのオプションがあります。
- SAS トークン文字列を使用する
- アカウント共有アクセス キーを使用する
- azure.identity からのトークン資格情報を使用する
または、 メソッドを使用してストレージ 接続文字列でfrom_connection_string認証することもできます。 「例: 接続文字列を使用したクライアントの作成」を参照してください。
アカウント URL に SAS トークンが既に含まれている場合は、資格情報を省略できます。
クライアントの作成
アカウントの URL と資格情報の準備ができたら、DataLakeServiceClient を作成できます。
from azure.storage.filedatalake import DataLakeServiceClient
service = DataLakeServiceClient(account_url="https://<my-storage-account-name>.dfs.core.windows.net/", credential=credential)
主要な概念
DataLake ストレージには、次の 4 種類のリソースが用意されています。
- ストレージ アカウント
- ストレージ アカウント内のファイル システム
- ファイル システムの下のディレクトリ
- ファイル システムまたはディレクトリ内のファイル
非同期クライアント
このライブラリには、Python 3.5 以降でサポートされている完全な非同期 API が含まれています。 これを使用するには、まず、 aiohttp などの非同期トランスポートをインストールする必要があります。 詳細については、 azure-core のドキュメント を参照してください。
非同期クライアントと資格情報は、不要になったら閉じる必要があります。 これらのオブジェクトは非同期コンテキスト マネージャーであり、非同期 close メソッドを定義します。
クライアント
DataLake Storage SDK には、DataLake サービスと対話するための 4 つの異なるクライアントが用意されています。
- DataLakeServiceClient - このクライアントは、アカウント レベルで DataLake サービスと対話します。
アカウントのプロパティの取得と構成、およびアカウント内のファイル システムの一覧表示、作成、削除を行う操作が提供されます。
特定のファイル システム、ディレクトリ、またはファイルに関連する操作の場合、これらのエンティティのクライアントは、 または
get_file_system_client関数をget_file_clientget_directory_client使用して取得することもできます。 - FileSystemClient - このクライアントは、そのファイル システムがまだ存在しない場合でも、特定のファイル システムとの対話を表します。 ファイル システムを作成、削除、または構成する操作を提供し、ファイル システムのパスを一覧表示する操作、ファイル システム内のファイルまたはディレクトリをアップロード、削除する操作が含まれます。
特定のファイルに関連する操作の場合は、 関数を使用してクライアントを
get_file_client取得することもできます。 特定のディレクトリに関連する操作の場合は、 関数を使用してクライアントをget_directory_client取得できます。 - DataLakeDirectoryClient - このクライアントは、そのディレクトリがまだ存在しない場合でも、特定のディレクトリとの対話を表します。 ディレクトリ操作の作成、削除、名前変更、プロパティの取得、およびプロパティの設定操作が提供されます。
- DataLakeFileClient - このクライアントは、そのファイルがまだ存在しない場合でも、特定のファイルとの対話を表します。 データの追加、データのフラッシュ、ファイルの削除、作成、読み取りを行うファイル操作を提供します。
- DataLakeLeaseClient - このクライアントは、FileSystemClient、DataLakeDirectoryClient、または DataLakeFileClient とのリース操作を表します。 リソースのリースを取得、更新、リリース、変更、中断する操作を提供します。
例
次のセクションでは、次のような最も一般的な Storage DataLake タスクをカバーするいくつかのコード スニペットを示します。
接続文字列を使用したクライアントの作成
Azure Storage アカウントへの接続文字列を使用して DataLakeServiceClient を作成します。
from azure.storage.filedatalake import DataLakeServiceClient
service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")
ファイルのアップロード
ファイル システムにファイルをアップロードします。
from azure.storage.filedatalake import DataLakeFileClient
data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))
ファイルのダウンロード
ファイル システムからファイルをダウンロードします。
from azure.storage.filedatalake import DataLakeFileClient
file = DataLakeFileClient.from_connection_string("my_connection_string",
file_system_name="myfilesystem", file_path="myfile")
with open("./BlockDestination.txt", "wb") as my_file:
download = file.download_file()
download.readinto(my_file)
パスの列挙
ファイル システム内のパスを一覧表示します。
from azure.storage.filedatalake import FileSystemClient
file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")
paths = file_system.get_paths()
for path in paths:
print(path.name + '\n')
オプションの構成
省略可能キーワード (keyword)、クライアントレベルおよび操作ごとのレベルで渡すことができる引数です。
再試行ポリシーの構成
クライアントをインスタンス化して再試行ポリシーを構成する場合は、次のキーワード (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): クライアントがサーバーへの接続の確立を待機する秒数。 既定値は 20 秒です。
- read_timeout (int): サーバーからの応答について、クライアントが連続する読み取り操作の間に待機する秒数。 これはソケット レベルのタイムアウトであり、全体的なデータ サイズの影響を受けません。 クライアント側の読み取りタイムアウトは自動的に再試行されます。 既定値は 60 秒です。
- transport (Any): HTTP 要求を送信するためのユーザー指定のトランスポート。
操作ごとのキーワード (keyword)引数:
- raw_response_hook (呼び出し可能): 指定されたコールバックは、サービスから返された応答を使用します。
- raw_request_hook (呼び出し可能): 指定されたコールバックは、サービスに送信される前に要求を使用します。
- client_request_id (str): 要求の省略可能なユーザー指定 ID。
- user_agent (str): 要求と共に送信されるユーザー エージェント ヘッダーにカスタム値を追加します。
- logging_enable (bool): DEBUG レベルでログ記録を有効にします。 既定値は False です。 また、クライアント レベルでを渡して、すべての要求に対して有効にすることもできます。
- logging_body (bool): 要求と応答本文のログ記録を有効にします。 既定値は False です。 また、クライアント レベルでを渡して、すべての要求に対して有効にすることもできます。
- headers (dict): カスタム ヘッダーをキーと値のペアとして渡します。 例:
headers={'CustomValue': value}
トラブルシューティング
全般
DataLake Storage クライアントでは、 Azure Core で定義されている例外が発生します。
このリストは、スローされた例外をキャッチするための参照に使用できます。 例外の特定のエラー コードを取得するには、 属性 ( error_code つまり) exception.error_codeを使用します。
ログの記録
このライブラリでは、標準の ログ記録 ライブラリを使用してログを記録します。 HTTP セッション (URL、ヘッダーなど) に関する基本情報は INFO レベルでログに記録されます。
要求/応答本文や未変換ヘッダーなど、詳細な DEBUG レベルのログ記録は、 引数を使用 logging_enable してクライアントで有効にすることができます。
import sys
import logging
from azure.storage.filedatalake import DataLakeServiceClient
# Create a logger for the 'azure.storage.filedatalake' SDK
logger = logging.getLogger('azure.storage')
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 = DataLakeServiceClient.from_connection_string("your_connection_string", logging_enable=True)
同様に、logging_enable は、詳細なログ記録がクライアントで有効になっていない場合でも、1 回の操作のために有効にすることができます。
service_client.list_file_systems(logging_enable=True)
次のステップ
その他のサンプル コード
Azure DataLake サンプルの使用を開始します。
SDK の GitHub リポジトリには、DataLake Storage Python SDK サンプルがいくつか用意されています。 これらのサンプルでは、DataLake Storage の作業中に一般的に発生する追加のシナリオのコード例を示します。
datalake_samples_access_control.py- 一般的な DataLake Storage タスクの例:- ファイル システムを設定する
- ディレクトリを作成する
- ディレクトリのアクセス制御の設定/取得
- ディレクトリの下にファイルを作成する
- 各ファイルのアクセス制御を設定/取得する
- ファイル システムを削除する
datalake_samples_upload_download.py- 一般的な DataLake Storage タスクの例:- ファイル システムを設定する
- [ファイルの作成]
- ファイルにデータを追加する
- ファイルにデータをフラッシュする
- アップロードしたデータをダウンロードする
- ファイル システムを削除する
その他のドキュメント
ADLS Gen1 から ADLS Gen2 API へのマッピングの表 Data Lake Storage Gen2に関するより広範な REST ドキュメントについては、docs.microsoft.com に関するData Lake Storage Gen2ドキュメントを参照してください。
共同作成
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。
pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。
このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。
Azure SDK for Python