共用方式為

Azure Functions 的 Azure 服務匯流排 系結

  • 發行項

Azure Functions 會透過觸發程式和系結與 Azure 服務匯流排 整合。 與 服務匯流排整合可讓您建置回應和傳送佇列或主題訊息的函式。

動作 類型
建立 服務匯流排 佇列或主題訊息時執行函式 觸發程序
傳送 Azure 服務匯流排 訊息 輸出繫結

安裝擴充功能

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

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

將延伸模組新增至安裝此 NuGet 套件的專案。

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

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

此版本可讓您系結至來自 Azure.Messaging.ServiceBus 的類型。

此版本支援透過 .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# 函式會在與執行階段隔離的處理序中執行。

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

隔離的背景工作進程會根據下表支持參數類型。

服務匯流排觸發程序

當您想要讓函式處理單一訊息時，服務匯流排 觸發程式可以繫結至下列類型：

類型 描述
string 以字串表示的訊息。 當訊息為簡單文字時，請使用 。
byte[] 訊息的位元組。
JSON 可序列化型別 當事件包含 JSON 數據時，Functions 會嘗試將 JSON 數據還原串行化為一般舊的 CLR 物件 （POCO） 類型。
ServiceBusReceivedMessage1 訊息物件。

系結至 ServiceBusReceivedMessage時，您也可以選擇性地包含 ServiceBusMessageActions1,2 類型的參數來執行訊息結算動作。

當您想要讓函式處理一批訊息時，服務匯流排 觸發程式可以繫結至下列類型：

類型 描述
T[] 其中 T 是其中一種單一訊息類型 來自批次的事件陣列。 每個專案都代表一個事件。

系結至 ServiceBusReceivedMessage[]時，您也可以選擇性地包含 ServiceBusMessageActions1,2 類型的參數來執行訊息結算動作。

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

2 使用 ServiceBusMessageActions時，將觸發程式屬性的 屬性設定AutoCompleteMessages為 false。 這可防止運行時間在成功函式調用之後嘗試完成訊息。

服務匯流排 輸出系結

當您想要函式寫入單一訊息時，服務匯流排 輸出系結可以繫結至下列類型：

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

當您想要函式寫入多個訊息時，服務匯流排 輸出系結可以繫結至下列類型：

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

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

host.json 設定

本節描述此系結可用的組態設定，視運行時間和擴充功能版本而定。

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

這些clientRetryOptions設定僅適用於與 服務匯流排 服務的互動。 它們不會影響函式執行的重試。 如需詳細資訊，請參閱 重試。

屬性 預設 描述
mode Exponential 用於計算重試延遲的方法。 默認指數模式會根據退後策略重試嘗試，每次嘗試都會在重試前增加等候持續時間。 模式 Fixed 會以固定間隔重試嘗試，每個延遲都有一致的持續時間。
tryTimeout 00:01:00 每次嘗試等候作業的最大持續時間。
delay 00:00:00.80 重試嘗試之間要套用的延遲或退退因素。
最大延遲 00:01:00 重試嘗試之間允許的最大延遲
maxRetries 3 在考慮相關聯的作業失敗之前，重試嘗試的次數上限。
prefetchCount 0 取得或設定訊息接收者可以同時要求的訊息數目。
transportType amqpTcp 用於與 服務匯流排 通訊的通訊協定和傳輸。 可用選項： amqpTcp、 amqpWebSockets
webProxy n/a 用來透過 Web 套接字與 服務匯流排 通訊的 Proxy。 Proxy 無法與傳輸搭配 amqpTcp 使用。
autoCompleteMessages true 判斷是否要在函式成功執行之後自動完成訊息。
maxAutoLockRenewalDuration 00:05:00 將自動更新訊息鎖定的最大持續時間。 此設定僅適用於一次接收單一訊息的函式。
maxConcurrentCalls 16 回呼的並行呼叫數目上限，應該針對每個縮放實例起始。 Functions 執行階段預設會並行處理多個訊息。 只有當觸發程式上的屬性或屬性設定為 false時isSessionsEnabled，才會使用此設定。 此設定僅適用於一次接收單一訊息的函式。
maxConcurrentSessions 8 每個縮放實例可同時處理的會話數目上限。 只有當觸發程式上的屬性或屬性設定為 true時isSessionsEnabled，才會使用此設定。 此設定僅適用於一次接收單一訊息的函式。
maxMessageBatchSize 1000 將傳遞至每個函式呼叫的訊息數目上限。 此設定僅適用於接收一批訊息的函式。
minMessageBatchSize1 1 批次中所需的訊息數目下限。 只有在函式接收多個訊息且必須小於 maxMessageBatchSize時，才會套用最小值。
不嚴格保證大小下限。 部分批次會在完成之前無法準備完整批次時 maxBatchWaitTime 分派。
maxBatchWaitTime1 00:00:30 觸發程式在叫用函式之前應該等候填滿批次的最大間隔。 只有在大於 1 且忽略時，才會考慮 minMessageBatchSize 等候時間。 如果等候時間經過前可用的訊息少於 minMessageBatchSize ，則會使用部分批次來叫用函式。 最長允許的等候時間是實體訊息鎖定持續時間的 50%，這表示允許的上限為 2 分 30 秒。 否則，您可能會收到鎖定例外狀況。

注意： 此間隔不是叫用函式確切計時的嚴格保證。 由於定時器精確度，誤差幅度很小。
sessionIdleTimeout n/a 等候目前使用中會話接收訊息的時間上限。 經過此時間之後，會話將會關閉，且函式會嘗試處理另一個會話。
enableCrossEntityTransactions false 是否要啟用跨越 服務匯流排 命名空間上多個實體的交易。

1 使用 minMessageBatchSize 和 maxBatchWaitTime 需要 5.10.0 版的 Microsoft.Azure.WebJobs.Extensions.ServiceBus 套件或更新版本。

下一步