本文介绍如何使用 IoT 中心的 Azure Functions 绑定。 IoT 中心支持基于 Azure 事件中心绑定。
若要了解设置和配置详细信息,请参阅概述。
Important: 虽然下述代码示例使用事件中心 API,但给定的语法适用于 IoT 中心函数。
使用函数触发器来响应发送到事件中心事件流的事件。 若要设置触发器,必须具有基础事件中心的读取访问权限。 触发函数时,传递给函数的消息充当字符串类型。
扩展
事件触发的函数的每个实例由单个 EventProcessorHost 实例提供支持。 触发器(由事件中心提供支持)确保只有一个 EventProcessorHost 实例能够在给定分区上获得租约。
例如,考虑如下所述的一个事件中心:
- 10 个分区
- 在所有分区之间平均分配 1000 个事件,每个分区中有 100 条消息
首次启用函数时,只有一个函数实例。 我们将第一个函数实例命名为 Function_0。 Function_0 函数具有单个 EventProcessorHost 实例,此实例在所有十个分区上都有租约。 此实例从分区 0-9 读取事件。 从此时开始,将发生下列情况之一:
-
不需要新的函数实例:在 Functions 的缩放逻辑生效之前,
Function_0能够处理所有 1,000 个事件。 在这种情况下,所有 1,000 条消息都由Function_0处理。 -
添加其他函数实例:如果 Functions 缩放逻辑确定
Function_0的消息数超出了它的处理能力,则会创建新的函数应用实例 (Function_1)。 此新函数也有一个关联的 EventProcessorHost 实例。 基础事件中心检测到新主机实例在尝试读取消息时,会在主机实例之间对分区进行负载均衡。 例如,可以将分区 0-4 分配给Function_0,将分区 5-9 分配给Function_1。 -
额外添加 N 个函数实例:如果 Functions 缩放逻辑确定
Function_0和Function_1的消息数超出了它们的处理能力,则会创建新的Functions_N函数应用实例。 会一直创建应用,直到N大于事件中心分区数为止。 在我们的示例中,事件中心再次对分区进行负载均衡,在本例中是在实例Function_0...Functions_9之间进行的。
缩放时,N 实例是一个大于事件中心分区数的数字。 此模式用于确保 EventProcessorHost 实例可供用来在其他实例释放锁时在分区上获取锁。 你只需为执行函数实例时使用的资源付费。 换句话说,不需要为过度预配的资源付费。
当所有函数执行都完成时(不管是否有错误),则会将检查点添加到关联的存储帐户。 检查点设置成功后,永远不会再次检索所有 1,000 条消息。
C#
以下示例演示用于记录事件中心触发器消息正文的 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}");
}
若要成批接收事件,请将 string 或 EventData 设为数组。
Note: 成批接收事件时,不能像上述示例那样使用
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# 脚本
以下示例演示 function.json 文件中的一个事件中心触发器绑定以及使用该绑定的 C# 脚本函数。 该函数记录事件中心触发器的消息正文。
以下示例显示了 function.json 文件中的事件中心绑定数据。
版本 2.x 及更高版本
{
"type": "eventHubTrigger",
"name": "myEventHubMessage",
"direction": "in",
"eventHubName": "MyEventHub",
"connection": "myEventHubReadConnectionAppSetting"
}
版本 1.x
{
"type": "eventHubTrigger",
"name": "myEventHubMessage",
"direction": "in",
"path": "MyEventHub",
"connection": "myEventHubReadConnectionAppSetting"
}
C# 脚本代码如下所示:
using System;
public static void Run(string myEventHubMessage, TraceWriter log)
{
log.Info($"C# function triggered to process a message: {myEventHubMessage}");
}
若要在函数代码中访问事件元数据,请绑定到 EventData 对象(需要对 Microsoft.Azure.EventHubs 使用 using 语句)。 此外,还可以通过在方法签名中使用绑定表达式来访问相同的属性。 以下示例演示了获取相同数据的两种方法:
#r "Microsoft.Azure.EventHubs"
using System.Text;
using System;
using Microsoft.ServiceBus.Messaging;
using Microsoft.Azure.EventHubs;
public static void Run(EventData myEventHubMessage,
DateTime enqueuedTimeUtc,
Int64 sequenceNumber,
string offset,
TraceWriter log)
{
log.Info($"Event: {Encoding.UTF8.GetString(myEventHubMessage.Body)}");
log.Info($"EnqueuedTimeUtc={myEventHubMessage.SystemProperties.EnqueuedTimeUtc}");
log.Info($"SequenceNumber={myEventHubMessage.SystemProperties.SequenceNumber}");
log.Info($"Offset={myEventHubMessage.SystemProperties.Offset}");
// Metadata accessed by using binding expressions
log.Info($"EnqueuedTimeUtc={enqueuedTimeUtc}");
log.Info($"SequenceNumber={sequenceNumber}");
log.Info($"Offset={offset}");
}
若要成批接收事件,请将 string 或 EventData 设为数组:
public static void Run(string[] eventHubMessages, TraceWriter log)
{
foreach (var message in eventHubMessages)
{
log.Info($"C# function triggered to process a message: {message}");
}
}
JavaScript
以下示例演示 function.json 文件中的一个事件中心触发器绑定以及使用该绑定的 JavaScript 函数。 此函数将读取事件元数据并记录消息。
以下示例显示了 function.json 文件中的事件中心绑定数据。
版本 2.x 及更高版本
{
"type": "eventHubTrigger",
"name": "myEventHubMessage",
"direction": "in",
"eventHubName": "MyEventHub",
"connection": "myEventHubReadConnectionAppSetting"
}
版本 1.x
{
"type": "eventHubTrigger",
"name": "myEventHubMessage",
"direction": "in",
"path": "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();
};
若要批量接收事件,请将 function.json 文件中的 cardinality 设为 many,如以下示例所示。
版本 2.x 及更高版本
{
"type": "eventHubTrigger",
"name": "eventHubMessages",
"direction": "in",
"eventHubName": "MyEventHub",
"cardinality": "many",
"connection": "myEventHubReadConnectionAppSetting"
}
版本 1.x
{
"type": "eventHubTrigger",
"name": "eventHubMessages",
"direction": "in",
"path": "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();
};
Python
以下示例演示 function.json 文件中的事件中心触发器绑定以及使用该绑定的 Python 函数。 此函数将读取事件元数据并记录消息。
以下示例显示了 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('Function triggered to process a message: ', event.get_body())
logging.info(' EnqueuedTimeUtc =', event.enqueued_time)
logging.info(' SequenceNumber =', event.sequence_number)
logging.info(' Offset =', event.offset)
# Metadata
for key in event.metadata:
logging.info(f'Metadata: {key} = ', event.metadata[key])
Java
以下示例演示了一个记录事件中心触发器消息正文的事件中心触发器绑定。
@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 或使用了 Optional<T> 的可为 null 的值一起使用。
特性和注释
C#
在 C# 类库中,使用 EventHubTriggerAttribute 特性。
该特性的构造函数使用事件中心的名称、使用者组的名称和包含连接字符串的应用设置的名称。 有关这些设置的详细信息,请参阅触发器配置部分。 下面是 EventHubTriggerAttribute 特性的示例:
[FunctionName("EventHubTriggerCSharp")]
public static void Run([EventHubTrigger("samples-workitems", Connection = "EventHubConnectionAppSetting")] string myEventHubMessage, ILogger log)
{
...
}
有关完整示例,请参阅触发器 - C# 示例。
C# 脚本
C# 脚本不支持特性。
JavaScript
JavaScript 不支持特性。
Python
Python 不支持特性。
Java
在 Java 函数运行时库中,对其值来自事件中心的参数使用 EventHubTrigger 注释。 带有这些注释的参数会导致函数在事件到达时运行。 可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。
配置
下表解释了在 function.json 文件和 EventHubTrigger 特性中设置的绑定配置属性。
| function.json 属性 | Attribute 属性 | 说明 |
|---|---|---|
| type | 不适用 | 必须设置为 eventHubTrigger。 在 Azure 门户中创建触发器时,会自动设置此属性。 |
| direction | 不适用 | 必须设置为 in。 在 Azure 门户中创建触发器时,会自动设置此属性。 |
| name | 不适用 | 在函数代码中表示事件项的变量的名称。 |
| 路径 | EventHubName | 仅适用于 Functions 1.x。 事件中心的名称。 当事件中心名称也出现在连接字符串中时,该值会在运行时覆盖此属性。 |
| eventHubName | EventHubName | Functions 2.x 及更高版本。 事件中心的名称。 当事件中心名称也出现在连接字符串中时,该值会在运行时覆盖此属性。 可以通过应用设置 %eventHubName% 进行引用 |
| consumerGroup | ConsumerGroup | 一个可选属性,用于设置使用者组,该组用于订阅事件中心中的事件。 如果将其省略,则会使用 $Default 使用者组。 |
| 基数 | 不适用 | 用于所有非 C# 语言。 设为 many 以启用批处理。 如果省略或设为 one,将向函数传递一条消息。在 C# 中,只要触发器具有该类型的数组,就会自动分配此属性。 |
| 连接 | Connection | 应用设置的名称,该名称中包含事件中心命名空间的连接字符串。 单击 命名空间 (而不是事件中心本身)的“连接信息”按钮,以复制此连接字符串。 此连接字符串必须至少具有读取权限才可激活触发器。 |
在本地进行开发时,应用设置将取 local.settings.json 文件的值。
事件元数据
事件中心触发器提供了几个元数据属性。 元数据属性可在其他绑定中用作绑定表达式的一部分,或者用作代码中的参数。 属性来自 EventData 类。
| 属性 | 类型 | 说明 |
|---|---|---|
PartitionContext |
PartitionContext | PartitionContext 实例。 |
EnqueuedTimeUtc |
DateTime |
排队时间 (UTC)。 |
Offset |
string |
数据相对于事件中心分区流的偏移量。 偏移量是事件中心流中的事件的标记或标识符。 该标识符在事件中心流的分区中是惟一的。 |
PartitionKey |
string |
事件数据应该发送到的分区。 |
Properties |
IDictionary<String,Object> |
事件数据的用户属性。 |
SequenceNumber |
Int64 |
事件的逻辑序列号。 |
SystemProperties |
IDictionary<String,Object> |
系统属性,包括事件数据。 |
请参阅在本文的前面部分使用这些属性的代码示例。
host.json 属性
host.json 文件包含控制事件中心触发器行为的设置。 配置因 Azure Functions 版本而异。
Functions 2.x 及更高版本
{
"version": "2.0",
"extensions": {
"eventHubs": {
"batchCheckpointFrequency": 5,
"eventProcessorOptions": {
"maxBatchSize": 256,
"prefetchCount": 512
},
"initialOffsetOptions": {
"type": "fromStart",
"enqueuedTimeUtc": ""
}
}
}
}
| 属性 | 默认 | 说明 |
|---|---|---|
| batchCheckpointFrequency | 1 | 创建 EventHub 游标检查点之前要处理的事件批数。 |
| eventProcessorOptions/maxBatchSize | 10 | 每个接收循环收到的最大事件计数。 |
| eventProcessorOptions/prefetchCount | 300 | 基础 EventProcessorHost 使用的默认预提取计数。 允许的最小值为 10。 |
| initialOffsetOptions/type | fromStart | 当存储中不存在检查点时,在事件流中开始处理事件的位置。 选项有 fromStart、fromEnd 或 fromEnqueuedTime。 fromEnd 处理在函数应用开始运行后排队的新事件。 应用于所有分区。 请参阅 EventProcessorOptions 文档了解详细信息。 |
| initialOffsetOptions/enqueuedTimeUtc | 空值 | 指定在事件流中开始处理的事件的排队时间。 如果 initialOffsetOptions/type 配置为 fromEnqueuedTime,则必需此设置。 支持 DateTime.Parse() 支持的任何格式的时间,如 2020-10-26T20:31Z。 为清楚起见,还应指定时区。 如果未指定时区,Functions 将假设是运行函数应用的计算机的本地时区,即在 Azure 上运行时的 UTC。 请参阅 EventProcessorOptions 文档了解详细信息。 |
Note: 有关 Azure Functions 2.x 及更高版本中的 host.json 参考,请参阅 Azure Functions 的 host.json 参考。
Functions 1.x
{
"eventHub": {
"maxBatchSize": 64,
"prefetchCount": 256,
"batchCheckpointFrequency": 1
}
}
| 属性 | 默认 | 说明 |
|---|---|---|
| maxBatchSize | 64 | 每个接收循环收到的最大事件计数。 |
| prefetchCount | 不适用 | 基础 EventProcessorHost 将使用的默认预提取。 |
| batchCheckpointFrequency | 1 | 创建 EventHub 游标检查点之前要处理的事件批数。 |
Note: 有关 Azure Functions 1.x 中 host.json 的参考,请参阅 Azure Functions 1.x 的 host.json 参考。
后续步骤
历史资料。此文对应 2022-08-12 的中文文档快照,适用产品版本和命令行为以原文为准。
来源与署名:Microsoft 和文档贡献者(原始作者元数据 craigshoemaker)。固定版本原文。文档采用 CC BY 4.0,示例代码采用 MIT 授权。本站将 Markdown 转为 HTML,规范化链接,移除外部媒体和导航标记。
