クイック スタート: Python 用 Azure Blob Storage クライアント ライブラリ

  • [アーティクル]

Note

最初からビルドするオプションでは、新しいプロジェクトの作成、パッケージのインストール、コードの作成、基本的なコンソール アプリの実行のプロセスを段階的に説明します。 Azure Blob Storage に接続するアプリの作成に関係するすべての詳細を理解したい場合は、この方法をお勧めします。 デプロイ タスクを自動化し、完成したプロジェクトから開始する場合は、テンプレートを使って開始するを選びます。

Note

テンプレートを使って開始するオプションでは、Azure Developer CLI を使ってデプロイ タスクを自動化し、完成したプロジェクトから開始します。 セットアップ タスクを実行せずにできるだけ早くコードを調べたい場合は、この方法をお勧めします。 アプリをビルドするための段階的な手順を希望する場合は、最初からビルドするを選びます。

Python 用の Azure Blob Storage クライアント ライブラリの使用を開始して、BLOB とコンテナーを管理します。

この記事では、手順に従ってパッケージをインストールし、基本タスクのコード例を試してみます。

この記事では、Azure Developer CLI を使って Azure リソースをデプロイし、いくつかのコマンドで完成したコンソール アプリを実行します。

API リファレンス ドキュメント | ライブラリのソース コード | パッケージ (PyPi) | サンプル

このビデオでは、Python 用 Azure Blob Storage クライアント ライブラリの使用を開始する方法について説明します。

ビデオの手順については、次のセクションでも説明します。

前提条件

設定

このセクションでは、Python 用 Azure Blob Storage クライアント ライブラリを操作するためのプロジェクトの準備について説明します。

プロジェクトを作成する

blob-quickstart という名前の Python アプリケーションを作成します。

  1. コンソール ウィンドウ (PowerShell や Bash など) で、プロジェクト用に新しいディレクトリを作成します。

    mkdir blob-quickstart

  2. 新しく作成された blob-quickstart ディレクトリに切り替えます。

    cd blob-quickstart

パッケージのインストール

プロジェクト ディレクトリから、pip install コマンドを使用して、Azure Blob Storage と Azure ID のクライアント ライブラリのパッケージをインストールします。 Azure サービスへのパスワードレス接続には、azure-identity パッケージが必要です。

pip install azure-storage-blob azure-identity

アプリのフレームワークを設定する

プロジェクト ディレクトリから、次の手順に従ってアプリの基本的な構造を作成します。

  1. コード エディターで新しいテキスト ファイルを開きます。
  2. 次に示すように、import ステートメントを追加し、プログラムの構造を作成し、基本的な例外処理を含めます。
  3. 新しいファイルを blob_quickstart.py として blob-quickstart ディレクトリに保存します。
import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

Azure Developer CLI をインストールすると、ストレージ アカウントを作成し、いくつかのコマンドでサンプル コードを実行できます。 プロジェクトはローカル開発環境または DevContainer で実行できます。

Azure Developer CLI テンプレートを初期化し、リソースをデプロイする

空のディレクトリから以下の手順に従って、azd テンプレートを初期化し、Azure リソースをプロビジョニングし、コードでの作業を開始します。

  • GitHub からクイックスタート リポジトリ資産をクローンして、テンプレートをローカルで初期化します。

    azd init --template blob-storage-quickstart-python

    次の情報の入力を求められます。

    • 環境名: この値は、Azure Developer CLI によって作成されたすべての Azure リソースのプレフィックスとして使われます。 名前はすべての Azure サブスクリプション間で一意である必要があり、3 から 24 文字の長さにする必要があります。 名前には、数字と小文字のみを含めることができます。

  • Azure へのログイン:

    azd auth login

  • リソースをプロビジョニングして Azure にデプロイします。

    azd up

    次の情報の入力を求められます。

    • サブスクリプション: リソースがデプロイされる Azure サブスクリプション。
    • 場所: リソースがデプロイされる Azure リージョン。

    デプロイが完了するまでに数分かかることがあります。 azd up コマンドの出力には、新しく作成されたストレージ アカウントの名前が含まれています。これは、後でコードを実行するために必要になります。

サンプル コードを実行します。

この時点で、リソースが Azure にデプロイされ、コードを実行する準備がほぼ整います。 以下の手順に従ってパッケージをインストールし、コード内のストレージ アカウントの名前を更新し、サンプル コンソール アプリを実行します。

  • パッケージのインストール: ローカル ディレクトリで次のコマンドを使用して、Azure Blob Storage と Azure ID のクライアント ライブラリのパッケージをインストールします: pip install azure-storage-blob azure-identity
  • ストレージ アカウント名の更新: ローカル ディレクトリで、blob_quickstart.py というファイルを編集します。 <storage-account-name> プレースホルダーを見つけて、azd up コマンドで作成されたストレージ アカウントの実際の名前に置き換えます。 変更を保存します。
  • プロジェクトの実行: 次のコマンドを実行して、アプリを実行します: python blob_quickstart.py。
  • 出力を確認する: このアプリは、ローカルの data フォルダーにテスト ファイルを作成し、ストレージ アカウントのコンテナーにアップロードします。 次に、コンテナー内の BLOB を一覧表示し、ファイルを新しい名前でダウンロードして、古いファイルと新しいファイルを比較できるようにします。

サンプル コードがどのように機能するかの詳細については、コード例を参照してください。

コードのテストが完了したら、「リソースのクリーンアップ」セクションを参照して、azd up コマンドによって作成されたリソースを削除します。

オブジェクト モデル

Azure Blob Storage は、大量の非構造化データを格納するために最適化されています。 非構造化データとは、特定のデータ モデルや定義に従っていないデータであり、テキスト データやバイナリ データなどがあります。 Blob Storage には、3 種類のリソースがあります。

  • ストレージ アカウント
  • ストレージ アカウント内のコンテナー
  • コンテナー内の BLOB

次の図に、これらのリソースの関係を示します。

Diagram of Blob storage architecture

これらのリソースとやり取りするには、以下の Python クラスを使用します。

  • BlobServiceClient:BlobServiceClient クラスを使用して、Azure Storage リソースと BLOB コンテナーを操作できます。
  • ContainerClient:ContainerClient クラスを使用して、Azure Storage コンテナーとその BLOB を操作できます。
  • BlobClient:BlobClient クラスを使用して、Azure Storage BLOB を操作できます。

コード例

以下のサンプル コード スニペットは、Python 用 Azure Blob Storage クライアント ライブラリを使用して以下のタスクを実行する方法を示します。

Note

Azure Developer CLI テンプレートには、サンプル コードが既に配置されているファイルが含まれています。 次の例では、サンプル コードの各部分について詳しく説明します。 このテンプレートは、Azure への認証に関するセクションで説明されているように、推奨されるパスワードレスの認証方法を実装します。 接続文字列メソッドは代替手段として示されていますが、テンプレートでは使われず、運用環境コードには推奨されません。

Azure に対する認証と BLOB データへのアクセスの認可

Azure Blob Storage に対するアプリケーション要求は、認可されている必要があります。 Azure Identity クライアント ライブラリによって提供される DefaultAzureCredential クラスを使用することは、Blob Storage などのコード内の Azure サービスへのパスワードレス接続を実装するための推奨される方法です。

アカウント アクセス キーを使用して、Azure Blob Storage への要求を認可することもできます。 ただし、この方法は慎重に使用する必要があります。 開発者は、セキュリティで保護されていない場所にアクセス・キーを公開しないように注意する必要があります。 アクセス キーを持つすべてのユーザーは、ストレージ アカウントに対する要求を承認でき、実質的にすべてのデータにアクセスできます。 DefaultAzureCredential はアカウント・キーよりも管理しやすく、セキュリティが優れており、パスワードレス認証が可能になります。 両方のオプションの例を次に示します。

DefaultAzureCredential は複数の認証方法をサポートしており、実行時に使用する方法が決定されます。 このアプローチを採用すると、環境固有のコードを実装することなく、異なる環境 (ローカルと運用環境) で異なる認証方法をアプリに使用できます。

DefaultAzureCredential が資格情報を検索する順序と場所については、Azure ID ライブラリの概要に関する記事を参照してください。

たとえば、ローカルで開発するときに、アプリから Azure CLI のサインイン資格情報を使って認証することができます。 アプリを Azure にデプロイした後は、マネージド ID を使用できます。 この移行のためにコードを変更する必要はありません。

Microsoft Entra ユーザー アカウントにロールを割り当てる

ローカルで開発する場合は、BLOB データにアクセスするユーザー アカウントに正しいアクセス許可があることを確認します。 BLOB データの読み取りと書き込みを行うには、ストレージ BLOB データ共同作成者が必要です。 このロールを自分に割り当てるには、ユーザー アクセス管理者ロール、または Microsoft.Authorization/roleAssignments/write アクションを含む別のロールに割り当てられている必要があります。 Azure portal、Azure CLI、または Azure PowerShell を使用して、ユーザーに Azure RBAC ロールを割り当てることができます。 ロールの割り当てに使用できるスコープの詳細は、スコープの概要ページでご覧いただけます。

このシナリオでは、最小限の特権の原則に従って、ストレージ アカウントに限定したアクセス許可をユーザー アカウントに割り当てます。 この方法を使って、ユーザーに必要最小限のアクセス許可のみを与え、より安全な運用環境を作成します。

次の例では、ストレージ BLOB データ共同作成者ロールを自分のユーザー アカウントに割り当てます。これにより、そのストレージ アカウント内の BLOB データに対する読み取りと書き込みの両方のアクセス権が付与されます。

重要

ほとんどの場合、ロールの割り当てが Azure に反映されるまでの時間は 1 分から 2 分ですが、まれに 8 分程度までかかる場合があります。 初めてコードを実行したときに認証エラーを受け取る場合は、しばらく待ってから再試行してください。

  1. Azure portal で、メインの検索バーまたは左側のナビゲーションを使ってストレージ アカウントを見つけます。

  2. ストレージ アカウントの概要ページで、左側のメニューから [アクセス制御 (IAM)] を選びます。

  3. [アクセス制御 (IAM)] ページで、[ロールの割り当て] タブを選びます。

  4. 上部のメニューから [+ 追加] を選択し、次に結果のドロップダウン メニューから [ロールの割り当ての追加] を選択します。

    A screenshot showing how to assign a role.

  5. 検索ボックスを使って、結果を目的のロールに絞り込みます。 この例では、ストレージ BLOB データ共同作成者を検索し、一致する結果を選び、[次へ] を選びます。

  6. [アクセスの割り当て先] で、[ユーザー、グループ、またはサービス プリンシパル] を選び、[+ メンバーの選択] を選びます。

  7. ダイアログで、自分の Microsoft Entra ユーザー名 (通常は user@domain メール アドレス) を検索し、ダイアログの下部にある [選択] を選びます。

  8. [レビューと割り当て] を選んで最終ページに移動し、もう一度 [レビューと割り当て] を行ってプロセスを完了します。

DefaultAzureCredential を使用して Azure にサインインしてアプリ コードを接続する

次の手順を使用して、ストレージ アカウント内のデータへのアクセスを認可できます。

  1. 必ず、ストレージ アカウントでロールを割り当てたのと同じ Microsoft Entra アカウントを使って認証を受けてください。 Azure CLI、Visual Studio Code、または Azure PowerShell を使って認証することができます。

    Azure CLI で次のコマンドを使って Azure にサインインします。

    az login

  2. DefaultAzureCredential を使用するには、azure-identity パッケージがインストールされ、クラスがインポートされていることを確認してください。

    from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

  3. このコードを try ブロック内に追加します。 ローカルのワークステーション上でコードを実行する場合、DefaultAzureCredential はログインしている優先順位の高いツールの開発者資格情報を使用して、Azure に対して認証が行われます。 これらのツールの例としては、Azure CLI や Visual Studio Code などがあります。

    account_url = "https://<storageaccountname>.blob.core.windows.net"
default_credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=default_credential)

  4. 必ず、BlobServiceClient オブジェクトの URI のストレージ アカウント名を更新してください。 ストレージ アカウント名は、Azure portal の概要ページで確認できます。

    A screenshot showing how to find the storage account name.

    Note

    Azure にデプロイした場合は、この同じコードを使用して、Azure で実行されているアプリケーションから Azure Storage への要求を認可できます。 ただし、Azure 内のアプリ上でマネージド ID を有効にする必要があります。 次に、そのマネージド ID が接続できるようにストレージ アカウントを構成します。 この Azure サービス間の接続を構成する詳細な手順については、Azure ホステッド アプリからの認証に関するチュートリアルを参照してください。

コンテナーの作成

blob_service_client オブジェクト上で create_container メソッドを呼び出して、ストレージ アカウントに新しいコンテナーを作成します。 この例のコードでは、確実に一意になるように、コンテナー名に GUID 値を追加します。

try ブロックの末尾に、次のコードを追加します。

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

コンテナーの作成の詳細と、その他のコード サンプルについては、「Create a blob container with Python (Python を使用して BLOB コンテナーを作成する)」を参照してください。

重要

コンテナーの名前は小文字にする必要があります。 コンテナーと BLOB の名前付けの詳細については、「Naming and Referencing Containers, Blobs, and Metadata (コンテナー、BLOB、メタデータの名前付けと参照)」を参照してください。

コンテナーに BLOB をアップロードする

upload_blob を使用してコンテナーに BLOB をアップロードします。 このコード例では、コンテナーにアップロードするローカルの data ディレクトリにテキスト ファイルを作成します。

try ブロックの末尾に、次のコードを追加します。

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

BLOB のアップロードの詳細と、その他のコード サンプルについては、「Upload a blob with Python (Python を使用して BLOB をアップロードする)」を参照してください。

コンテナー内の BLOB を一覧表示する

list_blobs メソッドを呼び出して、コンテナー内の BLOB を一覧表示します。 この場合、コンテナーに BLOB が 1 つだけ追加されているので、一覧表示操作ではその 1 つの BLOB だけが返されます。

try ブロックの末尾に、次のコードを追加します。

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

BLOB の一覧表示の詳細と、その他のコード サンプルについては、List blobs with Python (Python を使用して BLOB を一覧表示する)」を参照してください。

BLOB をダウンロードする

download_blob メソッドを呼び出して、以前に作成した BLOB をダウンロードします。 サンプル コードでは、ローカル ファイル システム内で両方のファイルを見ることができるように、ファイル名に "DOWNLOAD" というサフィックスを追加します。

try ブロックの末尾に、次のコードを追加します。

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

BLOB のダウンロードの詳細と、その他のコード サンプルについては、「Download a blob with Python (Python を使用して BLOB をダウンロードする)」を参照してください。

コンテナーを削除する

次のコードでは、​delete_container メソッドを使用して、コンテナー全体を削除することによって、アプリが作成したリソースがクリーンアップされます。 必要に応じてローカル ファイルを削除することもできます。

アプリでは、BLOB、コンテナー、およびローカル ファイルを削除する前に、input() を呼び出すことで、ユーザーの入力を一時停止します。 リソースが正しく作成されたことを確認してから、それらを削除してください。

try ブロックの末尾に、次のコードを追加します。

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

コンテナーの削除の詳細と、その他のコード サンプルについては、Delete and restore a blob container with Python (Python を使用して BLOB コンテナーを削除および復元する)」を参照してください。

コードの実行

このアプリでは、ローカル フォルダーにテスト ファイルが作成され、Azure Blob Storage にアップロードされます。 さらに、この例では、コンテナー内の BLOB を一覧表示し、新しい名前でファイルをダウンロードします。 古いファイルと新しいファイルを比較できます。

blob_quickstart.py ファイルが格納されているディレクトリに移動し、次の python コマンドを実行してアプリを実行します。

python blob_quickstart.py

アプリの出力は次の例のようになります (読みやすくするために UUID 値は省略されています)。

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

クリーンアップ プロセスを開始する前に、data フォルダー内の 2 つのファイルをチェックします。 それらを比較して、同じであるかどうかを確認します。

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

ファイルを確認し、テストを完了したら、Enter キーを押して、ストレージ アカウントに作成したコンテナーと共にテスト ファイルを削除します。 Azure CLI を使用して、リソースを削除することもできます。

クイックスタートが完了したら、次のコマンドを実行して、作成したリソースをクリーンアップできます。

azd down

リソースの削除の確認を求めるプロンプトが表示されます。 確認するには「y」と入力します。

次のステップ

このクイックスタートでは、Python を使用して BLOB をアップロード、ダウンロード、一覧表示する方法について説明しました。

BLOB ストレージのサンプル アプリを確認するには、以下に進んでください。

Python 用 Azure Blob Storage ライブラリのサンプル