适用于 Azure Functions 的 Azure IoT 中心绑定Azure IoT Hub bindings for Azure Functions

此系列文章介绍如何使用 IoT 中心的 Azure Functions 绑定。This set of articles explains how to work with Azure Functions bindings for IoT Hub. IoT 中心支持基于 Azure 事件中心绑定The IoT Hub support is based on the Azure Event Hubs Binding.

重要

虽然下述代码示例使用事件中心 API,但给定的语法适用于 IoT 中心函数。While the following code samples use the Event Hub API, the given syntax is applicable for IoT Hub functions.

操作Action 类型Type
响应发送到 IoT 中心事件流的事件。Respond to events sent to an IoT hub event stream. 触发器Trigger
将事件写入 IoT 事件流Write events to an IoT event stream 输出绑定Output binding

添加到 Functions 应用Add to your Functions app

Functions 2.x 及更高版本Functions 2.x and higher

使用触发器和绑定需要引用相应的包。Working with the trigger and bindings requires that you reference the appropriate package. NuGet 包用于 .NET 类库,而扩展捆绑包用于其他所有应用程序类型。The NuGet package is used for .NET class libraries while the extension bundle is used for all other application types.

语言Language 添加方式...Add by... 备注Remarks
C#C# 安装 NuGet 包版本 3.xInstalling the NuGet package, version 3.x
C# 脚本、Java、JavaScript、PowerShellC# Script, Java, JavaScript, PowerShell 注册扩展捆绑包Registering the extension bundle 建议将 [Azure Tools 扩展]用于 Visual Studio Code。The Azure Tools extension is recommended to use with Visual Studio Code.
C# 脚本(Azure 门户中仅限联机)C# Script (online-only in Azure portal) 添加绑定Adding a binding 若要更新现有绑定扩展而不必重新发布函数应用,请参阅更新扩展To update existing binding extensions without having to republish your function app, see Update your extensions.

事件中心扩展 5.x 及更高版本Event Hubs extension 5.x and higher

新版本的事件中心绑定扩展以预览版 NuGet 包的形式提供。A new version of the Event Hubs bindings extension is available as a preview NuGet package. 此预览版引入了使用标识而不是机密进行连接的功能。This preview introduces the ability to connect using an identity instead of a secret. 对于 .NET 应用程序,它还会更改你可以绑定到的类型,并将 Microsoft.Azure.EventHubs 中的类型替换为 Azure.Messaging.EventHubs 中的新类型。For .NET applications, it also changes the types that you can bind to, replacing the types from Microsoft.Azure.EventHubs with newer types from Azure.Messaging.EventHubs.

备注

预览包不包括在扩展捆绑包中,必须手动安装。The preview package is not included in an extension bundle and must be installed manually. 对于 .NET 应用,请添加对包的引用。For .NET apps, add a reference to the package. 对于所有其他应用类型,请参阅更新扩展For all other app types, see Update your extensions.

Functions 1.xFunctions 1.x

Functions 1.x 应用会自动引用 Microsoft.Azure.WebJobs NuGet 程序包(版本 2.x)。Functions 1.x apps automatically have a reference the Microsoft.Azure.WebJobs NuGet package, version 2.x.

host.json 设置host.json settings

host.json 文件包含控制事件中心触发器行为的设置。The host.json file contains settings that control Event Hubs trigger behavior. 配置因 Azure Functions 版本而异。The configuration is different depending on the Azure Functions version.

Functions 2.x 及更高版本Functions 2.x and higher

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "batchCheckpointFrequency": 5,
            "eventProcessorOptions": {
                "maxBatchSize": 256,
                "prefetchCount": 512
            },
            "initialOffsetOptions": {
                "type": "fromStart",
                "enqueuedTimeUtc": ""
            }
        }
    }
}  
属性Property 默认Default 说明Description
batchCheckpointFrequencybatchCheckpointFrequency 11 创建 EventHub 游标检查点之前要处理的事件批数。The number of event batches to process before creating an EventHub cursor checkpoint.
eventProcessorOptions/maxBatchSizeeventProcessorOptions/maxBatchSize 1010 每个接收循环收到的最大事件计数。The maximum event count received per receive loop.
eventProcessorOptions/prefetchCounteventProcessorOptions/prefetchCount 300300 基础 EventProcessorHost 使用的默认预提取计数。The default pre-fetch count used by the underlying EventProcessorHost. 允许的最小值为 10。The minimum allowed value is 10.
initialOffsetOptions/type1initialOffsetOptions/type1 fromStartfromStart 当存储中不存在检查点时,在事件流中开始处理事件的位置。The location in the event stream from which to start processing when a checkpoint doesn't exist in storage. 选项有 fromStartfromEndfromEnqueuedTimeOptions are fromStart , fromEnd or fromEnqueuedTime. fromEnd 处理在函数应用开始运行后排队的新事件。fromEnd processes new events that were enqueued after the function app started running. 应用于所有分区。Applies to all partitions. 请参阅 EventProcessorOptions 文档了解详细信息。For more information, see the EventProcessorOptions documentation.
initialOffsetOptions/enqueuedTimeUtc1initialOffsetOptions/enqueuedTimeUtc1 空值N/A 指定在事件流中开始处理的事件的排队时间。Specifies the enqueued time of the event in the stream from which to start processing. 如果 initialOffsetOptions/type 配置为 fromEnqueuedTime,则必需此设置。When initialOffsetOptions/type is configured as fromEnqueuedTime, this setting is mandatory. 支持 DateTime.Parse() 支持的任何格式的时间,如 2020-10-26T20:31ZSupports time in any format supported by DateTime.Parse(), such as 2020-10-26T20:31Z. 为清楚起见,还应指定时区。For clarity, you should also specify a timezone. 如果未指定时区,Functions 将假设是运行函数应用的计算机的本地时区,即在 Azure 上运行时的 UTC。When timezone isn't specified, Functions assumes the local timezone of the machine running the function app, which is UTC when running on Azure. 请参阅 EventProcessorOptions 文档了解详细信息。For more information, see the EventProcessorOptions documentation.

1intitialOffsetOptions 的支持始于 EventHubs v4.2.01 Support for intitialOffsetOptions begins with EventHubs v4.2.0.

备注

有关 Azure Functions 2.x 及更高版本中的 host.json 参考,请参阅 Azure Functions 的 host.json 参考For a reference of host.json in Azure Functions 2.x and beyond, see host.json reference for Azure Functions.

Functions 1.xFunctions 1.x

{
    "eventHub": {
      "maxBatchSize": 64,
      "prefetchCount": 256,
      "batchCheckpointFrequency": 1
    }
}
属性Property 默认Default 说明Description
maxBatchSizemaxBatchSize 6464 每个接收循环收到的最大事件计数。The maximum event count received per receive loop.
prefetchCountprefetchCount 不适用n/a 基础 EventProcessorHost 将使用的默认预提取。The default pre-fetch that will be used by the underlying EventProcessorHost.
batchCheckpointFrequencybatchCheckpointFrequency 11 创建 EventHub 游标检查点之前要处理的事件批数。The number of event batches to process before creating an EventHub cursor checkpoint.

备注

有关 Azure Functions 1.x 中 host.json 的参考,请参阅 Azure Functions 1.x 的 host.json 参考For a reference of host.json in Azure Functions 1.x, see host.json reference for Azure Functions 1.x.

后续步骤Next steps