Azure Functions における Azure Queue storage の出力バインド

Python v2 プログラミング モデルでは、Python 関数コードでデコレーターを使用してバインドを直接定義できます。 詳細については、「Python 開発者ガイド」を参照してください。

Python v1 プログラミング モデルでは、関数フォルダー内の個別の function.json ファイルでバインドを定義する必要があります。 詳細については、「Python 開発者ガイド」を参照してください。

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs.ToString()}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

次の例は、受け取った HTTP 要求ごとにキュー メッセージを作成する C# 関数を示しています。

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

次の例は、受け取った HTTP 要求ごとにキュー メッセージを作成する TypeScript 関数を示しています。

import { app, HttpRequest, HttpResponseInit, InvocationContext, output } from '@azure/functions';

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

複数のメッセージを出力するには、1 つのオブジェクトではなく配列を返します。 次に例を示します。

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

TypeScript のサンプルは、モデル v3 には記載されていません。

次の例は、受け取った HTTP 要求ごとにキュー メッセージを作成する HTTPトリガー JavaScript 関数 を示しています。

const { app, output } = require('@azure/functions');

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

複数のメッセージを出力するには、1 つのオブジェクトではなく配列を返します。 次に例を示します。

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

Queue Storage への出力バインドを構成する方法のエンド ツー エンドの例については、次のいずれかの記事を参照してください。

• Visual Studio Code を使用して関数を Azure Storage に接続する
• コマンド ライン ツールを使用して関数を Azure Storage に接続する

次の例は、function.json ファイルの HTTP トリガー バインドと、そのバインドを使用する JavaScript 関数を示しています。 この関数では、受け取った HTTP 要求ごとにキュー項目を作成します。

function.json ファイルを次に示します。

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

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

JavaScript コードを次に示します。

module.exports = async function (context, input) {
    context.bindings.myQueueItem = input.body;
};

一度で複数のメッセージを送信するには、myQueueItem 出力バインドのメッセージ配列を定義します。 次の JavaScript コードは、受け取った HTTP 要求ごとにハードコーディングされた値を含む 2 つのキュー メッセージを送信します。

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

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

Queue Storage への出力バインドを構成する方法のエンド ツー エンドの例については、次のいずれかの記事を参照してください。

• Visual Studio Code を使用して関数を Azure Storage に接続する
• コマンド ライン ツールを使用して関数を Azure Storage に接続する

ストレージ キュー バインディングは function.json で定義され、そこで type は queue に設定されます。

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

キューに個々のメッセージを設定するには、 set メソッドに 1 つの値を渡します。

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

キュー上で複数のメッセージを作成するには、パラメーターを適切なリスト型として宣言し、値の配列 (リスト型と一致する) を set メソッドに渡します。

import azure.functions as func
import typing

def main(req: func.HttpRequest, msg: func.Out[typing.List[str]]) -> func.HttpResponse:

    msg.set(['one', 'two'])

    return 'OK'

分離ワーカー プロセスで実行する場合、次の例に示すように、キューの名前を受け取る QueueOutputAttribute を使用します。

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

分離ワーカー プロセスで実行される場合、返される変数のみがサポートされます。 出力パラメーターは使用できません。

C# クラス ライブラリでは、QueueAttribute を使用します。 C# スクリプトでは、C# スクリプト ガイドで説明されているように、代わりに function.json 構成ファイルを使用します。

この属性は、out パラメーターまたは関数の戻り値に適用されます。 次の例のように、属性のコンストラクターはキューの名前を受け取ります。

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

次の例で示すように、Connection プロパティを設定して、使用するストレージ アカウントを指定できます。

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

StorageAccount 属性を使用して、クラス、メソッド、またはパラメーターのレベルでストレージ アカウントを指定できます。 詳細については、「トリガー - 属性」をご覧ください。

次の表では、output.storageQueue() メソッドに渡される options オブジェクトに対して設定できるプロパティについて説明します。

次の表は、function.json ファイルで設定したバインド構成のプロパティを説明しています。

分離ワーカー プロセス クラス ライブラリでコンパイルされた C# 関数は、ランタイムから分離されたプロセスで実行されます。

インプロセス クラス ライブラリは、Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数です。

out T paramName などのメソッドのパラメーターを使用して、単一のキュー メッセージを書き込みます。 out パラメーターではなくメソッドの戻り値の型を使用することができます。T は次に示すいずれかの型の場合があります。

• JSON としてシリアル化可能なオブジェクト
• string
• byte[]
• QueueMessage

これらの型の使用例については、拡張機能の GitHub リポジトリに関するページを参照してください。

キューに複数のメッセージを書き込むには、次のいずれかの型を使用します。

• ICollector<T> または IAsyncCollector<T>
• QueueClient

QueueMessage および QueueClient の使用例については、「拡張機能の GitHub リポジトリ」に関するページを参照してください。

属性は Connection プロパティを受け取りますが、 Connection を使用してストレージ アカウント接続を指定することもできます。 これは、ライブラリ内の他の関数とは異なるストレージ アカウントを使用する必要がある場合に実行できます。 コンストラクターは、ストレージ接続文字列を含むアプリ設定の名前を受け取ります。 属性は、パラメーター、メソッド、またはクラス レベルで適用できます。 次の例では、クラス レベルとメソッド レベルを示します。

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

使用するストレージ アカウントは、次の順序で決定されます。

• トリガーまたはバインド属性の Connection プロパティ。
• トリガーまたはバインド属性と同じパラメーターに適用された StorageAccount 属性。
• 関数に適用される StorageAccount 属性。
• クラスに適用される StorageAccount 属性。
• AzureWebJobsStorage アプリケーション設定で定義されている、関数アプリの既定のストレージ アカウント。

out T paramName などのメソッドのパラメーターを使用して、単一のキュー メッセージを書き込みます。 out パラメーターではなくメソッドの戻り値の型を使用することができます。T は次に示すいずれかの型の場合があります。

• JSON としてシリアル化可能なオブジェクト
• string
• byte[]
• CloudQueueMessage

CloudQueueMessage にバインドしようとしてエラー メッセージが表示された場合は、適切な Storage SDK バージョンへの参照があることを確認してください。

キューに複数のメッセージを書き込むには、次のいずれかの型を使用します。

• ICollector<T> または IAsyncCollector<T>
• CloudQueue

属性は Connection プロパティを受け取りますが、 Connection を使用してストレージ アカウント接続を指定することもできます。 これは、ライブラリ内の他の関数とは異なるストレージ アカウントを使用する必要がある場合に実行できます。 コンストラクターは、ストレージ接続文字列を含むアプリ設定の名前を受け取ります。 属性は、パラメーター、メソッド、またはクラス レベルで適用できます。 次の例では、クラス レベルとメソッド レベルを示します。

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

使用するストレージ アカウントは、次の順序で決定されます。

• トリガーまたはバインド属性の Connection プロパティ。
• トリガーまたはバインド属性と同じパラメーターに適用された StorageAccount 属性。
• 関数に適用される StorageAccount 属性。
• クラスに適用される StorageAccount 属性。
• AzureWebJobsStorage アプリケーション設定で定義されている、関数アプリの既定のストレージ アカウント。

関数で 1 つのメッセージを書き込む場合、キュー出力バインドは次の型にバインドできます

関数で複数のメッセージを書き込む場合、キュー出力バインドは次の型にバインドできます

その他の出力シナリオでは、Azure.Storage.Queues から型を直接作成して使用します。

分離ワーカー プロセスでは、現在、文字列パラメーターへのバインドのみがサポートされています。

値を直接返すか、context.extraOutputs.set() を使用することで出力メッセージにアクセスします。 キュー項目ペイロードには、文字列または JSON のシリアル化可能なオブジェクトを使用できます。

context.bindings.<name> を使用して出力イベントにアクセスします。<name> は function.json の name プロパティで指定された値です。 キュー項目ペイロードには、文字列または JSON のシリアル化可能なオブジェクトを使用できます。