Azure Functions における Azure Service Bus の出力バインド

  • [アーティクル]

キューまたはトピック メッセージを送信するには、Azure Service Bus 出力バインドを使用します。

セットアップと構成の詳細については、概要に関する記事を参照してください。

重要

この記事では、タブを使用して、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.* 名前空間が使用されます。

重要

インプロセス モデルのサポートは 2026 年 11 月 10 日に終了します。 完全なサポートのために、アプリを分離ワーカー モデルに移行することを強くお勧めします。

このコードにより、ILogger が定義され初期化されます。

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

この例では、メッセージを受信して 2 番目のキューに書き込む C# 関数を示します。

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    var outputMessage = $"Output message created at {DateTime.Now}";
    return outputMessage;
}

 

この例では、HTTP トリガーとオブジェクトを OutputType 使用して、HTTP 応答を送信し、出力メッセージを書き込みます。

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

このコードでは、次の Service Bus 出力バインド定義を含む複数の出力の種類 OutputTypeを定義します OutputEvent。

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

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

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

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

Java 関数は、Service Bus トピックにも書き込むことができます。 次の例では、出力バインディングの構成を記述する@ServiceBusTopicOutput注釈を使用します。

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

次の例は、タイマーでトリガーされた、5 分ごとにキュー メッセージを送信する TypeScript 関数を示しています。

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

次の例は、タイマーでトリガーされた、5 分ごとにキュー メッセージを送信する JavaScript 関数を示しています。

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

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

次の例は、function.json ファイル内の Service Bus 出力バインディングと、そのバインディングを使用する PowerShell 関数を示しています。

function.json ファイルのバインディング データを次に示します。

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

関数の出力としてメッセージを作成する PowerShell を次に示します。

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

次の例では、Python で Service Bus キューに書き出す方法を示します。 この例は、v1 と v2 のどちらの Python プログラミング モデルを使用するかによって異なります。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

属性

インプロセスと分離ワーカー プロセスのどちらの C# ライブラリも、属性を使用して出力バインドを定義します。 C# スクリプトでは、C# スクリプト ガイドで説明されているように、代わりに function.json 構成ファイルを使用します。

C# クラス ライブラリでは、ServiceBusOutputAttribute を使って、出力によって書き込まれるキューまたはトピックを定義します。

次の表では、この属性を使用して設定できるプロパティについて説明します。

プロパティ 説明
EntityType エンティティ型には、キューにメッセージを送信する場合は Queue、トピックにメッセージを送信する場合は Topic のいずれかを設定します。
QueueOrTopicName メッセージの送信先となるトピックまたはキューの名前。 EntityType を使って送信先の型を指定します。
接続 Service Bus への接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。

デコレーター

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

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

プロパティ 説明
arg_name 関数コード内のキューまたはトピック メッセージを表す変数の名前。
queue_name キューの名前。 トピックではなくキューのメッセージを送信する場合にのみ設定します。
topic_name トピックの名前。 キューではなくトピックのメッセージを送信する場合にのみ設定します。
connection Service Bus への接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。

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

注釈

ServiceBusQueueOutput と ServiceBusTopicOutput 注釈を使用して、関数の出力としてメッセージを書き込むことができます。 これらの注釈で修飾されたパラメーターは OutputBinding<T> として宣言されている必要があります。ここで、T はメッセージの型に対応する型です。

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

構成

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

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

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

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

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

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

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

function.json のプロパティ 説明
type "serviceBus" に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
direction "out" に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
name 関数コード内のキューまたはトピック メッセージを表す変数の名前。 "$return" に設定して、関数の戻り値を参照します。
queueName キューの名前。 トピックではなくキューのメッセージを送信する場合にのみ設定します。
topicName トピックの名前。 キューではなくトピックのメッセージを送信する場合にのみ設定します。
connection Service Bus への接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。
accessRights (v1 のみ) 接続文字列のアクセス権。 使用できる値は manage と listen です。 既定値は manage で、connection がmanageアクセス許可を持つことを示します。 管理アクセス許可を持たない接続文字列を使用する場合は、accessRights を "listen" に設定します。 設定しないと、Functions ランタイムが管理権限を必要とする操作の試行に失敗する可能性があります。 最新バージョンの Service Bus SDK が管理の操作をサポートしていないため、Azure Functions バージョン 2.x 以降ではこのプロパティを利用できません。

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

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

使用方法

次の出力パラメーターの型は、すべての C# モダリティと拡張機能バージョンでサポートされています。

Type 説明
System.String 書き込むメッセージが単純なテキストである場合に使います。 関数が終了したときにパラメーター値が null の場合、Functions はメッセージを作成しません。
byte[] バイナリ データのメッセージを書き込む場合に使います。 関数が終了したときにパラメーター値が null の場合、Functions はメッセージを作成しません。
Object メッセージに JSON が含まれている場合、Functions はオブジェクトを JSON メッセージ ペイロードにシリアル化します。 関数が終了したときにこのパラメーターの値が null の場合、Functions は、null オブジェクトでメッセージを作成します。

メッセージング固有のパラメーター型には、追加のメッセージ メタデータが含まれます。 出力バインドによってサポートされる特定の型は、Functions ランタイムのバージョン、拡張機能パッケージのバージョン、使用する C# のモダリティによって異なります。

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

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

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

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

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

Azure Functions 1.x では、キューが存在しない場合に accessRights を manage に設定していると、ランタイムによってキューが作成されます。 Azure Functions バージョン 2.x 以降では、キューまたはトピックが既に存在する必要があります。存在しないキューまたはトピックを指定した場合、関数は失敗します。

組み込みの出力バインドではなく、Azure Service Bus SDK を使用します。

値を直接返すか、context.extraOutputs.set() を使って、出力メッセージにアクセスします。

Service Bus への出力は Push-OutputBinding コマンドレット経由で取得できます。ここでは、Push-OutputBinding ファイル内のバインディングの name パラメーターで指定された名前に一致する引数を渡します。

組み込みの出力バインドではなく、Azure Service Bus SDK を使用します。

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

接続

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

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

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

接続文字列

接続文字列は、管理資格情報の取得に関する記事の手順に従って取得します。 接続文字列は、特定のキューまたはトピックに限らず、Service Bus 名前空間のものである必要があります。

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

アプリ設定の名前が "AzureWebJobs" で始まる場合は、名前の残りの部分のみを指定できます。 たとえば、connection を "MyServiceBus" に設定した場合、Functions ランタイムは "AzureWebJobsMyServiceBus" という名前のアプリ設定を探します。 connection を空のままにした場合、Functions ランタイムは、アプリ設定内の "AzureWebJobsServiceBus" という名前の既定の Service Bus 接続文字列を使用します。

ID ベースの接続

シークレットを含む接続文字列を使う代わりに、拡張機能のバージョン 5.x 以降を使用している場合は、アプリで Microsoft Entra ID を使用できます。 これを行うには、トリガーおよびバインド構成の connection プロパティにマップされる共通のプレフィックスに設定を定義します。

このモードでは、拡張機能に次のプロパティが必要です。

プロパティ 環境変数テンプレート 説明 値の例
完全修飾名前空間 <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Service Bus の完全修飾名前空間。 <service_bus_namespace>.servicebus.windows.net

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

注意

Azure App Configuration または Key Vault を使用してマネージド ID 接続の設定を指定する場合、__ の代わりに : や / などの有効なキー区切り記号を使用して、名前が正しく解決されるようにしなければなりません。

たとえば、「 <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace 」のように入力します。

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

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

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

重要

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

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

[バインドの種類] 組み込みロールの例
トリガー 1 Azure Service Bus データ受信者、Azure Service Bus データ所有者
出力バインド Azure Service Bus データ送信者

1 Service Bus トピックからのトリガーの場合、ロール割り当てには、Service Bus サブスクリプション リソースに対する有効なスコープが必要です。 トピックだけが含まれている場合は、エラーが発生します。 Azure portal などの一部のクライアントは、ロール割り当てのスコープとして、Service Bus サブスクリプション リソースを公開しません。 このような場合、代わりに Azure CLI を使用できます。 詳しくは、「Azure Service Bus 用の Azure 組み込みロール」を参照してください。

例外とリターン コード

バインド リファレンス
Service Bus Service Bus のエラー コード
Service Bus Service Bus の制限

次のステップ