Azure Functions における Azure Queue storage のトリガーとバインドの概要

  • [アーティクル]

Azure Functions は、新しい Azure Queue storage メッセージが作成されたときに実行でき、関数内でキュー メッセージを書き込むことができます。

アクション 種類
キュー ストレージのデータが変更されたときに関数を実行する トリガー
キュー ストレージ メッセージを書き込む 出力バインド

拡張機能のインストール

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

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

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

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

このバージョンでは、Azure.Storage.Queues からの型にバインドできます。

NuGet パッケージ バージョン 5.x をインストールすることによって、プロジェクトに拡張機能を追加します。

.NET CLI の使用

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues --version 5.0.0

注意

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

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

バンドルのインストール

BLOB ストレージのバインドは、host.json プロジェクト ファイルで指定される拡張機能バンドルの一部です。 このバンドルは、バインドのバージョンを変更するために、またはバンドルがまだインストールされていない場合に変更が必要になることがあります。 詳細については、「拡張機能のバンドル」を参照してください。

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

このバージョンの拡張機能は、host.json ファイルで次のコードを追加するか、または置き換えることによって、プレビュー拡張機能バンドル v3 から追加できます。

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

詳細については、ユーザーの更新に関するページを参照してください。

バインドの種類

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

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

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

分離ワーカー プロセスでは、以下の表に従ってパラメーターの型がサポートされています。 Azure.Storage.Queues の型へのバインドのサポートはプレビュー段階です。

キュー トリガー

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

Type 説明
string メッセージの内容を表す文字列。 メッセージが単純なテキストである場合に使用します。
byte[] メッセージのバイト数。
JSON シリアル化可能な型 キュー メッセージに JSON データが含まれている場合、Functions は JSON データを単純な従来の CLR オブジェクト (POCO) 型に逆シリアル化しようとします。
QueueMessage1 メッセージ。
BinaryData1 メッセージのバイト数。

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

キュー出力バインド

関数で 1 つのメッセージを書き込む場合、キュー出力バインドは次の型にバインドできます

Type 説明
string メッセージの内容を表す文字列。 メッセージが単純なテキストである場合に使用します。
byte[] メッセージのバイト数。
JSON シリアル化可能な型 JSON メッセージの内容を表すオブジェクト。 Functions は、単純な従来の CLR オブジェクト (POCO) 型を JSON データにシリアル化しようとします。

関数で複数のメッセージを書き込む場合、キュー出力バインドは次の型にバインドできます

Type 説明
T[] (T は単一メッセージ型の 1 つ) 複数のメッセージの内容を含む配列。 各エントリは 1 つのメッセージを表します。

その他の出力シナリオでは、Azure.Storage.Queues から型を直接作成して使用します。

host.json 設定

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

Note

Functions 1.x の host.json のリファレンスについては、「host.json reference for Azure Functions 1.x (Azure Functions 1.x の host.json のリファレンス)」を参照してください。

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
プロパティ Default 説明
maxPollingInterval 00:01:00 キューのポーリングの最大間隔。 最小間隔は 00:00:00.100 (100 ミリ秒) です。 間隔は、maxPollingInterval を上限としてインクリメントされます。 maxPollingInterval の既定値は 00:01:00 (1 分) です。 maxPollingInterval は 00:00:00.100 (100 ミリ秒) 以上であることが必要です。 Functions 2.x 以降では、データ型は TimeSpan です。 Functions 1.x では、ミリ秒単位となります。
visibilityTimeout 00:00:00 メッセージの処理が失敗したときの再試行間隔。
batchSize 16 Functions ランタイムが同時に取得して並列で処理するキュー メッセージの数。 処理中のメッセージの数が newBatchThreshold まで減少すると、ランタイムは は別のバッチを取得し、そのメッセージの処理を開始します。 そのため、1 つの関数につき同時に処理されるメッセージの最大数は、batchSize に newBatchThreshold を加えた値です。 この制限は、キューによってトリガーされる各関数に個別に適用されます。

1 つのキューで受信した複数のメッセージの並列実行を回避したい場合は、batchSize を 1 に設定します。 ただし、この設定では、関数アプリが単一の仮想マシン (VM) で実行されている限り、コンカレンシーは実現しません。 この関数アプリを複数の VM にスケール アウトすると、各 VM では、キューによってトリガーされる関数ごとに 1 つのインスタンスを実行できます。

最大の batchSize は 32 です。
maxDequeueCount 5 有害キューに移動する前に、メッセージの処理を試行する回数。
newBatchThreshold N*batchSize/2 同時に処理されているメッセージの数がこの数まで減少すると、ランタイムは別のバッチを取得します。

N は、App Service または Premium プランで実行されている場合に使用可能な vCPU の数を表します。 この値は従量課金プランで 1 です。
messageEncoding base64 この設定は、バージョン 5.0.0 以降の拡張機能のバンドルでのみ使用できます。 これは、メッセージのエンコード形式を表します。 有効値は base64 または none です。

次のステップ