Python 用 Azure DataLake サービスクライアントライブラリ - バージョン 12.14.0

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

概要

Python 用のこのプレビューパッケージには、Storage SDK で使用できる ADLS Gen2 固有の API サポートが含まれています。これには次のものが含まれます

階層型名前空間対応 (HNS) ストレージアカウントの新しいディレクトリレベル操作 (作成、名前変更、削除)。 HNS が有効なアカウントの場合、名前の変更/移動操作はアトミックです。
階層型名前空間が有効な (HNS) アカウントのアクセス許可関連の操作 (ACL の取得/設定)。

作業の開始

前提条件

このパッケージを使用するには、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 宛てに質問またはコメントをお送りください。

次の方法で共有

Python 用 Azure DataLake サービスクライアントライブラリ - バージョン 12.14.0

作業の開始

前提条件

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

ストレージアカウントの作成

クライアントを認証する

資格情報の取得

クライアントの作成

主要な概念

非同期クライアント

クライアント

例

接続文字列を使用したクライアントの作成

ファイルのアップロード

ファイルのダウンロード

パスの列挙

オプションの構成

再試行ポリシーの構成

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

トラブルシューティング

全般

ログの記録

次のステップ

その他のサンプルコード

その他のドキュメント

共同作成

その他のリソース

次の方法で共有

Python 用 Azure DataLake サービス クライアント ライブラリ - バージョン 12.14.0

作業の開始

前提条件

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

ストレージ アカウントの作成

クライアントを認証する

資格情報の取得

クライアントの作成

主要な概念

非同期クライアント

クライアント

例

接続文字列を使用したクライアントの作成

ファイルのアップロード

ファイルのダウンロード

パスの列挙

オプションの構成

再試行ポリシーの構成

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

トラブルシューティング

全般

ログの記録

次のステップ

その他のサンプル コード

その他のドキュメント

共同作成

その他のリソース

Python 用 Azure DataLake サービスクライアントライブラリ - バージョン 12.14.0

ストレージアカウントの作成

その他のサンプルコード