Azure Functions 的 Azure 事件网格触发器

使用函数触发器响应事件网格源发送的事件。 必须订阅源的事件才能接收事件。 若要了解如何创建事件订阅,请参阅创建订阅。 有关绑定设置和配置的信息,请参阅概述

注意

内部负载均衡器应用服务环境 (ASE) 在原生情况下不支持事件网格触发器。 触发器使用 HTTP 请求,该请求在虚拟网络中没有网关的情况下无法访问函数应用。

重要

本文使用选项卡来支持多个版本的 Node.js 编程模型。 v4 模型目前处于预览状态,旨在为 JavaScript 和 TypeScript 开发人员提供更为灵活和直观的体验。 在升级指南中详细了解 v3 和 v4 之间的差异。

Azure Functions 支持两种 Python 编程模型。 定义绑定的方式取决于选择的编程模型。

使用 Python v2 编程模型,可以直接在 Python 函数代码中使用修饰器定义绑定。 有关详细信息,请参阅 Python 开发人员指南

本文同时支持两个编程模型。

示例

如需 HTTP 触发器示例,请参阅将事件接收到 HTTP 终结点

与事件网格触发器一起使用的输入参数的类型取决于以下三个因素:

  • Functions 运行时版本
  • 绑定扩展版本
  • C# 函数的模态。

可以使用以下 C# 模式之一创建 C# 函数:

  • 进程内类库:编译的 C# 函数,该函数在与 Functions 运行时相同的进程中运行。
  • 独立进程类库:编译的 C# 函数,该函数在独立于运行时的进程中运行。 支持在 .NET 5.0 上运行的 C# 函数需要独立的进程。
  • C# 脚本:主要在 Azure 门户中创建 C# 函数时使用。

在独立工作进程中运行 C# 函数时,需要定义事件属性的自定义类型。 下面的示例定义了一个名为 MyEventType 的类。

    public class MyEventType
    {
        public string Id { get; set; }

        public string Topic { get; set; }

        public string Subject { get; set; }

        public string EventType { get; set; }

        public DateTime EventTime { get; set; }

        public IDictionary<string, object> Data { get; set; }
    }
}

下面的示例演示如何在触发器和事件网格输出绑定中使用自定义类型:

    public static class EventGridFunction
    {
        [Function(nameof(EventGridFunction))]
        [EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
        public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
        {
            var logger = context.GetLogger(nameof(EventGridFunction));

            logger.LogInformation(input.Data.ToString());

            var outputEvent = new MyEventType()
            {
                Id = "unique-id",
                Subject = "abc-subject",
                Data = new Dictionary<string, object>
                {
                    { "myKey", "myValue" }
                }
            };

            return outputEvent;
        }
    }

本部分包含以下示例:

以下示例显示了 Java 中的触发器绑定,它们使用绑定并生成事件,首先接收 String 形式的事件,第二个接收 POJO 形式的事件。

事件网格触发器、字符串参数

  @FunctionName("eventGridMonitorString")
  public void logEvent(
    @EventGridTrigger(
      name = "event"
    )
    String content,
    final ExecutionContext context) {
      context.getLogger().info("Event content: " + content);
  }

事件网格触发器、POJO 参数

此示例使用以下 POJO 表示事件网格事件的顶级属性:

import java.util.Date;
import java.util.Map;

public class EventSchema {

  public String topic;
  public String subject;
  public String eventType;
  public Date eventTime;
  public String id;
  public String dataVersion;
  public String metadataVersion;
  public Map<String, Object> data;

}

到达后,事件的 JSON 有效负载被反序列化为 EventSchema POJO 以供函数使用。 此过程允许函数以面向对象的方式访问事件的属性。

  @FunctionName("eventGridMonitor")
  public void logEvent(
    @EventGridTrigger(
      name = "event"
    )
    EventSchema event,
    final ExecutionContext context) {
      context.getLogger().info("Event content: ");
      context.getLogger().info("Subject: " + event.subject);
      context.getLogger().info("Time: " + event.eventTime); // automatically converted to Date by the runtime
      context.getLogger().info("Id: " + event.id);
      context.getLogger().info("Data: " + event.data);
  }

Java 函数运行时库中,对其值来自事件网格的参数使用 EventGridTrigger 注释。 带有这些注释的参数会导致函数在事件到达时运行。 可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。

以下示例展示了事件网格触发器 - TypeScript 函数

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

export async function eventGridTrigger1(event: EventGridEvent, context: InvocationContext): Promise<void> {
    context.log('Event grid function processed event:', event);
}

app.eventGrid('eventGridTrigger1', {
    handler: eventGridTrigger1,
});

以下示例显示事件网格触发器 JavaScript 函数

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

app.eventGrid('eventGridTrigger1', {
    handler: (event, context) => {
        context.log('Event grid function processed event:', event);
    },
});

以下示例显示如何在 function.json 文件中配置事件网格触发器绑定。

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "eventGridEvent",
      "direction": "in"
    }
  ]
}

事件网格事件通过名为 eventGridEvent 的参数提供给函数,如下面的 PowerShell 示例所示。

param($eventGridEvent, $TriggerMetadata)

# Make sure to pass hashtables to Out-String so they're logged correctly
$eventGridEvent | Out-String | Write-Host

以下示例演示了事件网络触发器绑定以及使用该绑定的 Python 函数。 该示例取决于使用的是 v1 还是 v2 Python 编程模型

import logging
import json
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="eventGridTrigger")
@app.event_grid_trigger(arg_name="event")
def eventGridTest(event: func.EventGridEvent):
    result = json.dumps({
        'id': event.id,
        'data': event.get_json(),
        'topic': event.topic,
        'subject': event.subject,
        'event_type': event.event_type,
    })

    logging.info('Python EventGrid trigger processed an event: %s', result)

特性

进程内独立工作进程 C# 库均使用 EventGridTrigger 特性。 C# 脚本改用 function.json 配置文件,如 C# 脚本指南中所述。

下面是某个方法签名中的 EventGridTrigger 特性:

        [Function(nameof(EventGridFunction))]
        [EventGridOutput(TopicEndpointUri = "MyEventGridTopicUriSetting", TopicKeySetting = "MyEventGridTopicKeySetting")]
        public static MyEventType Run([EventGridTrigger] MyEventType input, FunctionContext context)
        {

批注

使用 EventGridTrigger 注释,可以通过提供配置值以声明方式配置事件网格绑定。 有关更多详细信息,请参阅示例配置部分。

配置

传递给方法“app.eventGrid()”的对象“options”当前不支持模型 v4 的任何属性。

配置

下表解释了在 function.json 文件中设置的绑定配置属性。 无法在 EventGridTrigger 特性中设置任何构造函数参数或属性。

function.json 属性 说明
type 必需 - 必须设置为 eventGridTrigger
direction 必需 - 必须设置为 in
name 必需 - 在函数代码中对接收事件数据的参数使用的变量名称。

有关完整示例的信息,请参阅示例部分

使用情况

事件网格触发器使用 Webhook HTTP 请求,可以使用与 HTTP 触发器相同的 host.json 设置进行配置。

事件网格触发器支持的参数类型取决于函数运行时版本、扩展包版本以及使用的 C# 形式。

如果你希望函数处理单个事件,可将事件网格触发器绑定到以下类型:

类型 说明
JSON 可序列化类型 Functions 会尝试将事件的 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。
string 字符串形式的事件。
BinaryData (预览版1
事件消息的字节数。
CloudEvent (预览版1
事件对象。 当事件网格配置为使用 CloudEvents 架构传递时使用。
EventGridEvent (预览版1
事件对象。 当事件网格配置为使用事件网格架构传递时使用。

如果你希望函数处理批量事件,可将事件网格触发器绑定到以下类型:

类型 说明
CloudEvent[],
EventGridEvent[],
string[],
BinaryData[]
批处理中的事件数组。 每个条目表示一个事件。

1 若要使用这些类型,需要引用 Microsoft.Azure.Functions.Worker.Extensions.EventGrid 3.3.0-preview1 或更高版本以及 SDK 类型绑定的常见依赖项

事件网格事件实例可通过与类型为 EventSchemaEventGridTrigger 属性关联的参数提供。

可以通过在 function.json 文件的 name 属性中配置的参数来使用事件网格实例。

可以通过在 function.json 文件的 name 属性中配置的参数(类型为 func.EventGridEvent)来使用事件网格实例。

事件架构

事件网格事件的数据在 HTTP 请求的正文中以 JSON 对象形式接收。 该 JSON 如以下示例所示:

[{
  "topic": "/subscriptions/{subscriptionid}/resourceGroups/eg0122/providers/Microsoft.Storage/storageAccounts/egblobstore",
  "subject": "/blobServices/default/containers/{containername}/blobs/blobname.jpg",
  "eventType": "Microsoft.Storage.BlobCreated",
  "eventTime": "2018-01-23T17:02:19.6069787Z",
  "id": "{guid}",
  "data": {
    "api": "PutBlockList",
    "clientRequestId": "{guid}",
    "requestId": "{guid}",
    "eTag": "0x8D562831044DDD0",
    "contentType": "application/octet-stream",
    "contentLength": 2248,
    "blobType": "BlockBlob",
    "url": "https://egblobstore.blob.core.chinacloudapi.cn/{containername}/blobname.jpg",
    "sequencer": "000000000000272D000000000003D60F",
    "storageDiagnostics": {
      "batchId": "{guid}"
    }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

显示的示例是包含一个元素的数组。 事件网格始终发送一个数组,并可能在该数组中发送多个事件。 运行时针对每个数组元素调用你的函数一次。

事件 JSON 数据中的顶级属性在所有事件类型中相同,而 data 属性的内容特定于每个事件类型。 显示的示例适用于 Blob 存储事件。

有关通用和特定于事件的属性的说明,请参阅事件网格文档中的事件属性

后续步骤