.NET 用 Azure WebJobs Service Bus クライアント ライブラリ - バージョン 5.13.3
この拡張機能は、Azure 関数からAzure Service Busにアクセスするための機能を提供します。
作業の開始
パッケージをインストールする
NuGet を使用して Service Bus 拡張機能をインストールします。
dotnet add package Microsoft.Azure.WebJobs.Extensions.ServiceBus
前提条件
Azure サブスクリプション:Azure Service Busを含む Azure サービスを使用するには、サブスクリプションが必要です。 既存の Azure アカウントをお持ちでない場合は、無料試用版にサインアップするか、アカウントの作成時に Visual Studio サブスクリプション特典を使用できます。
Service Bus 名前空間:Azure Service Busと対話するには、名前空間を使用できるようにする必要もあります。 Azure リソースの作成に慣れていない場合は、Azure portalを使用して Service Bus 名前空間を作成するためのステップバイステップ ガイドに従ってください。 また、Azure CLI、Azure PowerShell、または Azure Resource Manager (ARM) テンプレートを使用して Service Bus エンティティを作成するための詳細な手順も確認できます。
Azure で必要な Service Bus リソースをすばやく作成し、それらの接続文字列を受け取るために、次をクリックしてサンプル テンプレートをデプロイできます。
クライアントを認証する
Service Bus クライアント ライブラリがキューまたはトピックと対話するには、接続して承認する方法を理解する必要があります。 これを行う最も簡単な方法は、Service Bus 名前空間の作成時に自動的に作成される接続文字列を使用することです。 Azure の共有アクセス ポリシーに慣れていない場合は、ステップ バイ ステップ ガイドに従って Service Bus 接続文字列を入手してください。
および ServiceBusTriggerAttribute の ServiceBusAttribute プロパティはConnection、接続文字列を格納する構成プロパティを指定するために使用されます。 指定しない場合、プロパティAzureWebJobsServiceBusには接続文字列が含まれている必要があります。
ローカル開発の場合は、 ファイルをlocal.settings.json使用して接続文字列を格納します。
{
"Values": {
"<connection_name>": "Endpoint=sb://<service_bus_namespace>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=<access key>"
}
}
デプロイ時に、アプリケーション設定を使用して接続文字列を設定します。
ID ベースの認証
環境で マネージド ID が 有効になっている場合は、それを使用して Service Bus 拡張機能を認証できます。 その前に、Azure Functions開発者ガイドの説明に従ってアクセス許可が構成されていることを確認する必要があります。
ID ベースの認証を使用するには、構成設定を指定します <connection_name>__fullyQualifiedNamespace 。
{
"Values": {
"AzureWebJobsStorage": "UseDevelopmentStorage=true",
"<connection_name>__fullyQualifiedNamespace": "<service_bus_namespace>.servicebus.windows.net"
}
}
または、デプロイされたアプリの場合は、アプリケーション設定で同じ設定を 設定します。
<connection_name>__fullyQualifiedNamespace=<service_bus_namespace>.servicebus.windows.net
ID ベースの接続の構成の詳細については、 こちらを参照してください。
主要な概念
Service Bus トリガー
Service Bus トリガーを使用すると、メッセージが Service Bus キューまたはトピックに送信されたときに関数を実行できます。
Service Bus トリガーの詳細については、Azure Service Bus トリガーのチュートリアルに従ってください。
Service Bus の出力バインド
Service Bus 出力バインドを使用すると、関数で Service Bus メッセージを送信できます。
Service Bus バインドの詳細については、Azure Service Bus出力バインドに従ってください。
例
個々のメッセージの送信
属性を関数の戻り値に適用することで、個々の ServiceBus メッセージをキューまたはトピックに送信できます。 戻り値の型stringbyte[]は、または ですServiceBusMessage。
[FunctionName("BindingToReturnValue")]
[return: ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")]
public static string BindToReturnValue([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer)
{
// This value would get stored in Service Bus message body.
// The string would be UTF8 encoded.
return $"C# Timer trigger function executed at: {DateTime.Now}";
}
、、または ServiceBusMessage型stringbyte[]のパラメーターをout使用することもできます。
[FunctionName("BindingToOutputParameter")]
public static void Run(
[TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
[ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] out ServiceBusMessage message)
{
message = new ServiceBusMessage($"C# Timer trigger function executed at: {DateTime.Now}");
}
複数のメッセージを送信する
1 つの Azure 関数呼び出しから複数のメッセージを送信するには、 属性を ServiceBus または IAsyncCollector<ServiceBusReceivedMessage> パラメーターにIAsyncCollector<string>適用します。
[FunctionName("BindingToCollector")]
public static async Task Run(
[TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
[ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] IAsyncCollector<ServiceBusMessage> collector)
{
// IAsyncCollector allows sending multiple messages in a single function invocation
await collector.AddAsync(new ServiceBusMessage(new BinaryData($"Message 1 added at: {DateTime.Now}")));
await collector.AddAsync(new ServiceBusMessage(new BinaryData($"Message 2 added at: {DateTime.Now}")));
}
厳密に型指定されたモデルへのバインドの使用
ServiceBus バインドで厳密に型指定されたモデル クラスを使用するには、 属性を ServiceBus model パラメーターに適用します。 これを行うと、 を厳密に型指定されたモデルに逆シリアル化 ServiceBusMessage.Bodyしようとします。
[FunctionName("TriggerSingleModel")]
public static void Run(
[ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] Dog dog,
ILogger logger)
{
logger.LogInformation($"Who's a good dog? {dog.Name} is!");
}
ServiceBusSender を使用した複数のメッセージの送信
直接 にバインドして ServiceBusSender 、メッセージ送信を最も制御することもできます。
[FunctionName("BindingToSender")]
public static async Task Run(
[TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
[ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")] ServiceBusSender sender)
{
await sender.SendMessagesAsync(new[]
{
new ServiceBusMessage(new BinaryData($"Message 1 added at: {DateTime.Now}")),
new ServiceBusMessage(new BinaryData($"Message 2 added at: {DateTime.Now}"))
});
}
メッセージごとのトリガー
Service Bus キューまたはサブスクリプションにメッセージが送信されるたびに関数を実行するには、 属性を ServiceBusTrigger 、、または ServiceBusReceivedMessage パラメーターにstring適用byte[]します。
[FunctionName("TriggerSingle")]
public static void Run(
[ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] string messageBodyAsString,
ILogger logger)
{
logger.LogInformation($"C# function triggered to process a message: {messageBodyAsString}");
}
バッチ トリガー
受信したメッセージのバッチに対して関数を実行するには、 属性を ServiceBusTrigger 、または ServiceBusReceivedMessage[] パラメーターにstring[]適用します。
[FunctionName("TriggerBatch")]
public static void Run(
[ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")] ServiceBusReceivedMessage[] messages,
ILogger logger)
{
foreach (ServiceBusReceivedMessage message in messages)
{
logger.LogInformation($"C# function triggered to process a message: {message.Body}");
logger.LogInformation($"EnqueuedTime={message.EnqueuedTime}");
}
}
メッセージ受け取り
関数が を使用して実行された後に自動的に完了するようにメッセージを ServiceBusOptions構成できます。 メッセージ受け取りをより詳細に制御する場合は、メッセージごとのトリガーとバッチ トリガーの両方を使用して に MessageActions バインドできます。
[FunctionName("BindingToMessageActions")]
public static async Task Run(
[ServiceBusTrigger("<queue_name>", Connection = "<connection_name>")]
ServiceBusReceivedMessage[] messages,
ServiceBusMessageActions messageActions)
{
foreach (ServiceBusReceivedMessage message in messages)
{
if (message.MessageId == "1")
{
await messageActions.DeadLetterMessageAsync(message);
}
else
{
await messageActions.CompleteMessageAsync(message);
}
}
}
セッション トリガー
セッションが有効なキューまたはトピックからメッセージを受信するには、 属性に プロパティをIsSessionsEnabledServiceBusTrigger設定します。 セッションを操作する場合は、 に SessionMessageActions バインドして、セッション固有の機能に加えてメッセージ決済メソッドにアクセスできます。
[FunctionName("BindingToSessionMessageActions")]
public static async Task Run(
[ServiceBusTrigger("<queue_name>", Connection = "<connection_name>", IsSessionsEnabled = true)]
ServiceBusReceivedMessage[] messages,
ServiceBusSessionMessageActions sessionActions)
{
foreach (ServiceBusReceivedMessage message in messages)
{
if (message.MessageId == "1")
{
await sessionActions.DeadLetterMessageAsync(message);
}
else
{
await sessionActions.CompleteMessageAsync(message);
}
}
// We can also perform session-specific operations using the actions, such as setting state that is specific to this session.
await sessionActions.SetSessionStateAsync(new BinaryData("<session state>"));
}
ReceiveActions へのバインド
関数呼び出し内から追加のメッセージを受信できます。 これは、バインド パラメーターを介して関数に配信される初期メッセージの特性に基づいて、関数呼び出し内で処理するメッセージの数をより詳細に制御する必要がある場合に便利です。 受信する追加のメッセージは、関数に配信される最初のメッセージと同じ AutoCompleteMessages および MaxAutoLockRenewalDuration 構成の対象になります。 メッセージをピークすることもできます。 ピークされたメッセージは、 および MaxAutoLockRenewalDuration の構成のAutoCompleteMessages対象になりません。これらのメッセージはロックされていないため、完了できません。
[FunctionName("BindingToReceiveActions")]
public static async Task Run(
[ServiceBusTrigger("<queue_name>", Connection = "<connection_name>", IsSessionsEnabled = true)]
ServiceBusReceivedMessage message,
ServiceBusMessageActions messageActions,
ServiceBusReceiveActions receiveActions)
{
if (message.MessageId == "1")
{
await messageActions.DeadLetterMessageAsync(message);
}
else
{
await messageActions.CompleteMessageAsync(message);
// attempt to receive additional messages in this session
var receivedMessages = await receiveActions.ReceiveMessagesAsync(maxMessages: 10);
// you can also use the receive actions to peek messages
var peekedMessages = await receiveActions.PeekMessagesAsync(maxMessages: 10);
}
}
ServiceBusClient へのバインド
トリガーで使用されているのと同じ ServiceBusClient にバインドする必要がある場合があります。 これは、受信したメッセージに基づいて送信者を動的に作成する必要がある場合に便利です。
[FunctionName("BindingToClient")]
public static async Task Run(
[ServiceBus("<queue_or_topic_name>", Connection = "<connection_name>")]
ServiceBusReceivedMessage message,
ServiceBusClient client)
{
ServiceBusSender sender = client.CreateSender(message.To);
await sender.SendMessageAsync(new ServiceBusMessage(message));
}
トラブルシューティング
関数が未処理の例外をトリガーし、まだメッセージを解決していない場合、拡張機能はメッセージを破棄して、メッセージをすぐに再受信できるようにしようとします。
トラブルシューティングガイダンスの詳細については、「Azure Functionsの監視」を参照してください。
次の手順
Azure Functionsの概要または Azure 関数の作成に関するガイドを参照してください。
共同作成
このライブラリのビルド、テスト、および投稿の詳細については、 CONTRIBUTING.md を参照してください。
このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。
このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示