Azure Functions でのトリガーとバインドの概念Azure Functions triggers and bindings concepts

この記事では、Azure Functions のトリガーとバインドの概念的な概要を説明します。This article is a conceptual overview of triggers and bindings in Azure Functions. ここでは、すべてのバインドとすべてのサポートされている言語に共通する機能について説明します。Features that are common to all bindings and all supported languages are described here.

概要Overview

トリガーは、関数を呼び出す方法を定義します。A trigger defines how a function is invoked. 1 つの関数には 1 つのトリガーしか含められません。A function must have exactly one trigger. トリガーにはデータが関連付けられていて、通常そのデータは、その関数をトリガーしたペイロードです。Triggers have associated data, which is usually the payload that triggered the function.

入出力バインドによって、コード内からデータに接続する宣言型の方法が提供されます。Input and output bindings provide a declarative way to connect to data from within your code. バインドは省略可能で、関数は複数の入出力バインドを持つことができます。Bindings are optional and a function can have multiple input and output bindings.

トリガーとバインドを使用すると、操作するサービスの詳細をハードコードする必要がなくなります。Triggers and bindings let you avoid hardcoding the details of the services that you're working with. 関数は、関数パラメーターでデータ (キュー メッセージの内容など) を受け取ります。You function receives data (for example, the content of a queue message) in function parameters. 関数の戻り値、out パラメーター、またはコレクター オブジェクトを使用して、(たとえば、キュー メッセージを作成するために) データを送信します。You send data (for example, to create a queue message) by using the return value of the function, an out parameter, or a collector object.

Azure Portal を使用して関数を開発する場合、トリガーとバインドは function.json ファイルに構成されます。When you develop functions by using the Azure portal, triggers and bindings are configured in a function.json file. ポータルではこの構成のために UI が提供されますが、詳細エディターに切り替えることで直接ファイルを編集できます。The portal provides a UI for this configuration but you can edit the file directly by changing to the Advanced editor.

Visual Studio を使用してクラス ライブラリを作成して関数を開発する場合は、メソッドとパラメーターを属性で修飾してトリガーとバインドを構成します。When you develop functions by using Visual Studio to create a class library, you configure triggers and bindings by decorating methods and parameters with attributes.

サポートされるバインディングSupported bindings

次の表は、Azure Functions の 2 つのメジャー バージョンのランタイムでサポートされているバインディングを示します。The following table shows the bindings that are supported in the two major versions of the Azure Functions runtime.

Type 1.x1.x 2.x2.x トリガーTrigger 入力Input 出力Output
Blob StorageBlob Storage
Cosmos DBCosmos DB 11
Event HubsEvent Hubs
外部ファイル 2External File2
外部テーブル 2External Table2
HTTPHTTP
Microsoft Graph
Excel テーブル
Microsoft Graph
Excel tables
11
Microsoft Graph
OneDrive ファイル
Microsoft Graph
OneDrive files
11
Microsoft Graph
Outlook メール
Microsoft Graph
Outlook email
11
Microsoft Graph
Events
Microsoft Graph
Events
11
Microsoft Graph
Auth トークン
Microsoft Graph
Auth tokens
11
Mobile AppsMobile Apps 11
Notification HubsNotification Hubs
Queue StorageQueue storage
SendGridSendGrid 11
Service BusService Bus 11
Table StorageTable storage
TimerTimer
TwilioTwilio 11
WebhookWebhooks

1 2.x にバインディング拡張として登録する必要があります。1 Must be registered as a binding extension in 2.x. 2.x の既知の問題を参照してください。See Known issues in 2.x.

2 実験的 — サポート対象外で、将来破棄される可能性があります。2 Experimental — not supported and might be abandoned in the future.

どのバインディングがプレビューでどのバインディングが実稼働環境で承認されているかについては、サポートされている言語に関する記事をご覧ください。For information about which bindings are in preview or are approved for production use, see Supported languages.

例: キュー トリガーとテーブルの出力バインドExample: queue trigger and table output binding

Azure Queue Storage に新しいメッセージが表示されるたびに Azure Table Storage に新しい行を書き込むとします。Suppose you want to write a new row to Azure Table storage whenever a new message appears in Azure Queue storage. このシナリオは、Azure Queue Storage トリガーと Azure Table Storage の出力バインドを使用して実装できます。This scenario can be implemented using an Azure Queue storage trigger and an Azure Table storage output binding.

このシナリオ用の function.json ファイルを次に示します。Here's a function.json file for this scenario.

{
  "bindings": [
    {
      "name": "order",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "myqueue-items",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    },
    {
      "name": "$return",
      "type": "table",
      "direction": "out",
      "tableName": "outTable",
      "connection": "MY_TABLE_STORAGE_ACCT_APP_SETTING"
    }
  ]
}

bindings 配列の最初の要素は、Queue Storage トリガーです。The first element in the bindings array is the Queue storage trigger. type および direction プロパティは、トリガーを識別します。The type and direction properties identify the trigger. name プロパティは、キュー メッセージの内容を受け取る関数パラメーターを識別します。The name property identifies the function parameter that will receive the queue message content. 監視するキューの名前は queueName に含まれ、接続文字列は connection で識別されるアプリ設定に含まれています。The name of the queue to monitor is in queueName, and the connection string is in the app setting identified by connection.

bindings 配列の 2 番目の要素は、Azure Table Storage の出力バインドです。The second element in the bindings array is the Azure Table Storage output binding. type および direction プロパティは、バインドを識別します。The type and direction properties identify the binding. name プロパティは、関数が新しいテーブル行を提供する方法を指定します。ここでは、関数の戻り値を使用します。The name property specifies how the function will provide the new table row, in this case by using the function return value. テーブルの名前は tableName に含まれ、接続文字列は connection で識別されるアプリ設定に含まれています。The name of the table is in tableName, and the connection string is in the app setting identified by connection.

Azure ポータルで function.json の内容を表示して編集するには、関数の [統合] タブにある [詳細エディター] オプションをクリックします。To view and edit the contents of function.json in the Azure portal, click the Advanced editor option on the Integrate tab of your function.

注意

connection の値は、接続文字列自体ではなく、接続文字列を含むアプリ設定の名前です。The value of connection is the name of an app setting that contains the connection string, not the connection string itself. "function.json にサービス シークレットを含めない" というベスト プラクティスを適用するために、バインドでは、アプリ設定に格納された接続文字列を使用します。Bindings use connection strings stored in app settings to enforce the best practice that function.json does not contain service secrets.

このトリガーとバインドで動作する C# のスクリプト コードを次に示します。Here's C# script code that works with this trigger and binding. キュー メッセージの内容を提供するパラメーターの名前が order であることに注意してください。function.jsonname プロパティ値が order であるため、この名前が必要になります。Notice that the name of the parameter that provides the queue message content is order; this name is required because the name property value in function.json is order

#r "Newtonsoft.Json"

using Newtonsoft.Json.Linq;

// From an incoming queue message that is a JSON object, add fields and write to Table storage
// The method return value creates a new row in Table Storage
public static Person Run(JObject order, TraceWriter log)
{
    return new Person() { 
            PartitionKey = "Orders", 
            RowKey = Guid.NewGuid().ToString(),  
            Name = order["Name"].ToString(),
            MobileNumber = order["MobileNumber"].ToString() };  
}

public class Person
{
    public string PartitionKey { get; set; }
    public string RowKey { get; set; }
    public string Name { get; set; }
    public string MobileNumber { get; set; }
}

同じ function.json ファイルを JavaScript 関数でも使用できます。The same function.json file can be used with a JavaScript function:

// From an incoming queue message that is a JSON object, add fields and write to Table Storage
// The second parameter to context.done is used as the value for the new row
module.exports = function (context, order) {
    order.PartitionKey = "Orders";
    order.RowKey = generateRandomId(); 

    context.done(null, order);
};

function generateRandomId() {
    return Math.random().toString(36).substring(2, 15) +
        Math.random().toString(36).substring(2, 15);
}

クラス ライブラリでは、同じトリガーとバインド情報 (キュー名とテーブル名、ストレージ アカウント、入力と出力の関数パラメーター) が属性によって提供されます。In a class library, the same trigger and binding information — queue and table names, storage accounts, function parameters for input and output — is provided by attributes:

 public static class QueueTriggerTableOutput
 {
     [FunctionName("QueueTriggerTableOutput")]
     [return: Table("outTable", Connection = "MY_TABLE_STORAGE_ACCT_APP_SETTING")]
     public static Person Run(
         [QueueTrigger("myqueue-items", Connection = "MY_STORAGE_ACCT_APP_SETTING")]JObject order, 
         TraceWriter log)
     {
         return new Person() {
                 PartitionKey = "Orders",
                 RowKey = Guid.NewGuid().ToString(),
                 Name = order["Name"].ToString(),
                 MobileNumber = order["MobileNumber"].ToString() };
     }
 }

 public class Person
 {
     public string PartitionKey { get; set; }
     public string RowKey { get; set; }
     public string Name { get; set; }
     public string MobileNumber { get; set; }
 }

バインドの方向Binding direction

すべてのトリガーとバインドには、function.json ファイルに direction プロパティがあります。All triggers and bindings have a direction property in the function.json file:

  • トリガーの場合、方向は常に in ですFor triggers, the direction is always in
  • 入出力バインドは inout を使用しますInput and output bindings use in and out
  • 一部のバインドは、特殊な方向の inout をサポートしてします。Some bindings support a special direction inout. inout を使用する場合、[統合] タブで使用できるのは詳細エディターのみです。If you use inout, only the Advanced editor is available in the Integrate tab.

クラス ライブラリの属性を使用してトリガーとバインドを構成した場合、その方向は属性コンストラクターで提供されるか、またはパラメーター型から推論されます。When you use attributes in a class library to configure triggers and bindings, the direction is provided in an attribute constructor or inferred from the parameter type.

単一出力を返すための関数の戻り値の型の使用Using the function return type to return a single output

前の例は、関数の戻り値を使用してバインドに出力を提供する方法を示しています。これは、name プロパティの特殊値 $return を使用して function.json に指定されています The preceding example shows how to use the function return value to provide output to a binding, which is specified in function.json by using the special value $return for the name property. (これは、C# スクリプト、JavaScript、F# などの、戻り値がある言語でのみサポートされています)。1 つの関数に複数の出力バインドがある場合は、1 つの出力バインドに対してのみ $return を使用します。(This is only supported in languages that have a return value, such as C# script, JavaScript, and F#.) If a function has multiple output bindings, use $return for only one of the output bindings.

// excerpt of function.json
{
    "name": "$return",
    "type": "blob",
    "direction": "out",
    "path": "output-container/{id}"
}

以下の例は、C# スクリプト、JavaScript、および F# で、戻り値の型が出力バインドでどのように使用されるかを示しています。The examples below show how return types are used with output bindings in C# script, JavaScript, and F#.

// C# example: use method return value for output binding
public static string Run(WorkItem input, TraceWriter log)
{
    string json = string.Format("{{ \"id\": \"{0}\" }}", input.Id);
    log.Info($"C# script processed queue message. Item={json}");
    return json;
}
// C# example: async method, using return value for output binding
public static Task<string> Run(WorkItem input, TraceWriter log)
{
    string json = string.Format("{{ \"id\": \"{0}\" }}", input.Id);
    log.Info($"C# script processed queue message. Item={json}");
    return Task.FromResult(json);
}
// JavaScript: return a value in the second parameter to context.done
module.exports = function (context, input) {
    var json = JSON.stringify(input);
    context.log('Node.js script processed queue message', json);
    context.done(null, json);
}
// F# example: use return value for output binding
let Run(input: WorkItem, log: TraceWriter) =
    let json = String.Format("{{ \"id\": \"{0}\" }}", input.Id)   
    log.Info(sprintf "F# script processed queue message '%s'" json)
    json

dataType プロパティのバインドBinding dataType property

.NET では、パラメーター型を使用して、入力データのデータ型を定義します。In .NET, use the parameter type to define the data type for input data. たとえば、キュー トリガーのテキストにバインドするには string を、バイナリとして読み取るにはバイト配列を、POCO オブジェクトを逆シリアル化するにはカスタム型を使用します。For instance, use string to bind to the text of a queue trigger, a byte array to read as binary and a custom type to deserialize to a POCO object.

JavaScript などの動的に型指定される言語の場合は、function.json ファイルの dataType プロパティを使用します。For languages that are dynamically typed such as JavaScript, use the dataType property in the function.json file. たとえば、バイナリ形式で HTTP 要求のコンテンツを読み取るには、dataTypebinary に設定します。For example, to read the content of an HTTP request in binary format, set dataType to binary:

{
    "type": "httpTrigger",
    "name": "req",
    "direction": "in",
    "dataType": "binary"
}

dataType のその他のオプションは、streamstring です。Other options for dataType are stream and string.

アプリケーション設定の解決Resolving 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 function.json in a public source control repository.

環境に基づいて構成を変更するときには、アプリ設定も常に役立ちます。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.

アプリ設定は、%MyAppSetting% のように値がパーセント記号で囲まれたときには常に解決されます。App settings are resolved whenever a value is enclosed in percent signs, such as %MyAppSetting%. トリガーやバインドの connection プロパティは特殊ケースであり、値はアプリ設定として自動的に解決されることに注意してください。Note that the connection property of triggers and bindings is a special case and automatically resolves values as app settings.

次の例は、アプリ設定 %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, 
    TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem}");
}

トリガーのメタデータ プロパティTrigger metadata properties

トリガーによって提供されるデータ ペイロード (関数をトリガーしたキュー メッセージなど) に加え、多くのトリガーは追加のメタデータ値を提供します。In addition to the data payload provided by a trigger (such as 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.

バインド式とパターンBinding expressions and patterns

トリガーとバインドの最も強力な機能の 1 つは、バインド式です。One of the most powerful features of triggers and bindings is binding expressions. バインドの構成にパターン式を定義して、それを他のバインドやコードで使用することができます。In the configuration for a binding, you can define pattern expressions which can then be used in other bindings or your code. トリガーのメタデータは、前のセクションに示したように、バインド式でも使用できます。Trigger metadata can also be used in binding expressions, as shown in the preceding section.

たとえば、Azure Portal の [新しい関数] ページの Image Resizer テンプレートのように、特定の Blob Storage コンテナー内のイメージのサイズを変更するとします (サンプル シナリオを参照してください)。For example, suppose you want to resize images in a particular blob storage container, similar to the Image Resizer template in the New Function page of the Azure portal (see the Samples scenario).

function.json の定義は次のようになります。Here is the function.json definition:

{
  "bindings": [
    {
      "name": "image",
      "type": "blobTrigger",
      "path": "sample-images/{filename}",
      "direction": "in",
      "connection": "MyStorageConnection"
    },
    {
      "name": "imageSmall",
      "type": "blob",
      "path": "sample-images-sm/{filename}",
      "direction": "out",
      "connection": "MyStorageConnection"
    }
  ],
}

filename パラメーターは、BLOB トリガーの定義と BLOB 出力バインドの両方で使用されることに注意してください。Notice that the filename parameter is used in both the blob trigger definition and the blob output binding. このパラメーターは、関数コードでも使用できます。This parameter can also be used in function code.

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

バインド式とパターンを使用するのと同じ機能がクラス ライブラリの属性に適用されます。The same ability to use binding expressions and patterns applies to attributes in class libraries. たとえば、クラス ライブラリ内のイメージ サイズ変更関数を次に示します。For example, here is a image resizing function in a class library:

[FunctionName("ResizeImage")]
[StorageAccount("AzureWebJobsStorage")]
public static void Run(
    [BlobTrigger("sample-images/{name}")] Stream image, 
    [Blob("sample-images-sm/{name}", FileAccess.Write)] Stream imageSmall, 
    [Blob("sample-images-md/{name}", FileAccess.Write)] Stream imageMedium)
{
    var imageBuilder = ImageResizer.ImageBuilder.Current;
    var size = imageDimensionsTable[ImageSize.Small];

    imageBuilder.Build(image, imageSmall,
        new ResizeSettings(size.Item1, size.Item2, FitMode.Max, null), false);

    image.Position = 0;
    size = imageDimensionsTable[ImageSize.Medium];

    imageBuilder.Build(image, imageMedium,
        new ResizeSettings(size.Item1, size.Item2, FitMode.Max, null), false);
}

public enum ImageSize { ExtraSmall, Small, Medium }

private static Dictionary<ImageSize, (int, int)> imageDimensionsTable = new Dictionary<ImageSize, (int, int)>() {
    { ImageSize.ExtraSmall, (320, 200) },
    { ImageSize.Small,      (640, 400) },
    { ImageSize.Medium,     (800, 600) }
};

GUID の作成Create GUIDs

{rand-guid} バインド式は GUID を作成します。The {rand-guid} binding expression creates a GUID. 次の例では、GUID を使用して一意の BLOB 名を作成しています。The following example uses a GUID to create a unique blob name:

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

現在の時刻Current time

バインド式 DateTimeDateTime.UtcNow に解決されます。The binding expression DateTime resolves to DateTime.UtcNow.

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

カスタム入力プロパティへのバインドBind to custom input properties

バインド式は、トリガー ペイロード自体に定義されているプロパティも参照できます。Binding expressions can also reference properties that are defined in the trigger payload itself. たとえば、webhook で提供されるファイル名から Blob Storage ファイルに動的にバインドすることもできます。For example, you may want to dynamically bind to a blob storage file from a filename provided in a webhook.

たとえば、次の function.json では、トリガー ペイロードの BlobName という名前のプロパティを使用しています。For example, the following function.json uses a property called BlobName from the trigger payload:

{
  "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# でこれを実現するには、トリガー ペイロードで逆シリアル化されるフィールドを定義する POCO を定義する必要があります。To accomplish this in C# and F#, you must define a POCO that defines the fields that will be deserialized in the trigger payload.

using System.Net;

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

public static HttpResponseMessage Run(HttpRequestMessage req, BlobInfo info, string blobContents)
{
    if (blobContents == null) {
        return req.CreateResponse(HttpStatusCode.NotFound);
    } 

    return req.CreateResponse(HttpStatusCode.OK, new {
        data = $"{blobContents}"
    });
}

JavaScript では、JSON のシリアル化解除は自動的に実行され、プロパティを直接使用することができます。In JavaScript, JSON deserialization is automatically performed and you can use the properties directly.

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

実行時のデータ バインドの構成Configuring binding data 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# 開発者用リファレンスの命令型のバインドによる実行時のバインドに関する記事をご覧ください。To learn more, see Binding at runtime via imperative bindings in the C# developer reference.

function.json ファイル スキーマfunction.json file schema

function.json ファイル スキーマは http://json.schemastore.org/function から入手できます。The function.json file schema is available at http://json.schemastore.org/function.

次の手順Next steps

特定のバインドの詳細については、以下の記事を参照してください。For more information on a specific binding, see the following articles: