Azure Functions における Azure Queue Storage のバインドAzure Queue storage bindings for Azure Functions

この記事では、Azure Functions で Azure Queue Storage のバインドを使用する方法について説明します。This article explains how to work with Azure Queue storage bindings in Azure Functions. Azure Functions は、キューのトリガーと出力バインドをサポートしています。Azure Functions supports trigger and output bindings for queues.

これは、Azure Functions の開発者向けリファレンス情報です。This is reference information for Azure Functions developers. Azure Functions を初めて使用する場合は、先に次のリソースを参照してください。If you're new to Azure Functions, start with the following resources:

トリガーTrigger

キュー トリガーを使用して、キューで新しい項目を受け取ったときに関数を開始します。Use the queue trigger to start a function when a new item is received on a queue. キュー メッセージは、関数への入力として提供されます。The queue message is provided as input to the function.

トリガー - 例Trigger - example

言語固有の例をご覧ください。See the language-specific example:

トリガー - C# の例Trigger - C# example

次の例は、キュー項目が処理されるたびに myqueue-items キューをポーリングし、ログを書き込むプリコンパイル済み C# コードを示しています。The following example shows precompiled C# code that polls the myqueue-items queue and writes a log each time a queue item is processed.

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        TraceWriter log)
    {
        log.Info($"C# function processed: {myQueueItem}");
    }
}

トリガー - C# スクリプトの例Trigger - C# script example

次の例は、function.json ファイルの BLOB トリガー バインドと、バインドを使用する C# スクリプト コードを示しています。The following example shows a blob trigger binding in a function.json file and C# script code that uses the binding. この関数は、キュー項目が処理されるたびに myqueue-items キューをポーリングし、ログを書き込みます。The function polls the myqueue-items queue and writes a log each time a queue item is processed.

function.json ファイルを次に示します。Here's the function.json file:

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

これらのプロパティについては、「構成」セクションを参照してください。The configuration section explains these properties.

C# スクリプト コードを次に示します。Here's the C# script code:

#r "Microsoft.WindowsAzure.Storage"

using Microsoft.WindowsAzure.Storage.Queue;
using System;

public static void Run(CloudQueueMessage myQueueItem, 
    DateTimeOffset expirationTime, 
    DateTimeOffset insertionTime, 
    DateTimeOffset nextVisibleTime,
    string queueTrigger,
    string id,
    string popReceipt,
    int dequeueCount,
    TraceWriter log)
{
    log.Info($"C# Queue trigger function processed: {myQueueItem.AsString}\n" +
        $"queueTrigger={queueTrigger}\n" +
        $"expirationTime={expirationTime}\n" +
        $"insertionTime={insertionTime}\n" +
        $"nextVisibleTime={nextVisibleTime}\n" +
        $"id={id}\n" +
        $"popReceipt={popReceipt}\n" + 
        $"dequeueCount={dequeueCount}");
}

function.json の name プロパティで名前が指定された myQueueItem については、「使用方法」セクションを参照してください。The usage section explains myQueueItem, which is named by the name property in function.json. ここに表示されているその他すべての変数については、「メッセージのメタデータ」セクションを参照してください。The message metadata section explains all of the other variables shown.

トリガー - JavaScript の例Trigger - JavaScript example

次の例は、function.json ファイルの BLOB トリガー バインドと、そのバインドを使用する JavaScript 関数を示しています。The following example shows a blob trigger binding in a function.json file and a JavaScript function that uses the binding. この関数は、キュー項目が処理されるたびに myqueue-items キューをポーリングし、ログを書き込みます。The function polls the myqueue-items queue and writes a log each time a queue item is processed.

function.json ファイルを次に示します。Here's the function.json file:

{
    "disabled": false,
    "bindings": [
        {
            "type": "queueTrigger",
            "direction": "in",
            "name": "myQueueItem",
            "queueName": "myqueue-items",
            "connection":"MyStorageConnectionAppSetting"
        }
    ]
}

これらのプロパティについては、「構成」セクションを参照してください。The configuration section explains these properties.

JavaScript コードを次に示します。Here's the JavaScript code:

module.exports = function (context) {
    context.log('Node.js queue trigger function processed work item', context.bindings.myQueueItem);
    context.log('queueTrigger =', context.bindingData.queueTrigger);
    context.log('expirationTime =', context.bindingData.expirationTime);
    context.log('insertionTime =', context.bindingData.insertionTime);
    context.log('nextVisibleTime =', context.bindingData.nextVisibleTime);
    context.log('id =', context.bindingData.id);
    context.log('popReceipt =', context.bindingData.popReceipt);
    context.log('dequeueCount =', context.bindingData.dequeueCount);
    context.done();
};

function.json の name プロパティで名前が指定された myQueueItem については、「使用方法」セクションを参照してください。The usage section explains myQueueItem, which is named by the name property in function.json. ここに表示されているその他すべての変数については、「メッセージのメタデータ」セクションを参照してください。The message metadata section explains all of the other variables shown.

トリガー - 属性Trigger - attributes

プリコンパイル済み C# 関数では、次の属性を使用してキュー トリガーを構成します。For precompiled C# functions, use the following attributes to configure a queue trigger:

  • NuGet パッケージ Microsoft.Azure.WebJobs で定義された QueueTriggerAttributeQueueTriggerAttribute, defined in NuGet package Microsoft.Azure.WebJobs

    次の例のように、属性のコンストラクターは監視するキューの名前を受け取ります。The attribute's constructor takes the name of the queue to monitor, as shown in the following example:

    [FunctionName("QueueTrigger")]
    public static void Run(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        TraceWriter log)
    {
        ...
    }
    

    次の例で示すように、Connection プロパティを設定して、使用するストレージ アカウントを指定できます。You can set the Connection property to specify the storage account to use, as shown in the following example:

    [FunctionName("QueueTrigger")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
        TraceWriter log)
    {
        ....
    }
    

    完全な例については、トリガー - プリコンパイル済み C# の例に関する記事をご覧ください。For a complete example, see Trigger - precompiled C# example.

  • NuGet パッケージ Microsoft.Azure.WebJobs で定義された StorageAccountAttributeStorageAccountAttribute, defined in NuGet package Microsoft.Azure.WebJobs

    使用するストレージ アカウントを指定する別の方法を提供します。Provides another way to specify the storage account to use. コンストラクターは、ストレージ接続文字列を含むアプリ設定の名前を受け取ります。The constructor takes the name of an app setting that contains a storage connection string. 属性は、パラメーター、メソッド、またはクラス レベルで適用できます。The attribute can be applied at the parameter, method, or class level. 次の例では、クラス レベルとメソッド レベルを示します。The following example shows class level and method level:

    [StorageAccount("ClassLevelStorageAppSetting")]
    public static class AzureFunctions
    {
        [FunctionName("QueueTrigger")]
        [StorageAccount("FunctionLevelStorageAppSetting")]
        public static void Run( //...
    {
        ...
    }
    

使用するストレージ アカウントは、次の順序で決定されます。The storage account to use is determined in the following order:

  • QueueTrigger 属性の Connection プロパティ。The QueueTrigger attribute's Connection property.
  • QueueTrigger 属性と同じパラメーターに適用された StorageAccount 属性。The StorageAccount attribute applied to the same parameter as the QueueTrigger attribute.
  • 関数に適用される StorageAccount 属性。The StorageAccount attribute applied to the function.
  • クラスに適用される StorageAccount 属性。The StorageAccount attribute applied to the class.
  • "AzureWebJobsStorage" アプリ設定。The "AzureWebJobsStorage" app setting.

トリガー - 構成Trigger - configuration

次の表は、function.json ファイルと QueueTrigger 属性で設定したバインド構成のプロパティを説明しています。The following table explains the binding configuration properties that you set in the function.json file and the QueueTrigger attribute.

function.json のプロパティfunction.json property 属性のプロパティAttribute property 説明Description
typetype 該当なしn/a queueTrigger に設定する必要があります。Must be set to queueTrigger. このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。This property is set automatically when you create the trigger in the Azure portal.
directiondirection 該当なしn/a function.json ファイルの場合のみ。In the function.json file only. in に設定する必要があります。Must be set to in. このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。This property is set automatically when you create the trigger in the Azure portal.
namename 該当なしn/a 関数コード内のキューを表す変数の名前。The name of the variable that represents the queue in function code.
queueNamequeueName QueueNameQueueName ポーリングするキューの名前。The name of the queue to poll.
connectionconnection ConnectionConnection このバインドに使用するストレージ接続文字列を含むアプリ設定の名前です。The name of an app setting that contains the Storage connection string to use for this binding. アプリ設定の名前が "AzureWebJobs" で始まる場合は、ここで名前の残りの部分のみを指定できます。If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. たとえば、connection を "MyStorage" に設定した場合、Functions ランタイムは "AzureWebJobsMyStorage" という名前のアプリ設定を探します。For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." connection を空のままにした場合、Functions ランタイムは、アプリ設定内の AzureWebJobsStorage という名前の既定のストレージ接続文字列を使用します。If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

ローカルで開発している場合、アプリ設定は local.settings.json ファイルに保存されます。When you're developing locally, app settings go into the local.settings.json file.

トリガー - 使用方法Trigger - usage

C# および C# スクリプトでは、Stream paramName のようなメソッド パラメーターを使用して BLOB データにアクセスします。In C# and C# script, access the blob data by using a method parameter such as Stream paramName. C# スクリプトでは、paramNamefunction.jsonname プロパティで指定された値です。In C# script, paramName is the value specified in the name property of function.json. 次の型のいずれにでもバインドできます。You can bind to any of the following types:

  • POCO オブジェクト - Functions ランタイムは、JSON ペイロードを POCO オブジェクトに逆シリアル化します。POCO object - The Functions runtime deserializes a JSON payload into a POCO object.
  • string
  • byte[]
  • CloudQueueMessageCloudQueueMessage

JavaScript の場合、context.bindings.<name> を使用してキュー項目ペイロードにアクセスします。In JavaScript, use context.bindings.<name> to access the queue item payload. ペイロードが JSON の場合は、オブジェクトに逆シリアル化されます。If the payload is JSON, it's deserialized into an object.

トリガー - メッセージのメタデータTrigger - message metadata

キュー トリガーは、いくつかのメタデータ プロパティを提供します。The queue trigger provides several metadata properties. これらのプロパティは、他のバインドのバインド式の一部として、またはコードのパラメーターとして使用できます。These properties can be used as part of binding expressions in other bindings or as parameters in your code. 値は、CloudQueueMessage と同じセマンティクスを持ちます。The values have the same semantics as CloudQueueMessage.

プロパティProperty Type 説明Description
QueueTrigger string キュー ペイロード (有効な文字列の場合)。Queue payload (if a valid string). キュー メッセージ ペイロードが文字列の場合、QueueTrigger は、function.jsonname プロパティで指定された変数と同じ値になります。If the queue message payload as a string, QueueTrigger has the same value as the variable named by the name property in function.json.
DequeueCount int このメッセージがデキューされた回数。The number of times this message has been dequeued.
ExpirationTime DateTimeOffset? メッセージが期限切れになる時刻。The time that the message expires.
Id string キュー メッセージ ID。Queue message ID.
InsertionTime DateTimeOffset? メッセージがキューに追加された時刻。The time that the message was added to the queue.
NextVisibleTime DateTimeOffset? メッセージが次に表示される時刻。The time that the message will next be visible.
PopReceipt string メッセージのポップ受信。The message's pop receipt.

トリガー - 有害メッセージTrigger - poison messages

キュー トリガー関数が失敗すると、Azure Functions は、その関数を特定のキュー メッセージに対して (最初の試行を含め) 最大 5 回再試行します。When a queue trigger function fails, Azure Functions retries the function up to five times for a given queue message, including the first try. 試行が 5 回とも失敗した場合、Functions ランタイム は、<originalqueuename>-poison という名前のキューにメッセージを追加します。If all five attempts fail, the functions runtime adds a message to a queue named <originalqueuename>-poison. メッセージのログを取得するか、手動での対処が必要であるという通知を送信することにより有害キューからのメッセージを処理する関数が記述できます。You can write a function to process messages from the poison queue by logging them or sending a notification that manual attention is needed.

有害メッセージを手動で処理するには、キュー メッセージの dequeueCount を確認します。To handle poison messages manually, check the dequeueCount of the queue message.

トリガー - host.json のプロパティTrigger - host.json properties

host.json ファイルには、キュー トリガーの動作を制御する設定が含まれています。The host.json file contains settings that control queue trigger behavior.

{
    "queues": {
      "maxPollingInterval": 2000,
      "visibilityTimeout" : "00:00:30",
      "batchSize": 16,
      "maxDequeueCount": 5,
      "newBatchThreshold": 8
    }
}
プロパティProperty 既定値Default DescriptionDescription
maxPollingIntervalmaxPollingInterval 6000060000 キューのポーリングの最大間隔 (ミリ秒)。The maximum interval in milliseconds between queue polls.
visibilityTimeoutvisibilityTimeout 00 メッセージの処理が失敗したときの再試行間隔。The time interval between retries when processing of a message fails.
batchSizebatchSize 1616 並列で取得および処理されるキュー メッセージ数。The number of queue messages to retrieve and process in parallel. 最大値は 32 です。The maximum is 32.
maxDequeueCountmaxDequeueCount 55 有害キューに移動する前に、メッセージの処理を試行する回数。The number of times to try processing a message before moving it to the poison queue.
newBatchThresholdnewBatchThreshold batchSize/2batchSize/2 新しいメッセージのバッチを取得するしきい値。The threshold at which a new batch of messages are fetched.

出力Output

Azure Queue Storage の出力バインドを使用して、キューにメッセージを書き込みます。Use the Azure Queue storage output binding to write messages to a queue.

出力 - 例Output - example

言語固有の例をご覧ください。See the language-specific example:

出力 - C# の例Output - C# example

次の例は、受け取った HTTP 要求ごとにキュー メッセージを作成するプリコンパイル済み C# コードを示します。The following example shows precompiled C# code that creates a queue message for each HTTP request received.

[StorageAccount("AzureWebJobsStorage")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  TraceWriter log)
    {
        log.Info($"C# function processed: {input.Text}");
        return input.Text;
    }
}

出力 - C# スクリプトの例Output - C# script example

次の例は、function.json ファイルの BLOB トリガー バインドと、バインドを使用する C# スクリプト コードを示しています。The following example shows a blob trigger binding in a function.json file and C# script code that uses the binding. この関数では、受け取った HTTP 要求ごとに POCO ペイロードを使用してキュー項目を作成します。The function creates a queue item with a POCO payload for each HTTP request received.

function.json ファイルを次に示します。Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting",
    }
  ]
}

これらのプロパティについては、「構成」セクションを参照してください。The configuration section explains these properties.

単一のキュー メッセージを作成する C# スクリプト コードを次に示します。Here's C# script code that creates a single queue message:

public class CustomQueueMessage
{
    public string PersonName { get; set; }
    public string Title { get; set; }
}

public static CustomQueueMessage Run(CustomQueueMessage input, TraceWriter log)
{
    return input;
}

一度で複数のメッセージを送信するには、ICollector または IAsyncCollector パラメーターを使用します。You can send multiple messages at once by using an ICollector or IAsyncCollector parameter. HTTP 要求データを含む 1 つのメッセージと、ハードコーディングされた値を含む 1 つのメッセージという、複数のメッセージを送信する C# スクリプト コードを次に示します。Here's C# script code that sends multiple messages, one with the HTTP request data and one with hard-coded values:

public static void Run(
    CustomQueueMessage input, 
    ICollector<CustomQueueMessage> myQueueItem, 
    TraceWriter log)
{
    myQueueItem.Add(input);
    myQueueItem.Add(new CustomQueueMessage { PersonName = "You", Title = "None" });
}

出力 - JavaScript の例Output - JavaScript example

次の例は、function.json ファイルの BLOB トリガー バインドと、そのバインドを使用する JavaScript 関数を示しています。The following example shows a blob trigger binding in a function.json file and a JavaScript function that uses the binding. この関数では、受け取った HTTP 要求ごとにキュー項目を作成します。The function creates a queue item for each HTTP request received.

function.json ファイルを次に示します。Here's the function.json file:

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "$return",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting",
    }
  ]
}

これらのプロパティについては、「構成」セクションを参照してください。The configuration section explains these properties.

JavaScript コードを次に示します。Here's the JavaScript code:

module.exports = function (context, input) {
    context.done(null, input.body);
};

一度で複数のメッセージを送信するには、myQueueItem 出力バインドのメッセージ配列を定義します。You can send multiple messages at once by defining a message array for the myQueueItem output binding. 次の JavaScript コードは、受け取った HTTP 要求ごとにハードコーディングされた値を含む 2 つのキュー メッセージを送信します。The following JavaScript code sends two queue messages with hard-coded values for each HTTP request received.

module.exports = function(context) {
    context.bindings.myQueueItem = ["message 1","message 2"];
    context.done();
};

出力 - 属性Output - attributes

プリコンパイル済み C# 関数では、NuGet パッケージ Microsoft.Azure.WebJobs で定義されている QueueAttribute を使用します。For precompiled C# functions, use the QueueAttribute, which is defined in NuGet package Microsoft.Azure.WebJobs.

この属性は、out パラメーターまたは関数の戻り値に適用されます。The attribute applies to an out parameter or the return value of the function. 次の例のように、属性のコンストラクターはキューの名前を受け取ります。The attribute's constructor takes the name of the queue, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  TraceWriter log)
{
    ...
}

次の例で示すように、Connection プロパティを設定して、使用するストレージ アカウントを指定できます。You can set the Connection property to specify the storage account to use, as shown in the following example:

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items, Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  TraceWriter log)
{
    ...
}

完全な例については、出力 - プリコンパイル済み C# の例に関する記事をご覧ください。For a complete example, see Output - precompiled C# example.

StorageAccount 属性を使用して、クラス、メソッド、またはパラメーターのレベルでストレージ アカウントを指定できます。You can use the StorageAccount attribute to specify the storage account at class, method, or parameter level. 詳細については、トリガー - 属性をご覧ください。For more information, see Trigger - attributes.

出力 - 構成Output - configuration

次の表は、function.json ファイルと Queue 属性で設定したバインド構成のプロパティを説明しています。The following table explains the binding configuration properties that you set in the function.json file and the Queue attribute.

function.json のプロパティfunction.json property 属性のプロパティAttribute property 説明Description
typetype 該当なしn/a queue に設定する必要があります。Must be set to queue. このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。This property is set automatically when you create the trigger in the Azure portal.
directiondirection 該当なしn/a out に設定する必要があります。Must be set to out. このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。This property is set automatically when you create the trigger in the Azure portal.
namename 該当なしn/a 関数コード内のキューを表す変数の名前。The name of the variable that represents the queue in function code. $return に設定して、関数の戻り値を参照します。Set to $return to reference the function return value.
queueNamequeueName QueueNameQueueName キューの名前。The name of the queue.
connectionconnection ConnectionConnection このバインドに使用するストレージ接続文字列を含むアプリ設定の名前です。The name of an app setting that contains the Storage connection string to use for this binding. アプリ設定の名前が "AzureWebJobs" で始まる場合は、ここで名前の残りの部分のみを指定できます。If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. たとえば、connection を "MyStorage" に設定した場合、Functions ランタイムは "AzureWebJobsMyStorage" という名前のアプリ設定を探します。For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." connection を空のままにした場合、Functions ランタイムは、アプリ設定内の AzureWebJobsStorage という名前の既定のストレージ接続文字列を使用します。If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

ローカルで開発している場合、アプリ設定は local.settings.json ファイルに保存されます。When you're developing locally, app settings go into the local.settings.json file.

出力 - 使用方法Output - usage

C# と C# スクリプトで単一のキュー メッセージを書き込むには、out T paramName などのメソッドのパラメーターを使用します。In C# and C# script, write a single queue message by using a method parameter such as out T paramName. C# スクリプトでは、paramNamefunction.jsonname プロパティで指定された値です。In C# script, paramName is the value specified in the name property of function.json. out パラメーターではなくメソッドの戻り値の型を使用することができます。T は次に示すいずれかの型の場合があります。You can use the method return type instead of an out parameter, and T can be any of the following types:

C# と C# スクリプトで複数のキュー メッセージを書き込むには、次のいずれかの型を使用します。In C# and C# script, write multiple queue messages by using one of the following types:

  • ICollector<T> または IAsyncCollector<T>ICollector<T> or IAsyncCollector<T>
  • CloudQueueCloudQueue

JavaScript 関数の場合は、context.bindings.<name> を使用して出力キュー メッセージにアクセスします。In JavaScript functions, use context.bindings.<name> to access the output queue message. キュー項目ペイロードには、文字列または JSON のシリアル化可能なオブジェクトを使用できます。You can use a string or a JSON-serializable object for the queue item payload.

次のステップNext steps