Azure Functions でのトリガーとバインドの使用方法

このトピックでは、Azure Functions でトリガーおよびバインドを使用して、さまざまなトリガーや Azure サービス、その他のクラウドベース サービスにコードを接続する方法を示します。 主に、すべてのバインド タイプでサポートされる高度なバインド機能と構文について説明します。

特定の種類のトリガーまたはバインドを使用する方法の詳細については、次の参照トピックのいずれかを参照してください。

HTTP/webhook Timer Mobile Apps Service Bus
DocumentDB Storage Blob ストレージ キュー ストレージ テーブル
Event Hubs Notification Hubs Twilio

これらの記事は、「Azure Functions developer reference (Azure Functions 開発者用リファレンス)」と C#F#、または Node.js の開発者用リファレンスを既に読んでいることを前提としています。

概要

トリガーは、カスタム コードをトリガーするために使用されるイベント応答です。 これにより、Azure プラットフォーム全体またはオンプレミスのイベントに応答できます。 バインドは、コードを目的のトリガーや関連する入出力データに接続するために使用される必要なメタデータを表します。 各関数の function.json ファイルには、すべての関連バインドが含まれます。 関数の入力バインドと出力バインドの数に制限はありません。 ただし、各関数でサポートされるトリガーのバインドは&1; つのみです。

Azure Function アプリに統合できるさまざまなバインドの詳細については、以下の表を参照してください。

サービス トリガー 入力 出力
スケジュール Azure Functions
HTTP (REST または Webhook) Azure Functions ✔*
Blob Storage Azure Storage (Azure Storage)
イベント Azure Event Hubs
キュー Azure Storage (Azure Storage)
キューとトピック Azure Service Bus
テーブル Azure Storage (Azure Storage)
テーブル Azure Mobile Apps
NoSQL DB Azure DocumentDB
プッシュ通知 Azure 通知ハブ
Twilio SMS テキスト Twilio

(* - HTTP 出力バインドには HTTP トリガーが必要です)

トリガーとバインド全般をより深く理解するために、Azure Storage キューにドロップされた新しい項目を処理するいくつかのコードを実行する必要があるとします。 Azure Functions には、これをサポートするための Azure キュー トリガーが用意されています。 キューを監視するには次の情報が必要です。

  • キューが存在するストレージ アカウント。
  • キュー名。
  • キューにドロップされた新しい項目を参照するためにコードで使用する変数名。

1 つのキュー トリガー バインドには、1 つの Azure 関数についての上記の情報が含まれます。 1 つのキュー トリガー バインドを含んでいる function.json の例を次に示します。

{
  "bindings": [
    {
      "name": "myNewUserQueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "queue-newusers",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    }
  ],
  "disabled": false
}

コードでは、新しいキュー項目の処理方法に応じてさまざまなタイプの出力を送信できます。 たとえば、Azure Storage テーブルに新しいレコードを書き込む必要があるとします。 これを行うには、Azure Storage テーブルへの出力バインドを作成します。 キュー トリガーに使用できるストレージ テーブルの出力バインドを含んでいる function.json の例を次に示します。

{
  "bindings": [
    {
      "name": "myNewUserQueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "queue-newusers",
      "connection": "MY_STORAGE_ACCT_APP_SETTING"
    },
    {
      "type": "table",
      "name": "myNewUserTableBinding",
      "tableName": "newUserTable",
      "connection": "MY_TABLE_STORAGE_ACCT_APP_SETTING",
      "direction": "out"
    }
  ],
  "disabled": false
}

次の C# 関数は、キューにドロップされる新しい項目に応答し、Azure Storage テーブルに新しいユーザー エントリを書き込みます。

#r "Newtonsoft.Json"

using System;
using Newtonsoft.Json;

public static async Task Run(string myNewUserQueueItem, IAsyncCollector<Person> myNewUserTableBinding, 
                                TraceWriter log)
{
    // In this example the queue item is a JSON string representing an order that contains the name, 
    // address and mobile number of the new customer.
    dynamic order = JsonConvert.DeserializeObject(myNewUserQueueItem);

    await myNewUserTableBinding.AddAsync(
        new Person() { 
            PartitionKey = "Test", 
            RowKey = Guid.NewGuid().ToString(), 
            Name = order.name,
            Address = order.address,
            MobileNumber = order.mobileNumber }
        );
}

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

その他のコード例とサポート対象の Azure ストレージ タイプに関するさらに具体的な情報については、「Azure Functions における Azure Storage のトリガーとバインド」を参照してください。

より高度なバインド機能を Azure Portal で使用するには、関数の [統合] タブにある [詳細エディター] オプションをクリックします。 詳細エディターを使用すると、function.json を Portal で直接編集できます。

ランダム GUID

Azure Functions には、バインドでランダム GUID を生成するための構文が用意されています。 次のバインド構文は、Storage コンテナー内の一意の名前を持つ新しい BLOB に出力を書き込みます。

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

単一の出力を返す場合

関数コードが単一の出力を返す場合、$return という名前の出力バインドを使用すると、より自然な関数シグネチャをコードで保持できます。 これは、戻り値がサポートされている言語 (C#、Node.js、F#) でのみ使用できます。 バインドは、キュー トリガーに使用される次の BLOB 出力バインドと同じようになります。

{
  "bindings": [
    {
      "type": "queueTrigger",
      "name": "input",
      "direction": "in",
      "queueName": "test-input-node"
    },
    {
      "type": "blob",
      "name": "$return",
      "direction": "out",
      "path": "test-output-node/{id}"
    }
  ]
}

次の C# コードは、関数シグネチャで out パラメーターを使用せずに、より自然に出力を返します。

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;
}

非同期の例:

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 json;
}

これと同じアプローチを Node.js で示すと次のようになります。

module.exports = function (context, input) {
    var json = JSON.stringify(input);
    context.log('Node.js script processed queue message', json);
    context.done(null, json);
}

F# の例を次に示します。

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

また、単一の出力を $return で指定することにより、これを複数の出力パラメーターで使用できます。

アプリケーション設定の解決

アプリケーション設定を使用して、実行時環境の一部として機密情報を保存することをお勧めします。 機密情報をアプリケーションの構成ファイルとは別に保存することで、アプリケーション ファイルの格納にパブリック リポジトリを使用した場合にこれらの情報が危険にさらされるリスクを制限します。

Azure Functions ランタイムは、%your app setting% のようにアプリケーション設定の名前がパーセント記号で囲まれている場合に、アプリケーション設定を値に解決します。 次の Twilio バインドでは、TWILIO_ACCT_PHONE というアプリケーション設定の名前をバインドの from フィールド用に使用しています。

{
  "type": "twilioSms",
  "name": "$return",
  "accountSid": "TwilioAccountSid",
  "authToken": "TwilioAuthToken",
  "to": "{mobileNumber}",
  "from": "%TWILIO_ACCT_PHONE%",
  "body": "Thank you {name}, your order was received Node.js",
  "direction": "out"
},

パラメーターのバインド

出力バインド プロパティの設定を静的に構成する代わりに、トリガーの入力バインドに含まれるデータに動的にバインドされるように設定を構成できます。 新しい注文が Azure Storage キューを使用して処理されるシナリオを考えてみましょう。 それぞれの新しいキュー項目は、少なくとも次のプロパティを含んでいる JSON 文字列です。

{
  "name" : "Customer Name",
  "address" : "Customer's Address",
  "mobileNumber" : "Customer's mobile number in the format - +1XXXYYYZZZZ."
}

注文が受信されたことを示す更新情報として、Twilio アカウントを使用して顧客に SMS テキスト メッセージを送信します。 Twilio 出力バインドの body および to フィールドを、入力に含まれていた name および mobileNumber に動的にバインドされるように構成できます。

{
  "name": "myNewOrderItem",
  "type": "queueTrigger",
  "direction": "in",
  "queueName": "queue-newOrders",
  "connection": "orders_STORAGE"
},
{
  "type": "twilioSms",
  "name": "$return",
  "accountSid": "TwilioAccountSid",
  "authToken": "TwilioAuthToken",
  "to": "{mobileNumber}",
  "from": "%TWILIO_ACCT_PHONE%",
  "body": "Thank you {name}, your order was received",
  "direction": "out"
},

あとは、関数コードで出力パラメータを次のように初期化するだけです。 実行時に、出力プロパティが目的の入力データにバインドされます。

#r "Newtonsoft.Json"
#r "Twilio.Api"

using System;
using System.Threading.Tasks;
using Newtonsoft.Json;
using Twilio;

public static async Task<SMSMessage> Run(string myNewOrderItem, TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myNewOrderItem}");

    dynamic order = JsonConvert.DeserializeObject(myNewOrderItem);    

    // Even if you want to use a hard coded message and number in the binding, you must at least 
    // initialize the SMSMessage variable.
    SMSMessage smsText = new SMSMessage();

    // The following isn't needed since we use parameter binding for this
    //string msg = "Hello " + order.name + ", thank you for your order.";
    //smsText.Body = msg;
    //smsText.To = order.mobileNumber;

    return smsText;
}

Node.js:

module.exports = function (context, myNewOrderItem) {    
    context.log('Node.js queue trigger function processed work item', myNewOrderItem);    

    // No need to set the properties of the text, we use parameters in the binding. We do need to 
    // initialize the object.
    var smsText = {};    

    context.done(null, smsText);
}

実行時の高度なバインド (命令型のバインド)

function.json を使用した標準的な入出力バインドのパターンは "宣言型" のバインドと呼ばれます。バインドは JSON 宣言によって定義されます。 ただし、命令型のバインドも使用できます。 このパターンを使用すると、サポートされている任意の数の入力バインドと出力バインドに関数コード内でバインドできます。 関数の設計時ではなく、関数の実行時にバインド パスまたは他の入力の計算が必要になった場合に、命令型のバインドが必要になることがあります。

次のように命令型のバインドを定義します。

  • 必要な命令型のバインドの function.json にエントリを含めないでください。
  • 入力パラメーター Binder binder または IBinder binder を渡します。
  • 次の C# パターンを使用してデータ バインドを実行します。
using (var output = await binder.BindAsync<T>(new BindingTypeAttribute(...)))
{
    ...
}

ここで、BindingTypeAttribute はバインドを定義する .NET 属性、T はそのバインドの種類でサポートされている入力または出力の型です。 Tout パラメーター型 (out JObject など) にすることはできません。 たとえば、Mobile Apps テーブルの出力バインドは 6 種類の出力をサポートしますが、T に使用できるのは ICollector または IAsyncCollector のみです。

次のコード例は、実行時に BLOB パスが定義された Storage Blob の出力バインドを作成し、この BLOB に文字列を書き込みます。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host.Bindings.Runtime;

public static async Task Run(string input, Binder binder)
{
    using (var writer = await binder.BindAsync<TextWriter>(new BlobAttribute("samples-output/path")))
    {
        writer.Write("Hello World!!");
    }
}

BlobAttributeStorage Blob の入力バインドまたは出力バインドを定義します。TextWriter はサポートされている出力バインドの種類です。 このコードは、ストレージ アカウントの接続文字列 (AzureWebJobsStorage) の既定のアプリケーション設定を取得します。 StorageAccountAttribute を追加し、属性の配列を BindAsync<T>() に渡すことで、使用するカスタムなアプリケーション設定を指定できます。 たとえば、次のように入力します。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host.Bindings.Runtime;

public static async Task Run(string input, Binder binder)
{
    var attributes = new Attribute[]
    {    
        new BlobAttribute("samples-output/path"),
        new StorageAccountAttribute("MyStorageAccount")
    };

    using (var writer = await binder.BindAsync<TextWriter>(attributes))
    {
        writer.Write("Hello World!");
    }
}

以下の表に、それぞれのバインドの種類で使われる対応する .NET 属性と参照するパッケージを示します。

バインド Attribute 参照の追加
DocumentDB Microsoft.Azure.WebJobs.DocumentDBAttribute #r "Microsoft.Azure.WebJobs.Extensions.DocumentDB"
Event Hubs Microsoft.Azure.WebJobs.ServiceBus.EventHubAttributeMicrosoft.Azure.WebJobs.ServiceBusAccountAttribute #r "Microsoft.Azure.Jobs.ServiceBus"
Mobile Apps Microsoft.Azure.WebJobs.MobileTableAttribute #r "Microsoft.Azure.WebJobs.Extensions.MobileApps"
Notification Hubs Microsoft.Azure.WebJobs.NotificationHubAttribute #r "Microsoft.Azure.WebJobs.Extensions.NotificationHubs"
Service Bus Microsoft.Azure.WebJobs.ServiceBusAttributeMicrosoft.Azure.WebJobs.ServiceBusAccountAttribute #r "Microsoft.Azure.WebJobs.ServiceBus"
ストレージ キュー Microsoft.Azure.WebJobs.QueueAttributeMicrosoft.Azure.WebJobs.StorageAccountAttribute
Storage Blob Microsoft.Azure.WebJobs.BlobAttributeMicrosoft.Azure.WebJobs.StorageAccountAttribute
ストレージ テーブル Microsoft.Azure.WebJobs.TableAttributeMicrosoft.Azure.WebJobs.StorageAccountAttribute
Twilio Microsoft.Azure.WebJobs.TwilioSmsAttribute #r "Microsoft.Azure.WebJobs.Extensions.Twilio"

次のステップ

詳細については、次のリソースを参照してください。