次の方法で共有


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

Azure Functions は、出力バインドを設定することによって、新しい Azure Queue storage メッセージを作成できます。

セットアップと構成の詳細については、概要に関するページをご覧ください。

重要

この記事では、タブを使用して、Node.js プログラミング モデルの複数のバージョンに対応しています。 v4 モデルは一般提供されており、JavaScript と TypeScript の開発者にとって、より柔軟で直感的なエクスペリエンスが得られるように設計されています。 v4 モデルの動作の詳細については、Azure Functions Node.js 開発者ガイドを参照してください。 v3 と v4 の違いの詳細については、移行ガイドを参照してください。

Azure Functions では、Python の 2 つのプログラミング モデルがサポートされています。 バインドを定義する方法は、選択したプログラミング モデルによって異なります。

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

この記事は、両方のプログラミング モデルをサポートしています。

A C# 関数は、次の C# モードのいずれかを使用して作成できます。

  • 分離されたワーカー モデル: ランタイムから分離されたワーカー プロセスで実行されるコンパイル済みの C# 関数。 分離ワーカー プロセスは、LTS および 非 LTS バージョンの .NET および .NET Framework で実行されている C# 関数をサポートするために必要です。 分離ワーカー プロセス関数の拡張機能では、Microsoft.Azure.Functions.Worker.Extensions.* 名前空間が使用されます。
  • インプロセス モデル: Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数。 このモデルの一部では、主に C# ポータルの編集のためにサポートされている C# スクリプトを使用して Functions を実行できます。 インプロセス関数の拡張機能では、Microsoft.Azure.WebJobs.Extensions.* 名前空間が使用されます。
[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;
}

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

次の例は、HTTP 要求によってトリガーされたときにキュー メッセージを作成する Java 関数を示しています。

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

Java 関数ランタイム ライブラリで、その値が Queue Storage に書き込まれる関数のパラメーター上で @QueueOutput 注釈を使用します。 パラメーターの型は OutputBinding<T> にする必要があります。T は POJO の Java の任意のネイティブ型です。

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

次の例は、受け取った 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']);

次の例は、受け取った 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 への出力バインドを構成する方法のエンド ツー エンドの例については、次のいずれかの記事を参照してください。

次のコードの例は、HTTP によってトリガーされる関数からキュー メッセージを出力する方法を示しています。 queuetype がある構成セクションで、出力バインディングを定義します。

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

このバインディング構成で、PowerShell 関数は Push-OutputBinding を使用してキュー メッセージを作成できます。 この例では、クエリ文字列または本文のパラメーターからメッセージが作成されます。

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

一度に複数のメッセージを送信するには、メッセージ配列を定義し、Push-OutputBinding を使用してキュー出力バインドにメッセージを送信します。

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

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

次の例では、ストレージ キューに 1 つの値と複数の値を出力する方法を示します。 function.json で必要な構成は、どちらでも同じです。 この例は、v1 と v2 のどちらの Python プログラミング モデルを使用するかによって異なります。

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 への出力バインドを構成する方法のエンド ツー エンドの例については、次のいずれかの記事を参照してください。

属性

C# ライブラリで出力バインドを定義する属性は、C# クラス ライブラリを実行するモードによって異なります。

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

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

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

デコレーター

Python v2 プログラミング モデルにのみ適用されます。

デコレータを使用して定義された Python v2 関数の場合、queue_output に次のプロパティがあります。

プロパティ 説明
arg_name 関数コード内のキューを表す変数の名前。
queue_name キューの名前。
connection Azure キューへの接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。

function.json を使用して定義された Python 関数については、[構成] セクションを参照してください。

注釈

QueueOutput 注釈を使用すると、メッセージを関数の出力として書き込むことができます。 次の例は、キュー メッセージを作成する HTTP トリガー関数を示しています。

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
プロパティ 説明
name 関数シグネチャのパラメーター名を宣言します。 関数がトリガーされると、このパラメーターの値にはキュー メッセージの内容が含められます。
queueName ストレージ アカウントのキュー名を宣言します。
connection ストレージ アカウントの接続文字列を示します。

QueueOutput 注釈に関連するパラメーターは、OutputBinding<T> インスタンスとして型指定されます。

構成

"Python v1 プログラミング モデルにのみ適用されます。"

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

プロパティ 説明
queueName キューの名前。
connection Azure キューへの接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。

ローカルで開発する場合は、Values コレクション内の local.settings.json ファイルにアプリケーション設定を追加します。

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

function.json のプロパティ 説明
type queue に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
direction out に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
name 関数コード内のキューを表す変数の名前。 $return に設定して、関数の戻り値を参照します。
queueName キューの名前。
connection Azure キューへの接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。

ローカルで開発する場合は、Values コレクション内の local.settings.json ファイルにアプリケーション設定を追加します。

完全な例については、セクションの例を参照してください。

使用方法

キュー出力バインディングの使用方法は、拡張機能パッケージのバージョンと、関数アプリで使用される C# のモダリティによって異なり、次のいずれかになります。

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

バージョンを選択すると、モードとバージョンの使用状況の詳細が表示されます。

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

Type 説明
string メッセージの内容を表す文字列。 メッセージが単純なテキストである場合に使用します。
byte[] メッセージのバイト数。
JSON シリアル化可能な型 JSON メッセージの内容を表すオブジェクト。 Functions は、単純な従来の CLR オブジェクト (POCO) 型を JSON データにシリアル化しようとします。

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

Type 説明
T[] (T は単一メッセージ型の 1 つ) 複数のメッセージの内容を含む配列。 各エントリは 1 つのメッセージを表します。

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

QueueOutput 注釈を使用して関数からキューを書き込むには、次の 2 つのオプションがあります。

  • 戻り値: 注釈を関数自体に適用することにより、関数の戻り値がキューに書き込まれます。

  • 命令型: メッセージ値を明示的に設定するには、OutputBinding<T> 型の特定のパラメーターに注釈を適用します。ここで、T は POJO または任意のネイティブ Java 型です。 この構成では、setValue メソッドに値を渡すと、値がキューに書き込まれます。

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

キュー メッセージへの出力は Push-OutputBinding 経由で利用できます。この場合、function.json ファイルのバインドの name パラメーターで指定された名前と一致する引数を渡します。

構成されたキューに関数から書き込むには、次の 2 つのオプションがあります。

  • 戻り値:function.json 内の name プロパティを $return に設定します。 この構成では、関数の戻り値は Queue storage メッセージとして永続化されます。

  • 命令型:Out 型として宣言されたパラメーターの set メソッドに値を渡します。 set に渡された値は、Queue storage メッセージとして永続化されます。

接続

connection プロパティは、アプリを Azure キューに接続する方法を指定する環境構成への参照です。 次が指定される場合があります。

  • 接続文字列を含むアプリケーション設定の名前
  • まとめて ID ベースの接続を定義する、複数のアプリケーション設定の共有プレフィックスの名前。

構成された値が、1 つの設定に完全一致し、プレフィックスがその他の設定とも一致する場合は、完全一致が使用されます。

接続文字列

接続文字列を取得するには、「ストレージ アカウント アクセス キーを管理する」の手順に従います。

この接続文字列は、バインド構成の connection プロパティで指定した値と同じ名前のアプリケーション設定に格納する必要があります。

アプリ設定の名前が "AzureWebJobs" で始まる場合は、ここで名前の残りの部分のみを指定できます。 たとえば、connection を "MyStorage" に設定した場合、Functions ランタイムは "AzureWebJobsMyStorage" という名前のアプリ設定を探します。connection を空のままにした場合、Functions ランタイムは、アプリ設定内の AzureWebJobsStorage という名前の既定のストレージ接続文字列を使用します。

ID ベースの接続

バージョン 5.x 以上の拡張機能を使用している場合 (non-.NET 言語スタックの場合は bundle 3.x 以上)、シークレットで接続文字列を使用する代わりに、アプリで Microsoft Entra ID を使用できます。 ID を使用するには、トリガーとバインドの構成の connection プロパティにマップされる共通のプレフィックスに設定を定義します。

connection を "AzureWebJobsStorage" に設定する場合は、「ID を使用してホスト ストレージに接続する」を参照してください。 その他のすべての接続では、拡張機能に次のプロパティが必要です。

プロパティ 環境変数テンプレート 説明 値の例
Queue サービス URI <CONNECTION_NAME_PREFIX>__queueServiceUri1 接続している Queue サービスのデータ プレーン URI。HTTPS スキームを使用します。 https://<storage_account_name>.queue.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri はエイリアスとして使用できます。 両方の形式が指定された場合、queueServiceUri の形式が使用されます。 全体の接続構成が BLOB、キュー、テーブル間で使用される場合、serviceUri 形式は指定できません。

接続をカスタマイズするには、他のプロパティを設定します。 「ID ベース接続に共通のプロパティ」を参照してください。

Azure Functions サービスでホストされている場合、ID ベースの接続では、マネージド ID が使用されます。 ユーザー割り当て ID を credential および clientID プロパティで指定できますが、システム割り当て ID が既定で使用されます。 リソース ID を使用したユーザー割り当て ID の構成はサポートされていないことに注意してください。 ローカル開発などの他のコンテキストで実行する場合は、代わりに開発者 ID が使用されますが、カスタマイズすることもできます。 ID ベースの接続によるローカル開発に関するページをご覧ください。

ID にアクセス許可を付与する

使用されている ID が何であれ、目的のアクションを実行するためのアクセス許可が必要です。 ほとんどの Azure では、これはそれらのアクセス許可を提供する組み込みロールまたはカスタム ロールを使って、Azure RBAC でロールを割り当てる必要があることを意味します。

重要

すべてのコンテキストに必要ではない一部のアクセス許可がターゲット サービスによって公開される場合があります。 可能であれば、最小限の特権の原則に従い、必要な特権だけを ID に付与します。 たとえば、アプリがデータ ソースからの読み取りのみを行う必要がある場合は、読み取りアクセス許可のみを持つロールを使用します。 サービスへの書き込みも可能なロールを割り当てることは、読み取り操作に対するアクセス許可が過剰になるため、不適切です。 同様に、ロールの割り当てが、読み取る必要のあるリソースだけに限定されていることを確認する必要があります。

実行時にキューへのアクセスを提供するロールの割り当てを作成する必要があります。 所有者のような管理ロールでは十分ではありません。 次の表は、通常の操作で Queue Storage の拡張機能を使用するときに推奨される組み込みロールを示しています。 アプリケーションでは、記述したコードに基づいて追加のアクセス許可が必要になる場合があります。

[バインドの種類] 組み込みロールの例
トリガー ストレージ キュー データ閲覧者ストレージ キュー データのメッセージ プロセッサ
出力バインド ストレージ キュー データ共同作成者ストレージ キュー データのメッセージ送信者

例外とリターン コード

バインド リファレンス
キュー キュー エラー コード
BLOB、テーブル、キュー ストレージ エラー コード
BLOB、テーブル、キュー トラブルシューティング

次のステップ