次の方法で共有

Azure FunctionsのバインドをAzure IoT Hubする

この一連の記事では、IoT HubのAzure Functions バインドを操作する方法について説明します。 IoT Hubのサポートは、Azure Event Hubs Binding に基づいています。

重要

次のコード サンプルでは Event Hub API を使用していますが、指定された構文はIoT Hub関数に適用できます。

アクション タイプ
IoT Hub のイベント ストリームに送信されたイベントに応答する Trigger

拡張機能のインストール

インストールする拡張機能 NuGet パッケージは、関数アプリで使用している C# モードによって異なります。

関数は分離された C# ワーカー プロセスで実行されます。 詳細については、分離されたワーカー プロセスで C# Azure Functionsを実行するための Guide を参照>。

拡張機能の機能性は、拡張機能のバージョンによって異なります。

このバージョンでは、シークレットではなく ID を使用して接続する機能が導入されています。 マネージド ID を使用して関数アプリを構成するチュートリアルについては、ID ベースの接続を使用した関数アプリの作成に関 するチュートリアルを参照してください。

このバージョンでは、.NET Aspire 統合を使用したトリガーとバインドの構成がサポートされています。

NuGet パッケージ バージョン 6.x をインストールして、拡張機能をプロジェクトに追加します。

バンドルのインストール

アプリでこのバインド拡張機能を使用できるようにするには、プロジェクトのルートにある host.json ファイルに次の extensionBundle 参照が含まれていることを確認します。

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

この例では、versionの[4.0.0, 5.0.0)値は、少なくとも4.0.0が5.0.0未満のバンドル バージョン (4.x のすべての潜在的なバージョンを含む) を使用するように Functions ホストに指示します。 この表記は、v4.x 拡張機能バンドルの利用可能な最新のマイナー バージョンでアプリを効果的に維持します。

可能であれば、最新の拡張機能バンドルメジャー バージョンを使用し、ランタイムが最新のマイナー バージョンを自動的に維持できるようにする必要があります。 最新のバンドルの内容は、extension バンドルのリリース ページで確認できます。 詳細については、「Azure Functions拡張機能バンドルを参照してください。

バインドの種類

.NETでサポートされるバインドの種類は、拡張機能のバージョンと C# 実行モードの両方によって異なります。次のいずれかのオプションを使用できます。

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

バージョンを選択すると、モードとバージョンのバインドの種類の詳細が表示されます。

分離ワーカー プロセスは、以下の表に従ってパラメーターの型をサポートします。 [Azure からの型へのバインドのサポート。Messaging.EventHubs] はプレビュー段階です。

Event Hubs トリガー

関数で 1 つのイベントを処理するとき、Event Hubs トリガーは次の型にバインドできます。

タイプ 説明
string イベントを表す文字列。 イベントが単純なテキストのときに使用します。
byte[] イベントのバイト数。
JSON シリアル化可能な型 イベントに JSON データが含まれている場合、Functions は JSON データを単純な従来の CLR オブジェクト (POCO) 型に逆シリアル化しようとします。
Azure。Messaging.EventHubs.EventData1 イベント オブジェクト。
古いバージョンの Event Hubs SDK から移行する場合、このバージョンでは Body を優先してレガシの 型のサポートが削除されることに注意してください。

関数でイベントのバッチを処理するとき、Event Hubs トリガーは次の型にバインドできます。

タイプ 説明
string[] バッチのイベントの配列を表す文字列。 各エントリは 1 つのイベントを表します。
EventData[] 1 Azureのインスタンスとしてのバッチからのイベントの配列。Messaging.EventHubs.EventData。 各エントリは 1 つのイベントを表します。
T[] (T は JSON シリアル化可能な型1) バッチのイベントの配列を表す、カスタム POCO 型のインスタンス。 各エントリは 1 つのイベントを表します。

1 これらの型を使用するには、Microsoft を参照する必要があります。Azure。Functions.Worker.Extensions.EventHubs 5.5.0 以降 および SDK 型バインドのcommon 依存関係。

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

関数で 1 つのイベントを書き込むとき、Event Hubs 出力バインドは次の型にバインドできます。

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

関数で複数のイベントを書き込むとき、Event Hubs 出力バインドは次の型にバインドできます。

タイプ 説明
T[] (T は単一のイベントの種類の 1 つ) 複数のイベントを含む配列。 各エントリは 1 つのイベントを表します。

その他の出力シナリオでは、EventHubProducerClient を作成し、Azure の他の型と共に使用します。Messaging.EventHubs 直接。 依存関係の挿入を使用してAzure SDKからクライアントの種類を作成する例については、「クライアントをAzure登録する」を参照してください。

SDK バインドの種類

Azure EventHub の SDK の種類はプレビュー段階です。 Python EventHub の SDK バインドのサンプルに従って、Pythonで Event Hubs の SDK の種類を使用します。

重要

SDK 型バインドを使用するには、Python v2 プログラミング モデルが必要です。

バインド パラメーターの種類 サンプル
EventHub トリガー EventData EventData

host.json 設定

host.json ファイルには、Event Hubs トリガーの動作を制御する設定が含まれています。 構成は、拡張機能のバージョンによって異なります。

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
プロパティ 既定値 説明
maxEventBatchSize2 100 単一の呼び出しでバッチに含まれるイベントの最大数。 1 以上を指定してください。
minEventBatchSize1 1 バッチで必要な最小イベント数。 最小値は、関数が複数のイベントを受信していて、maxEventBatchSize より小さくする必要がある場合にのみ適用されます。
最小サイズは厳密には保証されません。 部分的なバッチは、maxWaitTime が経過する前に完全なバッチを準備できない場合にディスパッチされます。 部分的なバッチは、スケーリングが行われた後の関数の最初の呼び出しでも行われる可能性があります。
maxWaitTime1 00:01:00 関数を呼び出す前に、トリガーがバッチの入力を待機する最大間隔。 待機時間は、minEventBatchSize が 1 より大きい場合にのみ考慮され、それ以外の場合は無視されます。 待機時間が経過する前に使用可能イベントが minEventBatchSize 未満の場合、関数は部分的なバッチで呼び出されます。 許容される最長待機時間は 10 分です。

注: この間隔は、関数が呼び出される正確なタイミングを厳密に保証するものではありません。 タイマーの精度により、わずかな誤差が生じます。 スケーリングが行われると、部分的なバッチでの最初の呼び出しがより迅速に行われるか、構成された待機時間の最大 2 倍かかる場合があります。
batchCheckpointFrequency 1 イベント ハブのチェックポイントを作成する前に処理するバッチの数。

手記：ターゲットベーススケーリングでサポートされるホスティングプランでこの値を1以上に設定すると、誤ったスケーリング動作を引き起こす可能性があります。 プラットフォームは未処理のキューサイズを「現在の位置 - チェックポイント位置」として計算しますが、バッチが処理されたがまだチェックポイントされていない場合、未処理メッセージを誤って示す可能性があり、メッセージが残らない場合に適切なスケーリングインが妨げられます。
プリフェッチカウント 300 Event Hubs から要求され、ローカル キャッシュに保持されるイベントの数。ネットワーク操作の待機を避けるために、読み取りを許可します
transportType amqpTcp Event Hubs との通信に使用されるプロトコルとトランスポート。 使用可能なオプション: amqpTcp、amqpWebSockets
webProxy null 値 Web ソケット経由の Event Hubs との通信に使用されるプロキシ。 プロキシを amqpTcp トランスポートと併用することはできません。
customEndpointAddress null 値 Event Hubs への接続を確立するときに使用するアドレス。アプリケーション ゲートウェイまたはホスト環境に必要なその他のパス経由で、ネットワーク要求をルーティングすることができます。 カスタム エンドポイント アドレスを使用する場合は、イベント ハブの完全修飾名前空間が引き続き必要であり、明示的に指定するか、connection stringを介して指定する必要があります。
targetUnprocessedEventThreshold1 null 値 関数インスタンスごとに必要な未処理のイベントの数。 このしきい値は、ターゲット ベースのスケーリングで使用され、maxEventBatchSize オプションから推定される既定のスケーリングしきい値をオーバーライドします。 設定すると、未処理のイベント数の合計がこの値で除算され、必要な関数インスタンスの数が決定されます。 インスタンス数は、バランスの取れたパーティション分散を作成する数値に切り上げられます。
initialOffsetOptions/type fromStart チェックポイントがストレージに存在しない場合に処理を開始するイベント ストリーム内の位置。 すべてのパーティションに適用されます。 詳細については、OffsetType のドキュメントに関する記事を参照してください。 使用可能なオプション: fromStart、fromEnd、fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null 値 ストリームにエンキューされたイベントの処理を開始する時刻を指定します。 initialOffsetOptions/type が fromEnqueuedTime として構成されている場合、この設定は必須です。 DateTime.Parse() でサポートされている形式の時刻がサポートされます (2020-10-26T20:31Z など)。 明確にするためには、タイムゾーンも指定する必要があります。 タイムゾーンが指定されていない場合、Functions は関数アプリを実行しているマシンのローカル タイムゾーン (Azureで実行されている場合は UTC) を想定します。
clientRetryOptions/mode 指数 再試行の遅延を計算するために使用する方法です。 指数モードでは、バックオフ戦略に基づいて再試行が行われます。この場合、再試行のたびに待機する期間が長くなります。 固定モードでは、一定の間隔で再試行が行われ、遅延の時間はそれぞれ一定です。 使用可能なオプション: exponential、fixed
clientRetryOptions/tryTimeout 00:01:00 試行ごとに Event Hubs 操作の完了を待機する最大期間です。
clientRetryOptions/delay 00:00:00.80 再試行の間に適用する遅延またはバックオフ係数です。
clientRetryOptions/maximumDelay 00:00:01 再試行の間の許容される最大の遅延です。
clientRetryOptions/maximumRetries 3 関連する操作が失敗したと判断するまでの再試行の最大回数です。

1minEventBatchSize および maxWaitTime を使用するには、Microsoft.Azure.WebJobs.Extensions.EventHubs パッケージの v5.3.0 以降のバージョンが必要です。

2Microsoft.Azure.WebJobs.Extensions.EventHubs パッケージの v6.0.0 で既定の maxEventBatchSize が変更されました。 以前のバージョンでは、これは 10 でした。

clientRetryOptions は、Functions ホストと Event Hubs の間の操作 (イベントのフェッチやイベントの送信など) を再試行するために使用されます。 個々の関数に再試行ポリシーを適用する方法については、Azure Functionsエラー処理と再試行に関するガイダンスを参照してください。

Azure Functions 2.x 以降の host.json のリファレンスについては、Azure Functions の host.json リファレンスを参照してください。

次のステップ

  • Last updated on