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

Azure Functions では、トリガーバインドを使用して、Azure やその他のサービスで発生したイベントに応答するコードを記述できます。Azure Functions allows you to write code in response to events in Azure and other services, through triggers and bindings. この記事では、サポートされているすべてのプログラミング言語でのトリガーとバインドの概念的な概要を説明します。This article is a conceptual overview of triggers and bindings for all supported programming languages. ここでは、すべてのバインドに共通する機能について説明します。Features that are common to all bindings are described here.

概要Overview

トリガーとバインドは、関数を呼び出す方法と、その関数で処理するデータを定義する宣言型の方法です。Triggers and bindings are a declarative way to define how a function is invoked and what data it works with. トリガーは、関数を呼び出す方法を定義します。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. トリガーと同様に、関数の構成に接続文字列やその他のプロパティを指定します。Similar to triggers, you specify connection strings and other properties in your function configuration. バインドは省略可能で、関数は複数の入出力バインドを持つことができます。Bindings are optional and a function can have multiple input and output bindings.

トリガーとバインドを使用すると、より汎用性があり、操作するサービスの詳細をハードコードしないコードを記述できます。Using triggers and bindings, you can write code that is more generic and does not hardcode the details of the services with which it interacts. サービスからのデータは、単純に関数コードの入力値になります。Data coming from services simply become input values for your function code. 別のサービスにデータを出力する (Azure Table Storage での新しい行の作成など) には、メソッドの戻り値を使用します。To output data to another service (such as creating a new row in Azure Table Storage), use the return value of the method. また、複数の値を出力する必要がある場合は、ヘルパー オブジェクトを使用します。Or, if you need to output multiple values, use a helper object. トリガーとバインドには name プロパティがあります。このプロパティは、バインドにアクセスするためにコード内で使用する識別子です。Triggers and bindings have a name property, which is an identifier you use in your code to access the binding.

トリガーとバインドは、Azure Functions ポータルの [統合] タブで構成できます。You can configure triggers and bindings in the Integrate tab in the Azure Functions portal. この UI は内部的に、function ディレクトリ内の function.json という名前のファイルを変更します。Under the covers, the UI modifies a file called function.json file in the function directory. 詳細エディターに変更すると、このファイルを編集できます。You can edit this file by changing to the Advanced editor.

次の表に、Azure Functions でサポートされているトリガーとバインドを示します。The following table shows the triggers and bindings that are supported with Azure Functions.

Type サービスService トリガーTrigger 入力Input 出力Output
スケジュールSchedule Azure FunctionsAzure Functions
HTTP (REST または Webhook)HTTP (REST or webhook) Azure FunctionsAzure Functions ✔**✔**
Blob StorageBlob Storage Azure Storage (Azure Storage)Azure Storage
イベントEvents Azure Event HubsAzure Event Hubs
キューQueues Azure Storage (Azure Storage)Azure Storage
キューとトピックQueues and topics Azure Service BusAzure Service Bus
Storage テーブルStorage tables Azure Storage (Azure Storage)Azure Storage
SQL テーブルSQL tables Azure Mobile AppsAzure Mobile Apps
NoSQL DBNoSQL DB Azure Cosmos DBAzure Cosmos DB
プッシュ通知Push Notifications Azure 通知ハブAzure Notification Hubs
Twilio SMS テキストTwilio SMS Text TwilioTwilio
SendGrid 電子メールSendGrid email SendGridSendGrid
Excel テーブルExcel tables Microsoft GraphMicrosoft Graph
OneDrive ファイルOneDrive files Microsoft GraphMicrosoft Graph
Outlook メールOutlook email Microsoft GraphMicrosoft Graph
Microsoft Graph イベントMicrosoft Graph events Microsoft GraphMicrosoft Graph
認証トークンAuth tokens Microsoft GraphMicrosoft Graph

(* - すべてのトリガーには入力データが関連付けられています)(* - All triggers have associated input data)

(** - HTTP 出力バインドには HTTP トリガーが必要です)(** - The HTTP output binding requires an HTTP trigger)

例: キュー トリガーとテーブルの出力バインド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 トリガーと Azure Table Storage の出力バインドを使用して実装できます。This scenario can be implemented using an Azure Queue trigger and an Azure Table Storage output binding.

Azure Queue Storage トリガーには、[統合] タブ内の以下の情報が必要です。An Azure Queue Storage trigger requires the following information in the Integrate tab:

  • Azure Queue Storage の Azure Storage アカウント接続文字列を含む、アプリ設定の名前The name of the app setting that contains the Azure Storage account connection string for the Azure Queue Storage
  • キュー名The queue name
  • order など、キュー メッセージの内容を読み取るためのコード内の識別子The identifier in your code to read the contents of the queue message, such as order.

Azure Table Storage に書き込むには、以下の詳細を含む出力バインドを使用します。To write to Azure Table Storage, use an output binding with the following details:

  • Azure Table Storage の Azure Storage アカウント接続文字列を含む、アプリ設定の名前The name of the app setting that contains the Azure Storage account connection string for the Azure Table Storage
  • テーブル名The table name
  • 関数から出力項目または戻り値を作成するための、コード内の識別子The identifier in your code to create output items, or the return value from the function.

バインディングは、アプリの設定に格納された接続文字列値を使用して、function.json にサービス シークレットを格納せずに、アプリ設定の名前だけを含めるというベスト プラクティスを確実に実行します。Bindings use connection strings values stored in the app settings to enforce the best practice that function.json does not contain service secrets and instead simply contain the names of the app settings.

その後、指定した識別子を使用して、コードで Azure Storage と統合します。Then, use the identifiers you provided to integrate with Azure Storage in your code.

#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; }
}
// 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);
}

次に、上記のコードに対応する function.json を示します。Here is the function.json that corresponds to the preceding code. 関数の実装言語に関係なく、同じ構成を使用できることに注意してください。Note that the same configuration can be used, regardless of the language of the function implementation.

{
  "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"
    }
  ]
}

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.

Azure Storage との統合のコード例と詳細については、「Azure Functions における Azure Storage のトリガーとバインド」を参照してください。For more code examples and details on integrating with Azure Storage, see Azure Functions triggers and bindings for Azure Storage.

バインドの方向Binding direction

すべてのトリガーとバインドには direction プロパティがあります。All triggers and bindings have a direction property:

  • トリガーの場合、方向は常に 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.

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

前の例は、関数の戻り値を使用してバインドに出力を提供する方法を示しています。これは、特殊な名前のパラメーター $return を使用して実現されます。The preceding example shows how to use the function return value to provide output to a binding, which is achieved by using the special name parameter $return. (このパラメーターは、C#、JavaScript、F# などの、戻り値がある言語でのみサポートされています。)1 つの関数に複数の出力バインドがある場合は、1 つの出力バインドに対してのみ $return を使用します。(This is only supported in languages that have a return value, such as C#, 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#, 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 types 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 など、動的に型指定された言語については、バインディングの定義で dataType プロパティを使用します。For languages that are dynamically typed such as JavaScript, use the dataType property in the binding definition. たとえば、バイナリ形式で HTTP 要求のコンテンツを読み取るには、binary 型を使用します。For example, to read the content of an HTTP request in binary format, use the type 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"
    }
  ]
}

トリガーのメタデータ プロパティ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 Storage Queue トリガーは以下のプロパティをサポートしています。For example, an Azure Storage Queue trigger supports the following properties:

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

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

たとえば、BLOB トリガーには一定の遅延があるため、キュー トリガーを使用して関数を実行できます (BLOB ストレージ トリガーに関するページを参照)。For example, since blob triggers have some delays, you can use a queue trigger to run your function (see Blob Storage Trigger). キュー メッセージにはトリガーする対象の Blob ファイル名が含まれます。The queue message would contain the blob filename to trigger on. queueTrigger メタデータ プロパティを使用する場合は、この動作をすべて、コードではなく構成に指定できます。Using the queueTrigger metadata property, you can specify this behavior all in your configuration, rather than your code.

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

次のセクションで説明するように、別のバインドのバインド式でも、トリガーのメタデータ プロパティを使用できます。Metadata properties from a trigger can also be used in a binding expression for another binding, as described in the following section.

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

トリガーとバインドの最も強力な機能の 1 つは、バインド式です。One of the most powerful features of triggers and bindings is binding expressions. バインド内にパターン式を定義して、それを他のバインドやコードで使用することができます。Within your 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 show in the sample in the preceding section.

たとえば、[新しい関数] ページの Image Resizer テンプレートのように、特定の Blob Storage コンテナー内のイメージのサイズを変更するとします。For example, suppose you want to resize images in particular blob storage container, similar to the Image Resizer template in the New Function page. [新しい関数] -> [言語] として [C#] -> [シナリオ]として [サンプル] -> ImageResizer CSharp の順に選択します。Go to New Function -> Language C# -> Scenario Samples -> ImageResizer-CSharp.

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

ランダム GUIDRandom GUIDs

Azure Functions には、{rand-guid} バインド式を使用してバインドに GUID を生成するための便利な構文があります。Azure Functions provides a convenience syntax for generating GUIDs in your bindings, through the {rand-guid} binding expression. 次の例では、これを使用して一意の Blob 名を生成しています。The following example uses this to generate a unique blob name:

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

現在の時刻Current time

バインド式 DateTime を使用できます。これは、DateTime.UtcNow に解決されます。You can use the binding expression DateTime, which resolves to DateTime.UtcNow.

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

バインド式でのカスタム入力プロパティへのバインドBind to custom input properties in a binding expression

バインド式は、トリガー ペイロード自体に定義されているプロパティも参照できます。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. 命令型のバインドは、設計時ではなくランタイム時にバインド パラメーターを計算する必要がある場合に便利です。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.

次のステップNext steps

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