.NET 用 Azure WebJobs Event Hubs クライアント ライブラリ - バージョン 6.0.1

  • [アーティクル]

この拡張機能は、Azure 関数からAzure Event Hubsにアクセスするための機能を提供します。

作業の開始

パッケージをインストールする

NuGet を使用して Event Hubs 拡張機能をインストールします。

dotnet add package Microsoft.Azure.WebJobs.Extensions.EventHubs

前提条件

  • Azure サブスクリプション:Azure Event Hubsを含む Azure サービスを使用するには、サブスクリプションが必要です。 既存の Azure アカウントをお持ちでない場合は、無料試用版にサインアップするか、アカウントの作成時に Visual Studio サブスクリプション特典を使用できます。

  • Event Hubs 名前空間とイベント ハブ:Azure Event Hubsと対話するには、名前空間と Event Hub も使用できる必要があります。 Azure リソースの作成に慣れていない場合は、Azure portalを使用して Event Hub を作成するためのステップバイステップ ガイドに従ってください。 ここでは、Azure CLI、Azure PowerShell、または Azure Resource Manager (ARM) テンプレートを使用してイベント ハブを作成するための詳細な手順も確認できます。

  • BLOB ストレージを使用する Azure Storage アカウント: チェックポイントを BLOB として Azure Storage に保持するには、BLOB を使用できる Azure Storage アカウントが必要です。 Azure Storage アカウントに慣れていない場合は、Azure portalを使用してストレージ アカウントを作成するための詳細なガイドに従ってください。 また、Azure CLI、Azure PowerShell、または Azure Resource Manager (ARM) テンプレートを使用してストレージ アカウントを作成するための詳細な手順も確認できます。

デプロイ ボタン

クライアントを認証する

Event Hubs クライアント ライブラリが Event Hub と対話するには、それに接続して承認する方法を理解する必要があります。 これを行う最も簡単な方法は、Event Hubs 名前空間の作成時に自動的に作成される接続文字列を使用することです。 Event Hubs での接続文字列の使用に慣れていない場合は、詳細なガイドに従って Event Hubs 接続文字列を取得できます。

および EventHubTriggerAttribute の EventHubAttribute プロパティはConnection、接続文字列を格納する構成プロパティを指定するために使用されます。

AzureWebJobsStorage 接続文字列は、処理チェックポイント情報を保持するために使用されます。

ローカル開発では、 ファイルをlocal.settings.json使用して接続文字列を格納します。

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "<connection_name>": "Endpoint=sb://<event_hubs_namespace>.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=Jya7Eh76HU92ibsxuk1ITN8CM8Bt76YLKf5ISjU3jZ8="
  }
}

デプロイ時に、アプリケーション設定を使用して接続文字列を設定します。

ID ベースの認証

環境で マネージド ID が 有効になっている場合は、それを使用して Event Hubs 拡張機能を認証できます。 その前に、Azure Functions開発者ガイドの説明に従ってアクセス許可が構成されていることを確認する必要があります。

ID ベースの認証を使用するには、構成設定を指定します <connection_name>__fullyQualifiedNamespace 。

{
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "<connection_name>__fullyQualifiedNamespace": "{event_hubs_namespace}.servicebus.windows.net"
  }
}

または、デプロイされたアプリの場合は、アプリケーション設定で同じ設定を 設定します。

<connection_name>__fullyQualifiedNamespace={event_hubs_namespace}.servicebus.windows.net

ID ベースの接続の構成の詳細については、 こちらを参照してください。

主要な概念

イベント ハブ トリガー

イベント ハブ トリガーを使用すると、メッセージがイベント ハブに送信されたときに関数を実行できます。

Event Hub トリガーの詳細については、Azure Event Hubs トリガーのチュートリアルに従ってください。

イベント ハブの出力バインド

イベント ハブの出力バインドを使用すると、関数で Event Hub イベントを送信できます。

Event Hub バインドの詳細については、Azure Event Hubs出力バインドに従ってください。

サポートされている型

トリガーと出力のバインドでは、次の型がサポートされています。

  • EventData
  • string - 値は UTF8 エンコードを使用してエンコードされます
  • BinaryData
  • byte[]
  • カスタム モデル型は、Newtonsoft.Json を使用して JSON でシリアル化されます
  • IAsyncCollector<T> バッチ トリガーの上記の種類のいずれか
  • EventHubProducerClient 出力バインドの場合

例

個々のイベントの送信

関数の戻り値を適用することで、イベント ハブに個々の EventHubAttribute イベントを送信できます。 戻り値には、 または EventData 型をstring指定できます。 戻り値を使用する場合、パーティション キーを指定することはできません。これを行うには、「複数のイベントを送信する」に示すように、 にIAsyncCollector<EventData>バインドする必要があります。

[FunctionName("BindingToReturnValue")]
[return: EventHub("<event_hub_name>", Connection = "<connection_name>")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer)
{
    // This value would get stored in EventHub event body.
    // The string would be UTF8 encoded
    return $"C# Timer trigger function executed at: {DateTime.Now}";
}

複数のイベントの送信

1 つの Azure 関数呼び出しから複数のイベントを送信するには、 または IAsyncCollector<EventData> パラメーターに をIAsyncCollector<string>適用EventHubAttributeします。 パーティション キーは、 に IAsyncCollector<EventData>バインドする場合にのみ使用できます。

[FunctionName("BindingToCollector")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [EventHub("<event_hub_name>", Connection = "<connection_name>")] IAsyncCollector<EventData> collector)
{
    // When no partition key is used, partitions will be assigned per-batch via round-robin.
    await collector.AddAsync(new EventData($"Event 1 added at: {DateTime.Now}"));
    await collector.AddAsync(new EventData($"Event 2 added at: {DateTime.Now}"));

    // Using a partition key will help group events together; events with the same key
    // will always be assigned to the same partition.
    await collector.AddAsync(new EventData($"Event 3 added at: {DateTime.Now}"), "sample-key");
    await collector.AddAsync(new EventData($"Event 4 added at: {DateTime.Now}"), "sample-key");
}

厳密に型指定されたモデルへのバインドの使用

EventHub バインドで厳密に型指定されたモデル クラスを使用するには、 を model パラメーターに適用 EventHubAttribute します。

[FunctionName("TriggerSingleModel")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] Dog dog,
    ILogger logger)
{
    logger.LogInformation($"Who's a good dog? {dog.Name} is!");
}

EventHubProducerClient を使用して複数のイベントを送信する

直接 にバインドして EventHubProducerClient 、イベント送信を最も制御することもできます。

[FunctionName("BindingToProducerClient")]
public static async Task Run(
    [TimerTrigger("0 */5 * * * *")] TimerInfo myTimer,
    [EventHub("<event_hub_name>", Connection = "<connection_name>")] EventHubProducerClient eventHubProducerClient)
{
    // IAsyncCollector allows sending multiple events in a single function invocation
    await eventHubProducerClient.SendAsync(new[]
    {
        new EventData($"Event 1 added at: {DateTime.Now}"),
        new EventData($"Event 2 added at: {DateTime.Now}")
    });
}

イベントごとのトリガー

イベントが Event Hub に送信されるたびに関数を実行するには、 または EventData パラメーターに をEventHubTriggerAttributestring適用します。

[FunctionName("TriggerSingle")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] string eventBodyAsString,
    ILogger logger)
{
    logger.LogInformation($"C# function triggered to process a message: {eventBodyAsString}");
}

バッチ トリガー

受信したイベントのバッチに対して関数を実行するには、 または EventData[] パラメーターに をstring[]適用EventHubTriggerAttributeします。

[FunctionName("TriggerBatch")]
public static void Run(
    [EventHubTrigger("<event_hub_name>", Connection = "<connection_name>")] EventData[] events,
    ILogger logger)
{
    foreach (var e in events)
    {
        logger.LogInformation($"C# function triggered to process a message: {e.EventBody}");
        logger.LogInformation($"EnqueuedTime={e.EnqueuedTime}");
    }
}

トラブルシューティング

トラブルシューティングのガイダンスについては、「Azure Functionsの監視」を参照してください。

次のステップ

Azure Functionsの概要または Azure 関数の作成に関するガイドを参照してください。

共同作成

このライブラリのビルド、テスト、および投稿の詳細については、 CONTRIBUTING.md を参照してください。

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、「 cla.microsoft.com」を参照してください。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数