Azure Functions のバインド式のパターン

[アーティクル]
06/01/2023

トリガーとバインドの最も強力な機能の 1 つは、"バインド式" です。 function.json ファイルおよび関数パラメーターとコードでは、さまざまなソースの値に解決される式を使用できます。

ほとんどの式は、それを中かっこで囲むことによって識別されます。たとえば、キュートリガー関数では、{queueTrigger} はキューメッセージテキストに解決されます。 BLOB 出力バインディングの path プロパティが container/{queueTrigger} であり、その関数がキューメッセージ HelloWorld によってトリガーされる場合は、HelloWorld という名前の BLOB が作成されます。

バインディング式の種類

アプリ設定
トリガーファイル名
トリガーメタデータ
JSON ペイロード
新しい GUID
現在の日付と時刻

バインディング式 - アプリ設定

ベストプラクティスとしては、シークレットや接続文字列は、構成ファイルではなくアプリ設定を使用して管理する必要があります。これにより、これらのシークレットへのアクセスが制限され、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 プロパティのメタデータプロパティを使用できます。

{
  "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 ファイルを示しています: 。 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# スクリプト開発者向けリファレンスを参照してください。

次のステップ

Azure 関数の戻り値の使用