Azure Functions の Azure Blob Storage トリガー

Blob ストレージ トリガーは、新しいまたは更新された BLOB が検出されたときに関数を開始します。 BLOB の内容は、関数への入力として提供されます。

Azure Blob Storage トリガーには、汎用ストレージ アカウントが必要です。 階層型名前空間を持つストレージ V2 アカウントもサポートされています。 BLOB 専用アカウントを使用する場合、またはアプリケーションに特別な必要性がある場合は、このトリガーの使用に代わる方法を検討してください。

セットアップと構成の詳細については、概要に関するページをご覧ください。

ポーリング

ポーリングは、ログの検査と定期的なコンテナー スキャンの実行のハイブリッドとして機能します。 BLOB は、間隔の間で使用される継続トークンを使用して、一度に 10,000 のグループ単位でスキャンされます。

警告

また、 ストレージ ログは "ベスト エフォート" ベースで作成されます。 すべてのイベントがキャプチャされる保証はありません。 ある条件下では、ログが欠落する可能性があります。

より高速で信頼性の高い BLOB 処理が必要な場合は、BLOB 作成時にキュー メッセージを作成することを検討してください。 次に、BLOB トリガーの代わりにキュー トリガーを使用して BLOB を処理します。 別のオプションは、Event Grid の使用です。「Event Grid を使用して、アップロードされたイメージのサイズ変更を自動化する」のチュートリアルをご覧ください。

代替

Event Grid トリガー

注意

5.x 以降のバージョンの Storage 拡張機能では、Event Grid を使用する Blob トリガーが組み込みでサポートされています。 詳しくは、以下の「ストレージ拡張機能 5.x 以降」セクションをご覧ください。

Event Grid トリガーにも、BLOB イベントのサポートが組み込まれています。 次のシナリオの場合は、Blob ストレージ トリガーではなく Event Grid を使用してください。

  • BLOB 専用ストレージ アカウント: BLOB 専用ストレージ アカウントは、BLOB の入力と出力のバインドでサポートされ、BLOB トリガーではサポートされません。

  • 高スケール: 高スケールとは、おおまかに言って、100,000 以上の BLOB を含むコンテナー、または 1 秒あたり 100 を超える BLOB の更新が発生するストレージ アカウントと定義できます。

  • 既存の BLOB: BLOB トリガーは、トリガーを設定するときにコンテナー内のすべての既存の BLOB を処理します。 既存の BLOB が多数含まれ、新しい BLOB に対してトリガーするだけのコンテナーがある場合は、Event Grid トリガーを使用します。

  • 待ち時間の最小化: 関数アプリを従量課金プランで使用しているときに、関数アプリがアイドル状態になっている場合、新しい BLOB の処理が最大で 10 分間遅延する可能性があります。 この待機時間を避けるには、Always On が有効な App Service プランに切り替えることができます。 BLOB ストレージ アカウントで Event Grid トリガーを使用することもできます。 例については、Event Grid のチュートリアルを参照してください。

Event Grid の例については、Event Grid を使用した画像のサイズ変更に関するチュートリアルを参照してください。

ストレージ拡張機能 5.x 以降

プレビュー版の Storage 拡張機能の Blob トリガーは、Event Grid を組み込みでサポートしています。これを使用するには、既存の Blob トリガーの source パラメーターを “Event Grid” に設定する必要があります。

Event Grid を使用する Blob トリガーの詳しい使用方法は、Event Grid Blob トリガーの使用方法に関する記事をご覧ください。

Queue ストレージ トリガー

BLOB を処理するもう 1 つの方法は、作成または変更される BLOB に対応するキュー メッセージを作成し、Queue storage トリガーを使用して処理を開始することです。

次の例は、samples-workitems コンテナーで BLOB が追加または更新されたときにログを書き込む C# 関数を示しています。

[FunctionName("BlobTriggerCSharp")]        
public static void Run([BlobTrigger("samples-workitems/{name}")] Stream myBlob, string name, ILogger log)
{
    log.LogInformation($"C# Blob trigger function Processed blob\n Name:{name} \n Size: {myBlob.Length} Bytes");
}

BLOB トリガー パス samples-workitems/{name} の文字列 {name} は、トリガーする BLOB のファイル名にアクセスするために関数コードで使用できる、バインディング式を作成します。 詳しくは、後述の「BLOB 名のパターン」をご覧ください。

BlobTrigger 属性の詳細については、「属性と注釈」を参照してください。

属性と注釈

C# クラス ライブラリで、次の属性を使用して BLOB トリガーを構成します。

  • BlobTriggerAttribute

    属性のコンストラクターは、監視するコンテナーを示すパス文字列と、必要に応じて BLOB 名のパターンを受け取ります。 次に例を示します。

    [FunctionName("ResizeImage")]
    public static void Run(
        [BlobTrigger("sample-images/{name}")] Stream image,
        [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
    {
        ....
    }
    

    次の例で示すように、Connection プロパティを設定して、使用するストレージ アカウントを指定できます。

    [FunctionName("ResizeImage")]
    public static void Run(
        [BlobTrigger("sample-images/{name}", Connection = "StorageConnectionAppSetting")] Stream image,
        [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageSmall)
    {
        ....
    }
    

    完全な例については、「トリガー - 例」を参照してください。

  • StorageAccountAttribute

    使用するストレージ アカウントを指定する別の方法を提供します。 コンストラクターは、ストレージ接続文字列を含むアプリ設定の名前を受け取ります。 属性は、パラメーター、メソッド、またはクラス レベルで適用できます。 次の例では、クラス レベルとメソッド レベルを示します。

    [StorageAccount("ClassLevelStorageAppSetting")]
    public static class AzureFunctions
    {
        [FunctionName("BlobTrigger")]
        [StorageAccount("FunctionLevelStorageAppSetting")]
        public static void Run( //...
    {
        ....
    }
    

使用するストレージ アカウントは、次の順序で決定されます。

  • BlobTrigger 属性の Connection プロパティ。
  • BlobTrigger 属性と同じパラメーターに適用された StorageAccount 属性。
  • 関数に適用される StorageAccount 属性。
  • クラスに適用される StorageAccount 属性。
  • 関数アプリの既定のストレージ アカウント ("AzureWebJobsStorage" アプリ設定)。

構成

次の表は、function.json ファイルと BlobTrigger 属性で設定したバインド構成のプロパティを説明しています。

function.json のプロパティ 属性のプロパティ 説明
type 該当なし blobTrigger に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
direction 該当なし in に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。 例外は、使用方法のセクションに記載しています。
name 該当なし 関数コード内の BLOB を表す変数の名前。
path BlobPath 監視するコンテナーBLOB 名パターンの場合があります。
connection 接続 このバインドに使用するストレージ接続文字列を含むアプリ設定の名前です。 アプリ設定の名前が "AzureWebJobs" で始まる場合は、ここで名前の残りの部分のみを指定できます。 たとえば、connection を "MyStorage" に設定した場合、Functions ランタイムは "AzureWebJobsMyStorage" という名前のアプリ設定を探します。 connection を空のままにした場合、Functions ランタイムは、アプリ設定内の AzureWebJobsStorage という名前の既定のストレージ接続文字列を使用します。

接続文字列は、BLOB ストレージ アカウントではなく汎用ストレージ アカウントに対するものである必要があります。

接続文字列の代わりにバージョン 5.x またはそれ以降の拡張機能を使用している場合は、接続を定義する構成セクションへの参照を指定できます。 「接続」を参照してください。

ローカルで開発している場合、アプリ設定は local.settings.json ファイルに保存されます。

使用法

Default

トリガーする BLOB には、次のパラメーターの型を使用できます。

  • Stream
  • TextReader
  • string
  • Byte[]
  • ICloudBlob1
  • CloudBlockBlob1
  • CloudPageBlob1
  • CloudAppendBlob1

1function.json には "inout" バインド direction、C# クラス ライブラリには FileAccess.ReadWrite が必要です。

Storage SDK タイプの 1 つにバインドしようとしてエラー メッセージが表示された場合は、適切な Storage SDK バージョンへの参照があることをご確認ください。

string または Byte[] へのバインドが推奨されるのは、BLOB のサイズが小さい場合のみです (BLOB 全体のコンテンツがメモリに読み込まれるため)。 通常、Stream 型または CloudBlockBlob 型の使用が推奨されます。 詳しくは、この記事で後述する「コンカレンシーとメモリ使用量」セクションをご覧ください。

その他の型

Storage 拡張機能の 5.0.0 以降のバージョンを使用するアプリでは、Azure SDK for .NET の型も使用できる場合があります。 このバージョンでは、次の型を優先するため、従来の ICloudBlobCloudBlockBlobCloudPageBlobCloudAppendBlob 型がサポートされなくなります。

1function.json には "inout" バインド direction、C# クラス ライブラリには FileAccess.ReadWrite が必要です。

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

BLOB 名のパターン

function.jsonpath プロパティまたは BlobTrigger 属性コンストラクターで BLOB 名のパターンを指定することができます。 名前のパターンは、フィルターまたはバインド式にすることができます。 以下のセクションで、例を示します。

ヒント

名前パターンでは、コンテナー名に競合回避モジュールを含めることはできません。

ファイル名と拡張子の取得

次の例は、BLOB ファイル名と拡張子を別々にバインドする方法を示します。

"path": "input/{blobname}.{blobextension}",

BLOB の名前が original-Blob1.txt の場合、関数コード内の blobname 変数と blobextension 変数の値は original-Blob1txt です。

BLOB 名のフィルター

次の例は、文字列 "original-" で始まる input コンテナーの BLOB でのみトリガーします。

"path": "input/original-{name}",

BLOB 名が original-Blob1.txt の場合、関数コード内の name 変数の値は Blob1.txt です。

ファイルの種類のフィルター

次の例は、 .png ファイルでのみトリガーします。

"path": "samples/{name}.png",

ファイル名の中かっこのフィルター

ファイル名の中かっこを検索するには、2 つの中かっこを使用して中かっこをエスケープします。 次の例は、名前に中かっこを含む BLOB をフィルター処理します。

"path": "images/{{20140101}}-{name}",

BLOB の名前が {20140101}-soundfile.mp3 の場合、関数コード内の name 変数の値は soundfile.mp3 です。

Metadata

BLOB トリガーは、いくつかのメタデータ プロパティを提供します。 これらのプロパティは、他のバインドのバインド式の一部として、またはコードのパラメーターとして使用できます。 これらの値は、CloudBlob 型と同じセマンティクスを持ちます。

プロパティ Type 説明
BlobTrigger string トリガーする BLOB のパス。
Uri System.Uri プライマリ ロケーションの BLOB URI。
Properties BlobProperties Blob のシステム プロパティ。
Metadata IDictionary<string,string> BLOB のユーザー定義メタデータ。

たとえば、次の C# スクリプトと JavaScript の例では、トリガーする BLOBへのパスがログに記録されます (コンテナーを含む)。

public static void Run(string myBlob, string blobTrigger, ILogger log)
{
    log.LogInformation($"Full blob path: {blobTrigger}");
} 

BLOB の配信確認メッセージ

Azure Functions ランタイムでは、BLOB トリガー関数は、同一の新規または更新された BLOB について 2 回以上呼び出されることはありません。 特定の BLOB バージョンが処理されているかどうかを判断するために、BLOB の配信確認メッセージ が維持されます。

Azure Functions では、BLOB の配信確認メッセージは (アプリ設定 AzureWebJobsStorage で指定した) 関数アプリの Azure ストレージ アカウント内の azure-webjobs-hosts というコンテナーに格納されます。 BLOB の配信確認メッセージには次の情報が含まれています。

  • トリガーされた関数 (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME>。例: MyFunctionApp.Functions.CopyBlob)
  • コンテナーの名前
  • BLOB の種類 (BlockBlob または PageBlob)。
  • BLOB の名前
  • ETag (BLOB のバージョン識別子。例: 0x8D1DC6E70A277EF)

BLOB を強制的に再処理する場合は、azure-webjobs-hosts コンテナーからその BLOB の配信確認メッセージを手動で削除します。 再処理がすぐに行われない場合がありますが、後で必ず行われます。 すぐに再処理するには、azure-webjobs-hosts/blobscaninfo 内の scaninfo BLOB を更新できます。 LatestScan プロパティの後に最後に変更されたタイムスタンプを持つすべての BLOB が再びスキャンされます。

有害な BLOB

指定された BLOB に対する BLOB トリガー関数が失敗すると、Azure Functions は既定で最大 5 回その関数を再試行します。

試行が 5 回とも失敗した場合、Azure Functions は webjobs-blobtrigger-poison という名前のストレージ キューにメッセージを追加します。 再試行回数の最大値の設定は変更可能です。 同じ MaxDequeueCount 設定は、有害な BLOB の処理と有害キュー メッセージの処理に使用されます。 有害な BLOB のキュー メッセージは次のプロパティを持つ JSON オブジェクトです。

  • FunctionId (<FUNCTION_APP_NAME>.Functions.<FUNCTION_NAME> の形式)
  • BlobType (BlockBlob または PageBlob)
  • コンテナー名
  • BlobName
  • ETag (BLOB のバージョン識別子。例: 0x8D1DC6E70A277EF)

コンカレンシーとメモリ使用量

BLOB トリガーはキューを内部的に使用するため、関数の同時呼び出しの最大数が host.json のキュー構成設定によって制御されます。 既定の設定では、コンカレンシーの数は 24 までに制限されています。 この制限は、BLOB トリガーを使用する各関数に個別に適用されます。

注意

バージョン 5.0.0 以降の Storage 拡張機能を使用しているアプリの場合、host.js のキューの構成はキュー トリガーにのみ適用されます。 BLOB トリガーのコンカレンシーは、代わりに host.js の BLOB 構成によって制御されます。

従量課金プランでは、1 つの仮想マシン (VM) の関数アプリのメモリが 1.5 GB に制限されています。 メモリは、同時実行される各関数インスタンスと、Functions ランタイム自体によって使用されます。 BLOB によってトリガーされる関数が BLOB 全体をメモリに読み込む場合、その関数が BLOB 用にのみ使用するメモリの最大量は 24 * 最大 BLOB サイズです。 たとえば、BLOB によってトリガーされる 3 つの関数を含む関数アプリの場合、既定の設定では、VM あたりの最大コンカレンシー数 3*24 = 72 関数呼び出しとなります。

JavaScript と Java の関数では BLOB 全体がメモリに読み込まれますが、C# 関数では string、または Byte[] にバインドした場合にこれが行われます。

host.json プロパティ

host.json ファイルには、BLOB トリガーの動作を制御する設定が含まれています。 使用可能な設定の詳細については、「host.json 設定」を参照してください。

次のステップ