Azure Functions のバインド式のパターン
トリガーとバインドの最も強力な機能の 1 つは、"バインド式" です。 function.json ファイルおよび関数パラメーターとコードでは、さまざまなソースの値に解決される式を使用できます。
ほとんどの式は、それを中かっこで囲むことによって識別されます。 たとえば、キュー トリガー関数では、{queueTrigger}
はキュー メッセージ テキストに解決されます。 BLOB 出力バインディングの path
プロパティが container/{queueTrigger}
であり、その関数がキュー メッセージ HelloWorld
によってトリガーされる場合は、HelloWorld
という名前の BLOB が作成されます。
バインディング式の種類
バインディング式 - アプリ設定
ベスト プラクティスとしては、シークレットや接続文字列は、構成ファイルではなくアプリ設定を使用して管理する必要があります。 これにより、これらのシークレットへのアクセスが制限され、function.json などのファイルをパブリックなソース管理リポジトリに格納することが安全になります。
環境に基づいて構成を変更するときには、アプリ設定も常に役立ちます。 たとえば、テスト環境で、別のキューや Blob Storage コンテナーを監視することもできます。
アプリ設定のバインディング式は、他のバインディング式とはさまざまに区別されます。これらは中かっこではなく、パーセント記号で囲まれます。 たとえば、BLOB 出力バインディング パスが %Environment%/newblob.txt
であり、Environment
アプリ設定値が Development
である場合は、BLOB が Development
コンテナー内に作成されます。
関数がローカルに実行されている場合、アプリ設定値は local.settings.json ファイルから来ます。
Note
トリガーとバインディングの connection
プロパティは特殊なケースであり、値はアプリ設定 (パーセント記号なし) として自動的に解決されます。
次の例は、アプリ設定 %input_queue_name%
を使用してトリガーの対象となるキューを定義する Azure Queue Storage トリガーです。
{
"bindings": [
{
"name": "order",
"type": "queueTrigger",
"direction": "in",
"queueName": "%input_queue_name%",
"connection": "MY_STORAGE_ACCT_APP_SETTING"
}
]
}
クラス ライブラリでも同じ方法を使用できます。
[FunctionName("QueueTrigger")]
public static void Run(
[QueueTrigger("%input_queue_name%")]string myQueueItem,
ILogger log)
{
log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
}
トリガー ファイル名
BLOB トリガーの path
は、他のバインディングや関数コード内のトリガー BLOB の名前を参照するために使用できるパターンにすることができます。 このパターンにはまた、どの BLOB が関数呼び出しをトリガーできるかを指定するフィルター条件を含めることもできます。
たとえば、次の BLOB トリガーのバインディングでは、path
パターンは sample-images/{filename}
です。これは、filename
という名前のバインディング式を作成します。
{
"bindings": [
{
"name": "image",
"type": "blobTrigger",
"path": "sample-images/{filename}",
"direction": "in",
"connection": "MyStorageConnection"
},
...
その後、出力バインディングで式 filename
を使用して、作成される BLOB の名前を指定できます。
...
{
"name": "imageSmall",
"type": "blob",
"path": "sample-images-sm/{filename}",
"direction": "out",
"connection": "MyStorageConnection"
}
],
}
関数コードは、filename
をパラメーター名として使用して、この同じ値にアクセスできます。
// C# example of binding to {filename}
public static void Run(Stream image, string filename, Stream imageSmall, ILogger log)
{
log.LogInformation($"Blob trigger processing: {filename}");
// ...
}
バインド式とパターンを使用するのと同じ機能がクラス ライブラリの属性に適用されます。 次の例では、属性コンストラクター パラメーターは前の path
の例と同じ path
値です。
[FunctionName("ResizeImage")]
public static void Run(
[BlobTrigger("sample-images/{filename}")] Stream image,
[Blob("sample-images-sm/{filename}", FileAccess.Write)] Stream imageSmall,
string filename,
ILogger log)
{
log.LogInformation($"Blob trigger processing: {filename}");
// ...
}
また、ファイル名の一部のための式を作成することもできます。 次の例の関数は、パターン (anyname-anyfile.csv
) に一致するファイル名でのみトリガーされます。
{
"name": "myBlob",
"type": "blobTrigger",
"direction": "in",
"path": "testContainerName/{date}-{filetype}.csv",
"connection": "OrderStorageConnection"
}
式を使用する方法および BLOB パス文字列内のパターンの詳細については、ストレージ BLOB バインディングのリファレンスに関するページを参照してください。
トリガー メタデータ
トリガーによって提供されるデータ ペイロード (関数をトリガーしたキュー メッセージの内容など) に加え、多くのトリガーは追加のメタデータ値を提供します。 これらの値は、C# および F# で入力パラメーターとして使用したり、JavaScript で context.bindings
オブジェクトのプロパティとして使用したりできます。
たとえば、Azure Queue Storage トリガーは、以下のプロパティをサポートしています。
- QueueTrigger - 有効な文字列の場合はメッセージの内容をトリガーします
- DequeueCount
- ExpirationTime
- Id
- InsertionTime
- NextVisibleTime
- PopReceipt
これらのメタデータ値は、function.json ファイルのプロパティでアクセスできます。 たとえば、キュー トリガーを使用していて、読み取る BLOB の名前がキュー メッセージに含まれているとします。 次の例に示すように、function.json ファイルで、BLOB path
プロパティの queueTrigger
メタデータ プロパティを使用できます。
{
"bindings": [
{
"name": "myQueueItem",
"type": "queueTrigger",
"queueName": "myqueue-items",
"connection": "MyStorageConnection",
},
{
"name": "myInputBlob",
"type": "blob",
"path": "samples-workitems/{queueTrigger}",
"direction": "in",
"connection": "MyStorageConnection"
}
]
}
各トリガーのメタデータ プロパティの詳細については、対応するリファレンス記事を参照してください。 例については、キュー トリガー メタデータに関するセクションを参照してください。 ドキュメントは、ポータルの [統合] タブの、バインド構成領域の下の [ドキュメント] セクションでも参照できます。
JSON ペイロード
一部のシナリオでは、同じ関数と関数コード内の他のバインドの構成で、トリガー ペイロードのプロパティを参照できます。 これには、トリガー ペイロードが JSON であり、各トリガーに固有のしきい値よりも小さいことが必要です。 通常、ペイロード サイズは 100 MB 未満にする必要がありますが、各トリガーの参照コンテンツを確認する必要があります。 トリガー ペイロードのプロパティを使用すると、アプリケーションのパフォーマンスに影響を与える可能性があり、トリガー パラメーターの型は、文字列や JSON データを表すカスタム オブジェクト型などの単純な型に強制されます。 ストリーム、クライアント、またはその他の SDK の種類では使用できません。
次の例は、JSON での BLOB 名を受信する Webhook 関数の function.json ファイルを示しています: {"BlobName":"HelloWorld.txt"}
。 BLOB 入力バインディングが BLOB を読み取り、HTTP 出力バインディングが HTTP 応答で BLOB コンテンツを返します。 BLOB 入力バインディングが BlobName
プロパティ ("path": "strings/{BlobName}"
) を直接参照することによって BLOB 名を取得していることに注意してください。
{
"bindings": [
{
"name": "info",
"type": "httpTrigger",
"direction": "in",
"webHookType": "genericJson"
},
{
"name": "blobContents",
"type": "blob",
"direction": "in",
"path": "strings/{BlobName}",
"connection": "AzureWebJobsStorage"
},
{
"name": "res",
"type": "http",
"direction": "out"
}
]
}
C# および F# でこれが機能するには、次の例に示すように、逆シリアル化されるフィールドを定義するクラスが必要です。
using System.Net;
using Microsoft.Extensions.Logging;
public class BlobInfo
{
public string BlobName { get; set; }
}
public static HttpResponseMessage Run(HttpRequestMessage req, BlobInfo info, string blobContents, ILogger log)
{
if (blobContents == null) {
return req.CreateResponse(HttpStatusCode.NotFound);
}
log.LogInformation($"Processing: {info.BlobName}");
return req.CreateResponse(HttpStatusCode.OK, new {
data = $"{blobContents}"
});
}
JavaScript では、JSON の逆シリアル化が自動的に実行されます。
module.exports = async function (context, info) {
if ('BlobName' in info) {
context.res = {
body: { 'data': context.bindings.blobContents }
}
}
else {
context.res = {
status: 404
};
}
}
ドット表記
JSON ペイロード内の一部のプロパティがプロパティを持つオブジェクトである場合は、ドット (.
) 表記を使用してこれらを直接参照できます。 この表記は、Azure Cosmos DB または Table Storage のバインドでは機能しません。
たとえば、次のような JSON があるとします。
{
"BlobName": {
"FileName":"HelloWorld",
"Extension":"txt"
}
}
FileName
を BlobName.FileName
として直接参照できます。 この JSON 形式では、前の例の path
プロパティは次のようになります。
"path": "strings/{BlobName.FileName}.{BlobName.Extension}",
C# では、次の 2 つのクラスが必要になります。
public class BlobInfo
{
public BlobName BlobName { get; set; }
}
public class BlobName
{
public string FileName { get; set; }
public string Extension { get; set; }
}
GUID の作成
{rand-guid}
バインド式は GUID を作成します。 function.json
ファイル内の次の BLOB パスは、function.json
などの名前を持つ BLOB を作成します。
{
"type": "blob",
"name": "blobOutput",
"direction": "out",
"path": "my-output-container/{rand-guid}.txt"
}
現在の時刻
バインド式 DateTime
は DateTime.UtcNow
に解決されます。 function.json
ファイル内の次の BLOB パスは、function.json
などの名前を持つ BLOB を作成します。
{
"type": "blob",
"name": "blobOutput",
"direction": "out",
"path": "my-output-container/{DateTime}.txt"
}
実行時のバインド
C# やその他の .NET 言語では、function.json の宣言型のバインドと属性ではなく、命令型のバインド パターンを使用できます。 命令型のバインドは、設計時ではなくランタイム時にバインド パラメーターを計算する必要がある場合に便利です。 詳細については、C# 開発者向けリファレンスまたはC# スクリプト開発者向けリファレンスを参照してください。