Azure Functions における Azure Blob Storage のバインドの概要

2024-04-07

Azure Functions はトリガーとバインドを使用して Azure Storage と統合されます。 Blob Storage との統合により、BLOB データの変更に対応し、値の読み取りと書き込も行う関数を作成することができます。

アクション	タイプ
Blob Storage データが変更されたときに関数を実行する	トリガー
関数で Blob Storage データを読み取る	入力バインド
関数で Blob Storage データを書き込めるようにする	出力バインド

拡張機能のインストール

インストールする拡張機能 NuGet パッケージは、関数アプリで使用している C# モードによって異なります。

分離ワーカーモデル
インプロセスモデル

関数は分離された C# ワーカープロセスで実行されます。詳しくは、「分離ワーカープロセスにおける C# Azure Functions の実行のガイド」をご覧ください。

拡張機能の機能性は、拡張機能のバージョンによって異なります。

このセクションでは、クラスライブラリの使用について説明します。 C# スクリプトについては、代わりにバージョン 4.x の拡張機能バンドルをインストールする必要があります。

このバージョンでは、シークレットではなく ID を使用して接続する機能が導入されています。マネージド ID を使用して関数アプリを構成するチュートリアルについては、ID ベースの接続を使用した関数アプリの作成に関するチュートリアルを参照してください。

このバージョンでは、Azure.Storage.Blobs からの型にバインドできます。これらの新しい型がWindowsAzure.StorageおよびMicrosoft.Azure.Storageとどのように異なるか、またそれらを移行する方法については、Azure.Storage.Blobs の移行ガイドに関するページを参照してください。

この拡張機能は、Microsoft.Azure.WebJobs.Extensions.Storage.Blobs NuGet パッケージ、バージョン 5.x をインストールすることで利用できます。

.NET CLI の使用

dotnet add package Microsoft.Azure.WebJobs.Extensions.Storage.Blobs --version 5.0.0

注意

Azure BLOB、Azure キュー、Azure テーブルでは、個別の拡張機能が使用され、個別に参照されるようになりました。たとえば、.NET インプロセスアプリの 3 つのサービスすべてに対してトリガーとバインドを使用するには、次のパッケージをプロジェクトに追加する必要があります。

以前、拡張機能は Microsoft.Azure.WebJobs.Extensions.Storage、バージョン 4.x としてまとめて出荷されました。この同じパッケージには 5.x バージョンもあり、BLOB とキューのみの分割パッケージを参照します。このため、パッケージ参照を古いバージョンからアップグレードする場合は、新しい Microsoft.Azure.WebJobs.Extensions.Tables NuGet パッケージを追加で参照する必要がある場合があります。また、このような新しい分割パッケージを参照するとき、結合されたストレージパッケージの古いバージョンを参照していないことを確認してください。同じバインディングの 2 つの定義による競合の発生を防止できます。

このバージョンでは、 .NET Aspire 統合を使用したトリガーとバインドの構成がサポートされています。

Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs NuGet パッケージ、バージョン 5.x 以降をインストールすることでパッケージに拡張機能を追加します。

.NET CLI の使用

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs

注意

Azure BLOB、Azure キュー、Azure テーブルでは、個別の拡張機能が使用され、個別に参照されるようになりました。たとえば、.NET 分離プロセスアプリの 3 つのサービスすべてに対してトリガーとバインドを使用するには、次のパッケージをプロジェクトに追加する必要があります。

Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues の最新バージョンに置き換えます
Microsoft.Azure.Functions.Worker.Extensions.Tables に置き換えます

以前、拡張機能は Microsoft.Azure.Functions.Worker.Extensions.Storage、バージョン 4.x としてまとめて出荷されました。この同じパッケージには 5.x バージョンもあり、BLOB とキューのみの分割パッケージを参照します。このため、パッケージ参照を古いバージョンからアップグレードする場合は、新しい Microsoft.Azure.Functions.Worker.Extensions.Tables NuGet パッケージを追加で参照する必要がある場合があります。また、このような新しい分割パッケージを参照するとき、結合されたストレージパッケージの古いバージョンを参照していないことを確認してください。同じバインディングの 2 つの定義による競合の発生を防止できます。

F# を使用してアプリケーションを記述する場合、アプリのスタートアップ構成の一部としてこの拡張機能を構成することもできます。 ConfigureFunctionsWorkerDefaults() または ConfigureFunctionsWebApplication() の呼び出しで、IFunctionsWorkerApplication パラメーターを受け取るデリゲートを追加します。次に、そのデリゲートの本文内でオブジェクトの ConfigureBlobStorageExtension() を呼び出します。

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureBlobStorageExtension() |> ignore
) |> ignore

バンドルのインストール

アプリでこのバインド拡張機能を使用できるようにするには、プロジェクトのルートにある host.json ファイルに次の extensionBundle 参照が含まれていることを確認します。

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

この例では、versionの[4.0.0, 5.0.0)値は、少なくとも4.0.0が5.0.0未満のバンドルバージョン (4.x のすべての潜在的なバージョンを含む) を使用するように Functions ホストに指示します。この表記は、v4.x 拡張機能バンドルの利用可能な最新のマイナーバージョンでアプリを効果的に維持します。

可能であれば、最新の拡張機能バンドルメジャーバージョンを使用し、ランタイムが最新のマイナーバージョンを自動的に維持できるようにする必要があります。最新のバンドルの内容は、拡張機能バンドルのリリースページで確認できます。詳細については、 Azure Functions 拡張機能バンドルに関するページを参照してください。

バインドの種類

.NET でサポートされるバインドの種類は、拡張機能のバージョンと C# 実行モードの両方によって異なります。これは次のいずれかになります。

分離ワーカーモデル
インプロセスモデル

分離ワーカープロセスクラスライブラリでコンパイルされた C# 関数は、ランタイムから分離されたプロセスで実行されます。

バージョンを選択すると、モードとバージョンのバインドの種類の詳細が表示されます。

Azure BLOB 拡張機能では、次の表に従ってパラメーターの型がサポートされています。

バインドのシナリオ	パラメーターの種類
BLOB トリガー	川 `TextReader` `string` `byte[]` BinaryData BlobClient¹ BlockBlobClient¹ PageBlobClient¹ AppendBlobClient¹ BlobBaseClient¹
BLOB 入力 (単一の BLOB)	川 `TextReader` `string` `byte[]` BinaryData BlobClient¹ BlockBlobClient¹ PageBlobClient¹ AppendBlobClient¹ BlobBaseClient¹
BLOB 入力 (1 つのコンテナーの複数の BLOB)	`IEnumerable<T>` (`T` は単一の BLOB 入力バインドの種類のいずれか)
BLOB 出力 (単一の BLOB)	川 `TextWriter` `string` `byte[]`
BLOB 出力 (複数の BLOB)	`ICollector<T>` または `IAsyncCollector<T>` (`T` は単一の BLOB 出力バインドの種類のいずれか)

¹ クライアント型では、属性の Access プロパティを FileAccess.ReadWrite に設定する必要があります。

これらの型の使用例については、拡張機能の GitHub リポジトリに関するページを参照してください。 Azure SDK の型、以前のバージョンとの違い、それらを移行する方法について、Azure.Storage.Blobs 移行ガイドに関するページを参照してください。

以前のバージョンの拡張機能では、現在は非推奨の Microsoft.Azure.Storage.Blob 名前空間の型が公開されていました。 Azure.Storage.Blobs の新しい型は、拡張機能 5.x 以降専用です。

このバージョンの Azure BLOB 拡張機能では、次の表に従ってパラメーターの型がサポートされています。

バインド	パラメーターの種類
BLOB トリガー	川 `TextReader` `string` `byte[]` ICloudBlob¹ CloudBlockBlob¹ CloudPageBlob¹ CloudAppendBlob¹
BLOB 入力	川 `TextReader` `string` `byte[]` ICloudBlob¹ CloudBlockBlob¹ CloudPageBlob¹ CloudAppendBlob¹
BLOB 出力	川 `TextWriter` `string` `byte[]`

¹ これらの型では、属性の Access プロパティを FileAccess.ReadWrite に設定する必要があります。

²IEnumerable<T> は、コンテナー内の BLOB の列挙体を提供します。ここで、T はサポートされているその他の型のいずれかになります。

分離ワーカープロセスでは、下の表に従ってパラメーターの型がサポートされています。

BLOB トリガー

BLOB トリガーは、次の型にバインドできます。

タイプ	説明
`string`	BLOB コンテンツを表す文字列。 BLOB コンテンツが単純なテキストのときに使用します。
`byte[]`	BLOB コンテンツのバイト数。
JSON シリアル化可能な型	BLOB に JSON データが含まれているとき、Functions は JSON データを単純な従来の CLR オブジェクト (POCO) 型に逆シリアル化しようとします。
Stream¹	BLOB コンテンツの入力ストリーム。
BlobClient¹、 BlockBlobClient¹、 PageBlobClient¹、 AppendBlobClient¹、 BlobBaseClient¹	BLOB に接続されているクライアント。この型のセットには BLOB の処理に対する最大限の制御機能が備わっています。接続に十分なアクセス許可がある場合は、BLOB への書き戻しに使用できます。

¹ これらの型を使用するには、Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs 6.0.0 以降と SDK 型バインドの一般的な依存関係に関する記事を参照する必要があります。

BLOB 入力バインディング

関数で 1 つの BLOB を処理するとき、BLOB 入力バインドは次の型にバインドできます。

タイプ	説明
`string`	BLOB コンテンツを表す文字列。 BLOB コンテンツが単純なテキストのときに使用します。
`byte[]`	BLOB コンテンツのバイト数。
JSON シリアル化可能な型	BLOB に JSON データが含まれているとき、Functions は JSON データを単純な従来の CLR オブジェクト (POCO) 型に逆シリアル化しようとします。
Stream¹	BLOB コンテンツの入力ストリーム。
BlobClient¹、 BlockBlobClient¹、 PageBlobClient¹、 AppendBlobClient¹、 BlobBaseClient¹	BLOB に接続されているクライアント。この型のセットには BLOB の処理に対する最大限の制御機能が備わっています。接続に十分なアクセス許可がある場合は、それへの書き戻しに使用できます。

関数で 1 つのコンテナーの複数の BLOB を処理するとき、BLOB 入力バインドは次の型にバインドできます。

タイプ	説明
`T[]` または `List<T>` (`T` は単一の BLOB 入力バインドの型のいずれか)	複数の BLOB の配列またはリスト。各エントリは、コンテナーの 1 つの BLOB を表します。これらの型によって実装される `IEnumerable<T>` などの任意のインターフェイスにバインドすることもできます。
BlobContainerClient¹	コンテナーに接続されているクライアント。この型にはコンテナーの処理に対する最大限の制御機能が備わっています。接続に十分なアクセス許可がある場合は、それへの書き込みに使用できます。

BLOB 出力バインディング

関数で 1 つの BLOB に書き込むとき、BLOB 出力バインドは次の型にバインドできます。

タイプ	説明
`string`	BLOB コンテンツを表す文字列。 BLOB コンテンツが単純なテキストのときに使用します。
`byte[]`	BLOB コンテンツのバイト数。
JSON シリアル化可能な型	JSON BLOB の内容を表すオブジェクト。 Functions は、Plain Old CLR Object (POCO) 型を JSON データにシリアル化しようとします。

関数で複数の BLOB に書き込むとき、BLOB 出力バインドは次の型にバインドできます。

タイプ	説明
`T[]` (`T` は単一の BLOB 出力バインドの型のいずれか)	複数の BLOB の内容を含む配列。各エントリは、1 つの BLOB の内容を表します。

その他の出力シナリオでは、 BlobClient または BlobContainerClient Azure.Storage.Blobs から直接他の型と共に作成して使用します。依存関係の挿入を使用して Azure SDK からクライアントの種類を作成する例については Azure クライアントの登録に関するページを参照してください。

SDK バインドの種類

Azure Storage BLOB の SDK の種類が一般公開されました。 Python での BLOB 用 SDK の種類の使用を開始するには、BLOB 用の Python SDK バインドのサンプルに従います。

重要

SDK の型バインドを使用するには、 Python v2 プログラミングモデルが必要です。

バインド	パラメーターの種類	サンプル
BLOB トリガー	BlobClient、 ContainerClient、 StorageStreamDownloader	`BlobClient`, `ContainerClient`, `StorageStreamDownloader`
BLOB 入力	BlobClient、 ContainerClient、 StorageStreamDownloader	`BlobClient`, `ContainerClient`, `StorageStreamDownloader`

host.json 設定

このセクションでは、このバインディングを使用する関数で使用できる関数アプリの構成設定について説明します。これらの設定は、拡張機能バージョン 5.0.0 以上を使用している場合にのみ適用されます。次の host.json ファイルの例には、このバインドのバージョン 2.x 以降の設定のみが含まれています。バージョン 2.x 以降のバージョンでの関数アプリ構成設定の詳細については、「Azure Functions の host.json のリファレンス」を参照してください。

注意

このセクションは、5.0.0 より前の拡張機能のバージョンには適用されません。それらの以前のバージョンでは、BLOB に対する関数アプリ規模の構成設定はありません。

{
    "version": "2.0",
    "extensions": {
        "blobs": {
            "maxDegreeOfParallelism": 4,
            "poisonBlobThreshold": 1
        }
    }
}

プロパティ	既定値	説明
maxDegreeOfParallelism	8 * (使用可能なコアの数)	特定の関数アプリ内で、BLOB によってトリガーされるすべての関数について、同時呼び出しに許可される数を表す整数。許容される最小値は 1 です。
poisonBlobThreshold	5	有害キューに移動する前に、メッセージの処理を試行する回数 (整数)。許容される最小値は 1 です。

次のステップ

フィードバック

このページはお役に立ちましたか?