Azure Functions 的 Azure IoT 中樞觸發程序

發行項
04/07/2024

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

如需安裝和組態詳細數據的詳細資訊，請參閱概觀。

重要

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

使用函式觸發程式來回應傳送至事件中樞事件數據流的事件。您必須具有基礎事件中樞的讀取許可權，才能設定觸發程式。觸發函式時，傳遞給函式的訊息會輸入為字串。

使用和進階方案的事件中樞調整決策是透過以目標為基礎的調整來完成。如需詳細資訊，請參閱以目標為基礎的調整。

如需 Azure Functions 如何使用觸發程式回應傳送至事件中樞事件串流之事件的資訊，請參閱整合事件中樞與 Azure 上的無伺服器函式。

重要

本文使用索引標籤來支援多個版本的 Node.js 程式設計模型。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活且更直覺的體驗。如需 v4 模型運作方式的更多詳細資料，請參閱 Azure Functions Node.js 開發人員指南。若要深入了解 v3 與 v4 之間的差異，請參閱移轉指南。

Azure Functions 支援兩種適用於 Python 的程式設計模型。您定義系結的方式取決於您所選擇的程式設計模型。

Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。如需詳細資訊，請參閱 Python 開發人員指南。

本文支援這兩種程序設計模型。

下列範例示範根據事件中樞觸發的 C# 函式，其中輸入訊息字串會寫入記錄：

{
    private readonly ILogger<EventHubsFunction> _logger;

    public EventHubsFunction(ILogger<EventHubsFunction> logger)
    {
        _logger = logger;
    }

    [Function(nameof(EventHubFunction))]
    [FixedDelayRetry(5, "00:00:10")]
    [EventHubOutput("dest", Connection = "EventHubConnection")]
    public string EventHubFunction(
        [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
        FunctionContext context)
    {
        _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

        var message = $"Output message created at {DateTime.Now}";
        return message;
    }

重要

內含式模型支援將於 2026 年 11 月 10 日結束。強烈建議您將應用程式移轉至隔離式背景工作角色模型，以取得完整支援。

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

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

若要存取函式程序代碼中的事件元數據，請系結至 EventData 物件。您也可以在方法簽章中使用繫結運算式，以存取相同的屬性。下列範例示範取得相同資料的兩種方式：

[FunctionName("EventHubTriggerCSharp")]
public 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}");
}

若要在批次中接收事件，請建立 string 或 EventData 陣列。

注意

在批次中接收時，您無法系結至方法參數，如上述範例中的， DateTime enqueuedTimeUtc 且必須從每個 EventData 物件接收這些參數

[FunctionName("EventHubTriggerCSharp")]
public 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}");
    }
}

模型 v4
模型 v3

下列範例顯示事件中樞觸發 TypeScript 函式。函式會讀取事件元數據並記錄訊息。

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Event hub function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
    context.log('Offset =', context.triggerMetadata.offset);
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: eventHubTrigger1,
});

若要接收批次中的事件，請將設定 cardinality 為 many，如下列範例所示。

import { app, InvocationContext } from '@azure/functions';

export async function eventHubTrigger1(messages: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Event hub function processed ${messages.length} messages`);
    for (let i = 0; i < messages.length; i++) {
        context.log('Event hub message:', messages[i]);
        context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
        context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
        context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
    }
}

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: eventHubTrigger1,
});

模型 v4
模型 v3

下列範例顯示事件中樞觸發 JavaScript 函式。函式會讀取事件元數據並記錄訊息。

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'one',
    handler: (message, context) => {
        context.log('Event hub function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('SequenceNumber =', context.triggerMetadata.sequenceNumber);
        context.log('Offset =', context.triggerMetadata.offset);
    },
});

若要接收批次中的事件，請將設定 cardinality 為 many，如下列範例所示。

const { app } = require('@azure/functions');

app.eventHub('eventHubTrigger1', {
    connection: 'myEventHubReadConnectionAppSetting',
    eventHubName: 'MyEventHub',
    cardinality: 'many',
    handler: (messages, context) => {
        context.log(`Event hub function processed ${messages.length} messages`);
        for (let i = 0; i < messages.length; i++) {
            context.log('Event hub message:', messages[i]);
            context.log(`EnqueuedTimeUtc = ${context.triggerMetadata.enqueuedTimeUtcArray[i]}`);
            context.log(`SequenceNumber = ${context.triggerMetadata.sequenceNumberArray[i]}`);
            context.log(`Offset = ${context.triggerMetadata.offsetArray[i]}`);
        }
    },
});

下列範例顯示function.json檔案中的事件中樞觸發程式系結，以及使用系結的 JavaScript 函式。函式會讀取事件元數據並記錄訊息。

{
  "type": "eventHubTrigger",
  "name": "myEventHubMessage",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

以下是 JavaScript 程式碼：

module.exports = function (context, myEventHubMessage) {
    context.log('Function triggered to process a message: ', myEventHubMessage);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('SequenceNumber =', context.bindingData.sequenceNumber);
    context.log('Offset =', context.bindingData.offset);

    context.done();
};

若要在批次中接收事件，請將設定cardinalitymany為 function.json 檔案，如下列範例所示。

{
  "type": "eventHubTrigger",
  "name": "eventHubMessages",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "cardinality": "many",
  "connection": "myEventHubReadConnectionAppSetting"
}

以下是 JavaScript 程式碼：

module.exports = function (context, eventHubMessages) {
    context.log(`JavaScript eventhub trigger function called for message array ${eventHubMessages}`);

    eventHubMessages.forEach((message, index) => {
        context.log(`Processed message ${message}`);
        context.log(`EnqueuedTimeUtc = ${context.bindingData.enqueuedTimeUtcArray[index]}`);
        context.log(`SequenceNumber = ${context.bindingData.sequenceNumberArray[index]}`);
        context.log(`Offset = ${context.bindingData.offsetArray[index]}`);
    });

    context.done();
};

以下是 PowerShell 程式代碼：

param($eventHubMessages, $TriggerMetadata)

Write-Host "PowerShell eventhub trigger function called for message array: $eventHubMessages"

$eventHubMessages | ForEach-Object { Write-Host "Processed message: $_" }

下列範例顯示事件中樞觸發程式系結，以及使用系結的 Python 函式。函式會讀取事件元數據並記錄訊息。此範例取決於您使用的是 v1 或 v2 Python 程式設計模型。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="EventHubTrigger1")
@app.event_hub_message_trigger(arg_name="myhub", 
                               event_hub_name="<EVENT_HUB_NAME>",
                               connection="<CONNECTION_SETTING>") 
def test_function(myhub: func.EventHubEvent):
    logging.info('Python EventHub trigger processed an event: %s',
                myhub.get_body().decode('utf-8'))

下列範例顯示function.json檔案中的事件中樞系結數據。

{
  "type": "eventHubTrigger",
  "name": "event",
  "direction": "in",
  "eventHubName": "MyEventHub",
  "connection": "myEventHubReadConnectionAppSetting"
}

以下是 Python 程式碼：

import logging
import azure.functions as func


def main(event: func.EventHubEvent):
    logging.info(f'Function triggered to process a message: {event.get_body().decode()}')
    logging.info(f'  EnqueuedTimeUtc = {event.enqueued_time}')
    logging.info(f'  SequenceNumber = {event.sequence_number}')
    logging.info(f'  Offset = {event.offset}')

    # Metadata
    for key in event.metadata:
        logging.info(f'Metadata: {key} = {event.metadata[key]}')

下列範例顯示事件中樞觸發程式系結，此系結會記錄事件中樞觸發程式的訊息本文。

@FunctionName("ehprocessor")
public void eventHubProcessor(
  @EventHubTrigger(name = "msg",
                  eventHubName = "myeventhubname",
                  connection = "myconnvarname") String message,
       final ExecutionContext context )
       {
          context.getLogger().info(message);
 }

在 Java 函式運行時間連結庫中，對 EventHubTrigger 值來自事件中樞的參數使用註釋。具有這些批注的參數會導致函式在事件送達時執行。此批注可以搭配原生 Java 類型、POJO 或使用可為 Null 的值使用 Optional<T>。

下列範例說明大量使用 SystemProperties 和其他 Binding 選項，以進一步反省事件，並提供格式正確的 BlobOutput 日期階層式路徑。

package com.example;
import java.util.Map;
import java.time.ZonedDateTime;

import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

/**
 * Azure Functions with Event Hub trigger.
 * and Blob Output using date in path along with message partition ID
 * and message sequence number from EventHub Trigger Properties
 */
public class EventHubReceiver {

    @FunctionName("EventHubReceiver")
    @StorageAccount("bloboutput")

    public void run(
            @EventHubTrigger(name = "message",
                eventHubName = "%eventhub%",
                consumerGroup = "%consumergroup%",
                connection = "eventhubconnection",
                cardinality = Cardinality.ONE)
            String message,

            final ExecutionContext context,

            @BindingName("Properties") Map<String, Object> properties,
            @BindingName("SystemProperties") Map<String, Object> systemProperties,
            @BindingName("PartitionContext") Map<String, Object> partitionContext,
            @BindingName("EnqueuedTimeUtc") Object enqueuedTimeUtc,

            @BlobOutput(
                name = "outputItem",
                path = "iotevents/{datetime:yy}/{datetime:MM}/{datetime:dd}/{datetime:HH}/" +
                       "{datetime:mm}/{PartitionContext.PartitionId}/{SystemProperties.SequenceNumber}.json")
            OutputBinding<String> outputItem) {

        var et = ZonedDateTime.parse(enqueuedTimeUtc + "Z"); // needed as the UTC time presented does not have a TZ
                                                             // indicator
        context.getLogger().info("Event hub message received: " + message + ", properties: " + properties);
        context.getLogger().info("Properties: " + properties);
        context.getLogger().info("System Properties: " + systemProperties);
        context.getLogger().info("partitionContext: " + partitionContext);
        context.getLogger().info("EnqueuedTimeUtc: " + et);

        outputItem.setValue(message);
    }
}

屬性

進程內和隔離的背景工作進程 C# 連結庫都會使用屬性來設定觸發程式。 C# 文稿會改用function.json組態檔，如 C# 腳本指南中所述。

隔離式背景工作角色模型
內含式模型

EventHubTriggerAttribute使用在支援下列屬性的事件中樞上定義觸發程式。

參數	描述
EventHubName	事件中樞的名稱。當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。可以在應用程式設定中參考，例如`%eventHubName%`
ConsumerGroup	選擇性屬性，可設定用來訂閱中樞內事件的取用者群組。省略時，會使用取 `$Default` 用者群組。
[連接]	應用程式設定或設定集合的名稱，指定如何連線到事件中樞。若要深入了解，請參閱連線。

在 C# 類別庫中，使用支援下列屬性的 EventHubTriggerAttribute。

參數	描述
EventHubName	事件中樞的名稱。當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。可以在應用程式設定中參考，例如`%eventHubName%`
ConsumerGroup	選擇性屬性，可設定用來訂閱中樞內事件的取用者群組。省略時，會使用取 `$Default` 用者群組。
[連接]	應用程式設定或設定集合的名稱，指定如何連線到事件中樞。若要深入了解，請參閱連線。

裝飾項目

僅適用於 Python v2 程式設計模型。

針對使用裝飾項目定義的 Python v2 函式，在上 event_hub_message_trigger具有下列屬性：

屬性	說明
`arg_name`	代表函式程式碼中事件項目的變數名稱。
`event_hub_name`	事件中樞的名稱。當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。
`connection`	應用程式設定或設定集合的名稱，指定如何連線到事件中樞。請參閱連線。

如需使用 function.json 定義的 Python 函式，請參閱組態一節。

註釋

在 Java 函式運行時間連結庫中，使用 EventHubTrigger 註釋，其支援下列設定：

組態

僅適用於 Python v1 程式設計模型。

模型 v4
模型 v3

下表說明您可以在傳遞至 app.eventHub() 方法的物件options上設定的屬性。

屬性	說明
eventHubName	事件中樞的名稱。當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。可透過應用程式設定參考 `%eventHubName%`
consumerGroup	選擇性屬性，可設定用來訂閱中樞內事件的取用者群組。如果省略，則會使用 `$Default` 取用者群組。
基數	`many`設定為以啟用批處理。如果省略或設定為 `one`，則會將單一訊息傳遞至函式。
connection	應用程式設定或設定集合的名稱，指定如何連線到事件中樞。請參閱連線。

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

屬性	描述
type	必須設定為 `eventHubTrigger`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction	必須設定為 `in`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name	代表函式程式碼中事件項目的變數名稱。
eventHubName	事件中樞的名稱。當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。可透過應用程式設定參考 `%eventHubName%`
consumerGroup	選擇性屬性，可設定用來訂閱中樞內事件的取用者群組。如果省略，則會使用 `$Default` 取用者群組。
基數	`many`設定為以啟用批處理。如果省略或設定為 `one`，則會將單一訊息傳遞至函式。
connection	應用程式設定或設定集合的名稱，指定如何連線到事件中樞。請參閱連線。

下表說明您在 function.json 檔案中設定的觸發程式組態屬性，其與運行時間版本不同。

Functions 2.x+
Functions 1.x

function.json 屬性	描述
type	必須設定為 `eventHubTrigger`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction	必須設定為 `in`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name	代表函式程式碼中事件項目的變數名稱。
eventHubName	事件中樞的名稱。當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。可透過應用程式設定參考 `%eventHubName%`
consumerGroup	選擇性屬性，可設定用來訂閱中樞內事件的取用者群組。如果省略，則會使用 `$Default` 取用者群組。
基數	`many`設定為以啟用批處理。如果省略或設定為 `one`，則會將單一訊息傳遞至函式。
connection	應用程式設定或設定集合的名稱，指定如何連線到事件中樞。請參閱連線。

function.json 屬性	描述
type	必須設定為 `eventHubTrigger`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction	必須設定為 `in`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name	代表函式程式碼中事件項目的變數名稱。
path	事件中樞的名稱。當事件中樞名稱也呈現於連接字串時，該值會在執行階段覆寫這個屬性。
consumerGroup	選擇性屬性，可設定用來訂閱中樞內事件的取用者群組。如果省略，則會使用 `$Default` 取用者群組。
基數	`many`設定為以啟用批處理。如果省略或設定為 `one`，則會將單一訊息傳遞至函式。
connection	應用程式設定或設定集合的名稱，指定如何連線到事件中樞。請參閱連線。

當您在本機開發時，請在集合中的 local.settings.json 檔案Values中新增應用程式設定。

使用方式

若要深入瞭解事件中樞如何觸發和 IoT 中樞觸發程序調整，請參閱使用 Azure Functions 取用事件。

事件中樞輸出系結所支援的參數類型取決於 Functions 運行時間版本、擴充套件版本，以及所使用的 C# 形式。

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

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

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

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

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

參數類型可以是下列其中一項：

任何原生 Java 類型，例如 int、String、byte[]。
使用選擇性的可為 Null 值。
任何 POJO 類型。

若要深入瞭解，請參閱 EventHubTrigger 參考。

事件元數據

事件中樞觸發程式提供數個元數據屬性。元數據屬性可用來做為其他系結中系結表達式的一部分，或做為程式代碼中的參數。屬性來自 EventData 類別。

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

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

連線

屬性connection是環境組態的參考，其中包含包含連接字串的應用程式設定名稱。您可以選取命名空間的 [連線資訊] 按鈕，以取得此連接字串。連接字串必須是事件中樞命名空間，而不是事件中樞本身。

連接字串至少必須具有「讀取」許可權，才能啟動函式。

此連接字串應該儲存在應用程式設定中，其名稱符合系結組態的屬性所connection指定的值。

注意

IoT 中樞觸發程式不支援以身分識別為基礎的連線。如果您需要端對端使用受控識別，您可以改用 IoT 中樞路由將數據傳送至您控制的事件中樞。如此一來，輸出路由就可以使用受控識別進行驗證，事件可以使用受控識別從該事件中樞讀取。

host.json屬性

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

下一步

將事件寫入事件資料串流（輸出系結）

共用方式為

Azure Functions 的 Azure IoT 中樞觸發程序

範例

屬性

裝飾項目

註釋

組態

使用方式

事件元數據

連線

host.json屬性

下一步

意見反應

其他資源