Azure Functions のバインド式のパターンAzure Functions binding expression patterns

トリガーとバインドの最も強力な機能の 1 つは、"バインド式" です。One of the most powerful features of triggers and bindings is binding expressions. function.json ファイルおよび関数パラメーターとコードでは、さまざまなソースの値に解決される式を使用できます。In the function.json file and in function parameters and code, you can use expressions that resolve to values from various sources.

ほとんどの式は、それを中かっこで囲むことによって識別されます。Most expressions are identified by wrapping them in curly braces. たとえば、キュー トリガー関数では、{queueTrigger} はキュー メッセージ テキストに解決されます。For example, in a queue trigger function, {queueTrigger} resolves to the queue message text. BLOB 出力バインディングの path プロパティが container/{queueTrigger} であり、その関数がキュー メッセージ HelloWorld によってトリガーされる場合は、HelloWorld という名前の BLOB が作成されます。If the path property for a blob output binding is container/{queueTrigger} and the function is triggered by a queue message HelloWorld, a blob named HelloWorld is created.

バインディング式の種類Types of binding expressions

バインディング式 - アプリ設定Binding expressions - app settings

ベスト プラクティスとしては、シークレットや接続文字列は、構成ファイルではなくアプリ設定を使用して管理する必要があります。As a best practice, secrets and connection strings should be managed using app settings, rather than configuration files. これにより、これらのシークレットへのアクセスが制限され、function.json などのファイルをパブリックなソース管理リポジトリに格納することが安全になります。This limits access to these secrets and makes it safe to store files such as function.json in public source control repositories.

環境に基づいて構成を変更するときには、アプリ設定も常に役立ちます。App settings are also useful whenever you want to change configuration based on the environment. たとえば、テスト環境で、別のキューや Blob Storage コンテナーを監視することもできます。For example, in a test environment, you may want to monitor a different queue or blob storage container.

アプリ設定のバインディング式は、他のバインディング式とはさまざまに区別されます。これらは中かっこではなく、パーセント記号で囲まれます。App setting binding expressions are identified differently from other binding expressions: they are wrapped in percent signs rather than curly braces. たとえば、BLOB 出力バインディング パスが %Environment%/newblob.txt であり、Environment アプリ設定値が Development である場合は、BLOB が Development コンテナー内に作成されます。For example if the blob output binding path is %Environment%/newblob.txt and the Environment app setting value is Development, a blob will be created in the Development container.

関数がローカルに実行されている場合、アプリ設定値は local.settings.json ファイルから来ます。When a function is running locally, app setting values come from the local.settings.json file.

トリガーとバインディングの connection プロパティは特殊なケースであり、値をアプリ設定 (パーセント記号なし) として自動的に解決することに注意してください。Note that the connection property of triggers and bindings is a special case and automatically resolves values as app settings, without percent signs.

次の例は、アプリ設定 %input-queue-name% を使用してトリガーの対象となるキューを定義する Azure Queue Storage トリガーです。The following example is an Azure Queue Storage trigger that uses an app setting %input-queue-name% to define the queue to trigger on.

{
  "bindings": [
    {
      "name": "order",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "%input-queue-name%",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    }
  ]
}

クラス ライブラリでも同じ方法を使用できます。You can use the same approach in class libraries:

[FunctionName("QueueTrigger")]
public static void Run(
    [QueueTrigger("%input-queue-name%")]string myQueueItem, 
    ILogger log)
{
    log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
}

トリガー ファイル名Trigger file name

BLOB トリガーの path は、他のバインディングや関数コード内のトリガー BLOB の名前を参照するために使用できるパターンにすることができます。The path for a Blob trigger can be a pattern that lets you refer to the name of the triggering blob in other bindings and function code. このパターンにはまた、どの BLOB が関数呼び出しをトリガーできるかを指定するフィルター条件を含めることもできます。The pattern can also include filtering criteria that specify which blobs can trigger a function invocation.

たとえば、次の BLOB トリガーのバインディングでは、path パターンは sample-images/{filename} です。これは、filename という名前のバインディング式を作成します。For example, in the following Blob trigger binding, the path pattern is sample-images/{filename}, which creates a binding expression named filename:

{
  "bindings": [
    {
      "name": "image",
      "type": "blobTrigger",
      "path": "sample-images/{filename}",
      "direction": "in",
      "connection": "MyStorageConnection"
    },
    ...

その後、出力バインディングで式 filename を使用して、作成される BLOB の名前を指定できます。The expression filename can then be used in an output binding to specify the name of the blob being created:

    ...
    {
      "name": "imageSmall",
      "type": "blob",
      "path": "sample-images-sm/{filename}",
      "direction": "out",
      "connection": "MyStorageConnection"
    }
  ],
}

関数コードは、filename をパラメーター名として使用して、この同じ値にアクセスできます。Function code has access to this same value by using filename as a parameter name:

// C# example of binding to {filename}
public static void Run(Stream image, string filename, Stream imageSmall, ILogger log)  
{
    log.LogInformation($"Blob trigger processing: {filename}");
    // ...
} 

バインド式とパターンを使用するのと同じ機能がクラス ライブラリの属性に適用されます。The same ability to use binding expressions and patterns applies to attributes in class libraries. 次の例では、属性コンストラクター パラメーターは前の function.json の例と同じ path 値です。In the following example, the attribute constructor parameters are the same path values as the preceding function.json examples:

[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}");
    // ...
}

また、拡張機能などのファイル名の一部のための式を作成することもできます。You can also create expressions for parts of the file name such as the extension. 式を使用する方法および BLOB パス文字列内のパターンの詳細については、ストレージ BLOB バインディングのリファレンスに関するページを参照してください。For more information on how to use expressions and patterns in the Blob path string, see the Storage blob binding reference.

トリガー メタデータTrigger metadata

トリガーによって提供されるデータ ペイロード (関数をトリガーしたキュー メッセージの内容など) に加え、多くのトリガーは追加のメタデータ値を提供します。In addition to the data payload provided by a trigger (such as the content of the queue message that triggered a function), many triggers provide additional metadata values. これらの値は、C# および F# で入力パラメーターとして使用したり、JavaScript で context.bindings オブジェクトのプロパティとして使用したりできます。These values can be used as input parameters in C# and F# or properties on the context.bindings object in JavaScript.

たとえば、Azure Queue Storage トリガーは、以下のプロパティをサポートしています。For example, an Azure Queue storage trigger supports the following properties:

  • QueueTrigger - 有効な文字列の場合はメッセージの内容をトリガーしますQueueTrigger - triggering message content if a valid string
  • DequeueCountDequeueCount
  • ExpirationTimeExpirationTime
  • IdId
  • InsertionTimeInsertionTime
  • NextVisibleTimeNextVisibleTime
  • PopReceiptPopReceipt

これらのメタデータ値は、function.json ファイルのプロパティでアクセスできます。These metadata values are accessible in function.json file properties. たとえば、キュー トリガーを使用していて、読み取る BLOB の名前がキュー メッセージに含まれているとします。For example, suppose you use a queue trigger and the queue message contains the name of a blob you want to read. 次の例に示すように、function.json ファイルで、BLOB path プロパティの queueTrigger メタデータ プロパティを使用できます。In the function.json file, you can use queueTrigger metadata property in the blob path property, as shown in the following example:

  "bindings": [
    {
      "name": "myQueueItem",
      "type": "queueTrigger",
      "queueName": "myqueue-items",
      "connection": "MyStorageConnection",
    },
    {
      "name": "myInputBlob",
      "type": "blob",
      "path": "samples-workitems/{queueTrigger}",
      "direction": "in",
      "connection": "MyStorageConnection"
    }
  ]

各トリガーのメタデータ プロパティの詳細については、対応するリファレンス記事を参照してください。Details of metadata properties for each trigger are described in the corresponding reference article. 例については、キュー トリガー メタデータに関するセクションを参照してください。For an example, see queue trigger metadata. ドキュメントは、ポータルの [統合] タブの、バインド構成領域の下の [ドキュメント] セクションでも参照できます。Documentation is also available in the Integrate tab of the portal, in the Documentation section below the binding configuration area.

JSON ペイロードJSON payloads

トリガー ペイロードが JSON である場合は、同じ関数および関数コードで、他のバインディング用の構成内のそのプロパティを参照できます。When a trigger payload is JSON, you can refer to its properties in configuration for other bindings in the same function and in function code.

次の例は、JSON での BLOB 名を受信する Webhook 関数の function.json ファイルを示しています: {"BlobName":"HelloWorld.txt"}The following example shows the function.json file for a webhook function that receives a blob name in JSON: {"BlobName":"HelloWorld.txt"}. BLOB 入力バインディングが BLOB を読み取り、HTTP 出力バインディングが HTTP 応答で BLOB コンテンツを返します。A Blob input binding reads the blob, and the HTTP output binding returns the blob contents in the HTTP response. BLOB 入力バインディングが BlobName プロパティ ("path": "strings/{BlobName}") を直接参照することによって BLOB 名を取得していることに注意してください。Notice that the Blob input binding gets the blob name by referring directly to the BlobName property ("path": "strings/{BlobName}")

{
  "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# でこれが機能するには、次の例に示すように、逆シリアル化されるフィールドを定義するクラスが必要です。For this to work in C# and F#, you need a class that defines the fields to be deserialized, as in the following example:

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 の逆シリアル化が自動的に実行されます。In JavaScript, JSON deserialization is automatically performed.

module.exports = function (context, info) {
    if ('BlobName' in info) {
        context.res = {
            body: { 'data': context.bindings.blobContents }
        }
    }
    else {
        context.res = {
            status: 404
        };
    }
    context.done();
}

ドット表記Dot notation

JSON ペイロード内のいくつかのプロパティがプロパティを持つオブジェクトである場合は、ドット表記を使用してこれらを直接参照できます。If some of the properties in your JSON payload are objects with properties, you can refer to those directly by using dot notation. たとえば、次のような JSON があるとします。For example, suppose your JSON looks like this:

{
  "BlobName": {
    "FileName":"HelloWorld",
    "Extension":"txt"
  }
}

FileNameBlobName.FileName として直接参照できます。You can refer directly to FileName as BlobName.FileName. この JSON 形式では、前の例の path プロパティは次のようになります。With this JSON format, here's what the path property in the preceding example would look like:

"path": "strings/{BlobName.FileName}.{BlobName.Extension}",

C# では、次の 2 つのクラスが必要になります。In C#, you would need two classes:

public class BlobInfo
{
    public BlobName BlobName { get; set; }
}
public class BlobName
{
    public string FileName { get; set; }
    public string Extension { get; set; }
}

GUID の作成Create GUIDs

{rand-guid} バインド式は GUID を作成します。The {rand-guid} binding expression creates a GUID. function.json ファイル内の次の BLOB パスは、50710cb5-84b9-4d87-9d83-a03d6976a682.txt などの名前を持つ BLOB を作成します。The following blob path in a function.json file creates a blob with a name like 50710cb5-84b9-4d87-9d83-a03d6976a682.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{rand-guid}"
}

現在の時刻Current time

バインド式 DateTimeDateTime.UtcNow に解決されます。The binding expression DateTime resolves to DateTime.UtcNow. function.json ファイル内の次の BLOB パスは、2018-02-16T17-59-55Z.txt などの名前を持つ BLOB を作成します。The following blob path in a function.json file creates a blob with a name like 2018-02-16T17-59-55Z.txt.

{
  "type": "blob",
  "name": "blobOutput",
  "direction": "out",
  "path": "my-output-container/{DateTime}"
}

実行時のバインドBinding at runtime

C# やその他の .NET 言語では、function.json の宣言型のバインドと属性ではなく、命令型のバインド パターンを使用できます。In C# and other .NET languages, you can use an imperative binding pattern, as opposed to the declarative bindings in function.json and attributes. 命令型のバインドは、設計時ではなくランタイム時にバインド パラメーターを計算する必要がある場合に便利です。Imperative binding is useful when binding parameters need to be computed at runtime rather than design time. 詳細については、C# 開発者向けリファレンスまたはC# スクリプト開発者向けリファレンスを参照してください。To learn more, see the C# developer reference or the C# script developer reference.

次の手順Next steps