Azure Functions 的 Azure IoT 中樞觸發程式

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

如需安裝和設定詳細資料的相關資訊,請參閱概觀

重要

下列程式碼範例使用事件中樞 API,而指定的語法適用于 IoT 中樞函式。

使用函式觸發程序將回應傳送至事件中樞事件串流。 您必須具有基礎事件中樞的讀取存取權,才能設定觸發程序。 觸發函式時,傳遞至函式的訊息會以字串的形式輸入。

調整大小

由事件所觸發的函式,其每個執行個體只會由單一 EventProcessorHost 執行個體來提供支援。 觸發程序 (由事件中樞提供) 會確保只有 1 個 EventProcessorHost 執行個體可以在指定的分割區上取得租用。

例如,請考慮以下事件中樞:

  • 10 個資料分割
  • 1000 個平均散佈於所有分割區上的事件,且每個分割區中有 100 個訊息

當您的函式首次啟用時,只會有 1 個該函式的執行個體。 讓我們將第一個函式執行個體稱為 Function_0Function_0 函式具有單一 EventProcessorHost 的執行個體,這個執行個體在全部 10 個分割區全都擁有租用。 此執行個體會從分割區 0-9 讀取事件。 從這裡開始,會發生下列其中一件事:

  • 不需要新的函式執行個體Function_0 能夠在 Functions 的規模調整邏輯開始生效之前完全處理這 1000 個事件。 在此情況下,Function_0 會完全處理這 1000 個訊息。

  • 再新增 1 個函式執行個體:如果 Functions 規模調整邏輯判斷 Function_0 所擁有的數目比能夠處理的數目還多,就會建立一個新的函數應用程式執行個體 (Function_1)。 這個新的函式也會具有相關聯的 EventProcessorHost 執行個體。 當基礎事件中樞偵測到新的主控件執行個體正在嘗試讀取訊息時,會在主控件執行個體之間進行分割區的負載平衡。 例如,分割區 0-4 可能會指派給 Function_0,分割區 5-9 則指派給 Function_1

  • 再新增 N 個函式執行個體:如果 Functions 規模調整邏輯判斷 Function_0Function_1 所擁有的訊息都比能夠處理的還多,則會建立新的 Functions_N 函數應用程式執行個體。 系統會將應用程式建立到 N 大於事件中樞分割區數目的點。 在本例中,事件中樞同樣會將分割區負載平衡,在此案例中,會跨執行個體 Function_0...Functions_9 來進行。

發生規模調整時,N 個執行個體是大於事件中樞分割區數目的數字。 使用這個模式以確保 EventProcessorHost 執行個體可用來在分割區變成可從其他執行個體使用時,取得這些分割區的鎖定。 您只需針對函式執行個體執行時所使用的資源付費。 換句話說,您不需要針對這個過度佈建付費。

當所有函式執行完成時 (不論有無錯誤),系統就會在相關聯的儲存體帳戶中新增檢查點。 當檢查點檢查成功時,就永遠不會再次擷取所有的 1000 個訊息。

下列範例顯示的 C# 函式,可記錄事件中樞觸發程序的訊息本文。

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    log.LogInformation($"C# function triggered to process a message: {myEventHubMessage}");
}

若要取得函式程式碼中事件中繼資料的存取權,請繫結至 EventData 物件 (Microsoft.Azure.EventHubs 需要 using 陳述式)。 您也可以在方法簽章中使用繫結運算式,以存取相同的屬性。 下列範例示範取得相同資料的兩種方式:

[FunctionName("EventHubTriggerCSharp")]
public static void Run(
    [EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData myEventHubMessage,
    DateTime enqueuedTimeUtc,
    Int64 sequenceNumber,
    string offset,
    ILogger log)
{
    log.LogInformation($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
    // Metadata accessed by binding to EventData
    log.LogInformation($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
    log.LogInformation($"Offset={myEventHubMessage.SystemProperties.Offset}");
    // Metadata accessed by using binding expressions in method parameters
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"SequenceNumber={sequenceNumber}");
    log.LogInformation($"Offset={offset}");
}

若要以批次方式接收事件,請讓 stringEventData 成為陣列。

注意

以批次方式接收時,您無法像上述範例中一樣使用 DateTime enqueuedTimeUtc 來繫結至方法參數,而必須從每個 EventData 物件接收這些事件

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] EventData[] eventHubMessages, ILogger log)
{
    foreach (var message in eventHubMessages)
    {
        log.LogInformation($"C# function triggered to process a message: {Encoding.UTF8.GetString(message.Body)}");
        log.LogInformation($"EnqueuedTimeUtc={message.SystemProperties.EnqueuedTimeUtc}");
    }
}

屬性和註釋

C# 類別庫中,使用 EventHubTriggerAttribute 屬性。

此屬性的建構函式接受事件中樞的名稱、取用者群組的名稱,以及包含連接字串的應用程式設定名稱。 如需這些設定的詳細資訊,請參閱觸發程序組態一節。 以下是 EventHubTriggerAttribute 屬性範例:

[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
    ...
}

如需完整範例,請參閱觸發程序 - C# 範例

組態

下表說明您在 function.json 檔案中設定的繫結設定屬性內容和 EventHubTrigger 屬性。

function.json 屬性 屬性內容 描述
type n/a 必須設為 eventHubTrigger。 當您在 Azure 入口網站中建立觸發程序時,會自動設定此屬性。
direction n/a 必須設為 in。 當您在 Azure 入口網站中建立觸發程序時,會自動設定此屬性。
name n/a 代表函式程式碼中事件項目的變數名稱。
path EventHubName 僅限 Functions 1.x。 事件中樞的名稱。 當事件中樞名稱也呈現於連接字串時,該值會在執行階段覆寫這個屬性。
eventHubName EventHubName Functions 2.x 和更新版本。 事件中樞的名稱。 當事件中樞名稱也呈現於連接字串時,該值會在執行階段覆寫這個屬性。 可透過應用程式設定 %eventHubName% 參照
consumerGroup ConsumerGroup 選擇性屬性,可設定用來訂閱中樞內事件的取用者群組。 如果省略,則會使用 $Default 取用者群組。
基數 n/a 用於所有非 C# 語言。 設定為 many 才能啟用批次處理。 如果省略或設定為 one,會傳遞單一訊息至函式。

在 C# 中,每當觸發程序具有類型的陣列時,就會自動指派此屬性。
connection [連接] 應用程式設定的名稱,其中包含事件中樞命名空間的連接字串。 按一下命名空間的 [連接資訊] 按鈕 (而不是事件中樞本身),來複製此連接字串。 此連接字串至少必須具備讀取權限,才能啟動觸發程序。

如果您使用 版本5.x 或更高版本的擴充功能,而不是連接字串,您可以提供定義連接的設定區段參考。 請參閱 連接

當您要在本機開發時,應用程式設定會進入 local.settings.json 檔案

使用量

預設

您可以針對觸發事件中樞使用下列參數類型:

其他類型

使用5.0.0 或更高版本之事件中樞延伸模組的應用程式會使用 EventData EventHubs 中的類型,而不是 EventHubs 命名空間中的類型。 此版本會捨棄舊版類型的支援, Body 以支援下列類型:

事件中繼資料

事件中樞觸發程序提供數個中繼資料屬性。 中繼資料屬性可作為其他繫結中繫結運算式的一部分或程式碼中的參數使用。 屬性來自 EventData 類別。

屬性 類型 描述
PartitionContext PartitionContext PartitionContext 執行個體。
EnqueuedTimeUtc DateTime 加入佇列的時間 (UTC)。
Offset string 相對於事件中樞資料分割串流的資料位移。 此位移是事件中樞串流中事件的標記或識別碼。 此識別碼在事件中樞串流的資料分割內是唯一的。
PartitionKey string 事件資料應該傳送至的資料分割。
Properties IDictionary<String,Object> 事件資料的使用者屬性。
SequenceNumber Int64 事件的邏輯序號。
SystemProperties IDictionary<String,Object> 系統屬性,包括事件資料。

請參閱稍早在本文中使用這些屬性的程式碼範例

host.json 屬性

檔案 host.js 包含控制事件中樞觸發程式列為的設定。 如需可用設定的詳細資訊,請參閱 host.js的設定 一節。

下一步