共用方式為

Azure Functions 的 Azure IoT 中樞繫結

  • 發行項

這組文章說明如何使用適用於 IoT 中樞 的 Azure Functions 系結。 IoT 中樞 支援是以 Azure 事件中樞 系結為基礎。

重要

雖然下列程式代碼範例使用事件中樞 API，但指定的語法適用於 IoT 中樞 函式。

動作 類型
回應傳送至IoT中樞事件數據流的事件。 觸發程序

安裝擴充功能

您安裝的延伸模組 NuGet 套件取決於您在函式應用程式中使用的 C# 模式：

函式會在隔離的 C# 背景工作進程中執行。 若要深入瞭解，請參閱 在隔離背景工作程序中執行 C# Azure Functions 的指南。

擴充功能的功能會根據擴充功能版本而有所不同：

此版本引進了使用身分識別而非秘密進行連線的能力。 如需使用受控識別設定函數應用程式的教學課程，請參閱使用身分識別型連線建立函數應用程式的教學課程。

此版本支援透過 .NET Aspire 整合來設定觸發程式和系結。

藉由安裝 NuGet 套件 5.x 版，將延伸模組新增至您的專案。

安裝搭售方案

事件中樞延伸模組是延伸模組套件組合的一 部分，此套件組合會在您的host.json項目檔中指定。 您可能需要修改此套件組合來變更系結的版本，或尚未安裝套件組合。 若要深入瞭解，請參閱 延伸模組套件組合。

此版本引進了使用身分識別而非秘密進行連線的能力。 如需使用受控識別設定函數應用程式的教學課程，請參閱使用身分識別型連線建立函數應用程式的教學課程。

您可以從延伸模組套件組合 v3 新增此版本的延伸模組，方法是在檔案中 host.json 新增或取代下列程式代碼：

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

若要深入瞭解，請參閱 更新延伸模組。

繫結型別

.NET 支援的系結類型取決於延伸模組版本和 C# 執行模式，這可以是下列其中一個選項：

隔離式背景工作處理序類別庫編譯的 C# 函式會在與執行階段隔離的處理序中執行。

選擇版本以查看模式和版本的系結類型詳細數據。

隔離的背景工作進程會根據下表支持參數類型。 支援從 Azure.Messaging.EventHubs 系結至類型，目前為預覽狀態。

事件中樞觸發程序

當您想要讓函式處理單一事件時，事件中樞觸發程式可以繫結至下列類型：

類型 描述
string 事件做為字串。 當事件是簡單的文字時，請使用 。
byte[] 事件的位元組。
JSON 可序列化型別 當事件包含 JSON 數據時，Functions 會嘗試將 JSON 數據還原串行化為一般舊的 CLR 物件 （POCO） 類型。
Azure.Messaging.EventHubs.EventData1 事件物件。
如果您要從任何舊版的事件中樞 SDK 移轉，請注意，此版本會捨棄舊版類型的支援 Body ，而支援 EventBody。

當您想要讓函式處理一批事件時，事件中樞觸發程式可以繫結至下列類型：

類型 描述
string[] 批次中的事件陣列，做為字串。 每個專案都代表一個事件。
EventData[]1 批次中的事件陣列，做為 Azure.Messaging.EventHubs.EventData 的實例。 每個專案都代表一個事件。
T[] 其中 T 是 JSON 可串行化類型1 批次中的事件陣列，做為自定義POCO類型的實例。 每個專案都代表一個事件。

1 若要使用這些類型，您必須參考 Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 或更新版本 ，以及 SDK 類型系結的常見相依性。

事件中樞輸出系結

當您想要函式撰寫單一事件時，事件中樞輸出系結可以系結至下列類型：

類型 描述
string 事件做為字串。 當事件是簡單的文字時，請使用 。
byte[] 事件的位元組。
JSON 可序列化型別 物件，表示 事件。 函式會嘗試將一般舊的CLR物件 （POCO） 類型串行化為 JSON 數據。

當您要函式寫入多個事件時，事件中樞輸出系結可以系結至下列類型：

類型 描述
T[] 其中 T 是其中一個單一事件類型 包含多個事件的陣列。 每個專案都代表一個事件。

針對其他輸出案例，請直接從 Azure.Messaging.EventHubs 建立及使用 EventHubProducerClient 與其他類型。 如需使用相依性插入從 Azure SDK 建立用戶端類型的範例，請參閱 註冊 Azure 用戶端 。

host.json 設定

host.json檔案包含控制事件中樞觸發程序的設定。 設定會根據擴充功能版本而有所不同。

{
    "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 觸發程式在叫用函式之前應該等候填滿批次的最大間隔。 只有在大於 1 且忽略時，才會考慮 minEventBatchSize 等候時間。 如果等候時間經過前可用的事件少於 minEventBatchSize ，則會使用部分批次來叫用函式。 允許最長的等候時間是10分鐘。

注意： 此間隔不是叫用函式確切計時的嚴格保證。 由於定時器精確度，誤差幅度很小。 進行調整時，部分批次的第一次調用可能會更快發生，或最多需要設定的等候時間兩次。
batchCheckpointFrequency 1 要處理的批次數目，再建立事件中樞的檢查點。
prefetchCount 300 從事件中樞急切要求並保留在本機快取中的事件數目，以允許讀取以避免等候網路作業
transportType amqpTcp 用於與事件中樞通訊的通訊協議和傳輸。 可用選項： amqpTcp、 amqpWebSockets
webProxy null 用來透過 Web 套接字與事件中樞通訊的 Proxy。 Proxy 無法與傳輸搭配 amqpTcp 使用。
customEndpointAddress null 建立事件中樞連線時要使用的位址，允許透過應用程式網關或其他主機環境所需的路徑路由傳送網路要求。 使用自定義端點位址時，仍需要事件中樞的完整命名空間，而且必須明確指定或透過 連接字串。
targetUnprocessedEventThreshold1 null 每個函式實例所需的未處理事件數目。 臨界值用於以目標為基礎的調整，以覆寫從 maxEventBatchSize 選項推斷的默認調整閾值。 設定時，未處理的事件計數總計會除以此值，以判斷所需的函式實例數目。 實例計數會四捨五入為建立平衡分割區分佈的數位。
initialOffsetOptions/type fromStart 事件數據流中的位置，以在記憶體中不存在檢查點時開始處理。 適用於所有分割區。 如需詳細資訊，請參閱 OffsetType 檔。 可用選項： fromStart、、 fromEnd、 fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null 指定要開始處理之數據流中事件加入佇列的時間。 當 設定為 fromEnqueuedTime時initialOffsetOptions/type，此設定為必要設定。 支援 DateTime.Parse（）所支援之任何格式的時間，例如 2020-10-26T20:31Z。 為了清楚起見，您也應該指定時區。 未指定時區時，Functions 會假設執行函式應用程式的本機時區，也就是在 Azure 上執行的 UTC。
clientRetryOptions/mode 指數 用於計算重試延遲的方法。 指數模式會根據退讓策略重試延遲嘗試，每次嘗試都會增加重試前等候的持續時間。 固定模式會以固定間隔重試嘗試，每個延遲都有一致的持續時間。 可用選項： exponential、 fixed
clientRetryOptions/tryTimeout 00:01:00 每次嘗試，等候事件中樞作業完成的最大持續時間。
clientRetryOptions/delay 00:00:00.80 重試嘗試之間要套用的延遲或退退因素。
clientRetryOptions/maximumDelay 00:00:01 重試嘗試之間允許的最大延遲。
clientRetryOptions/maximumRetries 3 在考慮相關聯的作業失敗之前，重試嘗試的次數上限。

1 使用 minEventBatchSize 和 maxWaitTime 需要 5.3.0 版的 Microsoft.Azure.WebJobs.Extensions.EventHubs 套件或更新版本。

2 套件 v6.0.0 Microsoft.Azure.WebJobs.Extensions.EventHubs 中的預設值maxEventBatchSize已變更。 在舊版中，這是 10。

clientRetryOptions用來重試 Functions 主機與事件中樞之間的作業（例如擷取事件和傳送事件）。 如需將重試原則套用至個別函式的資訊，請參閱 Azure Functions 錯誤處理和重試的指引。

如需 Azure Functions 2.x 及以後host.json的參考，請參閱 Azure Functions 的host.json參考。

下一步