Azure Functions 的 Azure 事件网格触发器

项目
2024/10/30

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

备注

内部负载均衡器应用服务环境 (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# 函数，该函数在独立于运行时的工作进程中运行。需要独立的工作进程才能支持在非 LTS 版 .NET 和 .NET Framework 上运行的 C# 函数。
C# 脚本：主要在 Azure 门户中创建 C# 函数时使用。

重要

对进程内模型的支持将于 2026 年 11 月 10 日结束。为获得完全支持，强烈建议将应用迁移到独立工作模型。

独立工作模型
进程模型

在独立工作进程中运行 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;
        }
    }

以下示例展示了使用 CloudEvent 绑定参数的 Functions 版本 4.x 函数：

using Azure.Messaging;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class CloudEventTriggerFunction
    {
        [FunctionName("CloudEventTriggerFunction")]
        public static void Run(
            ILogger logger,
            [EventGridTrigger] CloudEvent e)
        {
            logger.LogInformation("Event received {type} {subject}", e.Type, e.Subject);
        }
    }
}

以下示例展示了使用 EventGridEvent 绑定参数的 Functions 版本 4.x 函数：

using Microsoft.Azure.WebJobs;
using Azure.Messaging.EventGrid;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridTriggerDemo
    {
        [FunctionName("EventGridTriggerDemo")]
        public static void Run([EventGridTrigger] EventGridEvent eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.Data.ToString());
        }
    }
}

下面的示例展示一个使用 JObject 绑定参数的函数：

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public static class EventGridTriggerCSharp
    {
        [FunctionName("EventGridTriggerCSharp")]
        public static void Run([EventGridTrigger] JObject eventGridEvent, ILogger log)
        {
            log.LogInformation(eventGridEvent.ToString(Formatting.Indented));
        }
    }
}

本部分包含以下示例：

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

以下示例显示了 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 的值一起使用。

模型 v4
模型 v3

以下示例展示了事件网格触发器 - 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,
});

模型 v4
模型 v3

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

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

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

以下示例演示 function.json 文件中的一个触发器绑定以及使用该绑定的 JavaScript 函数。

下面是 function.json 文件中的绑定数据：

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

JavaScript 代码如下所示：

module.exports = async function (context, eventGridEvent) {
    context.log("JavaScript Event Grid function processed a request.");
    context.log("Subject: " + eventGridEvent.subject);
    context.log("Time: " + eventGridEvent.eventTime);
    context.log("Data: " + JSON.stringify(eventGridEvent.data));
};

以下示例显示如何在 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)

下面是 function.json 文件中的绑定数据：

{
  "bindings": [
    {
      "type": "eventGridTrigger",
      "name": "event",
      "direction": "in"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

下面是 Python 代码：

import json
import logging

import azure.functions as func

def main(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 特性：

[FunctionName("EventGridTest")]
public static void EventGridTest([EventGridTrigger] JObject eventGridEvent, ILogger log)
{

批注

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

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

下表解释了在 function.json 文件中设置的绑定配置属性。

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

配置

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

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

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

使用情况

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

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

进程内 C# 类库函数支持以下类型：

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

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

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

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

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

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

可以通过在 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 存储事件。

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

后续步骤

如有疑问，请在此处向团队提交问题
调度事件网格事件

通过