Azure Functions 的 Azure 事件网格触发器

使用函数触发器来响应发送到事件网格主题的事件。

有关设置和配置的详细信息,请参阅概述

备注

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

示例

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

3.x 版

以下示例演示绑定到 CloudEvent 的 Functions 3.x C# 函数

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 3.x C# 函数

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

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

C#(2.x 及更高版本)

以下示例演示绑定到 EventGridEventC# 函数

using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Azure.EventGrid.Models;
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());
        }
    }
}

有关详细信息,请参阅包、特性配置用法

版本 1.x

以下示例演示绑定到 JObject 的 Functions 1.x C# 函数

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Azure.WebJobs.Host;
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));
        }
    }
}

特性和注释

C# 类库中,使用 EventGridTrigger 特性。

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

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

有关完整示例,请参阅 C# 示例。

配置

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

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

使用情况

在 Azure Functions 1.x 中,可以为事件网格触发器使用以下参数类型:

  • JObject
  • string

在 Azure Functions 2.x 及更高版本中,还可以选择对事件网格触发器使用以下参数类型:

  • Microsoft.Azure.EventGrid.Models.EventGridEvent - 定义所有事件类型通用的字段的属性。

备注

如果你尝试绑定到 Microsoft.Azure.WebJobs.Extensions.EventGrid.EventGridEvent,编译器会显示“已弃用”消息并建议你改用 Microsoft.Azure.EventGrid.Models.EventGridEvent。 若要使用较新类型,请引用 Microsoft.Azure.EventGrid NuGet 包,并通过为 EventGridEvent 类型名称添加 Microsoft.Azure.EventGrid.Models 前缀来对其进行完全限定。

其他类型

使用事件网格扩展 3.0.0 或更高版本的应用使用 Azure.Messaging.EventGrid 命名空间中的 EventGridEvent 类型。 此外,还可以从 Azure.Messaging 命名空间绑定到 CloudEvent 类型。

事件架构

事件网格事件的数据在 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 存储事件。

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

EventGridEvent 类型只定义顶级属性;Data 属性是 JObject

创建订阅

若要开始接收事件网格 HTTP 请求,请创建一个事件网格订阅,用于指定可调用函数的终结点 URL。

Azure 门户

对于在 Azure 门户中使用事件网格触发器开发的函数,请选择“集成”,然后选择“事件网格触发器”并选择“创建事件网格订阅”。

在门户中将新事件订阅连接到触发器。

选择此链接时,门户将打开“创建事件订阅”页,其中已定义了当前触发器终结点。

已定义函数终结点的“创建事件订阅”

有关如何使用 Azure 门户创建订阅的详细信息,请参阅事件网格文档中的创建自定义事件 - Azure 门户

Azure CLI

若要使用 Azure CLI 创建订阅,请运行 az eventgrid event-subscription create 命令。

该命令需要可调用函数的终结点 URL。 以下示例显示特定于版本的 URL 模式:

版本 2.x(及更高版本)运行时

https://{functionappname}.chinacloudsites.cn/runtime/webhooks/eventgrid?functionName={functionname}&code={systemkey}

1.x 版运行时

https://{functionappname}.chinacloudsites.cn/admin/extensions/EventGridExtensionConfig?functionName={functionname}&code={systemkey}

系统密钥是必须包含在事件网格触发器终结点 URL 中的授权密钥。 以下部分介绍如何获取系统密钥。

下面是一个订阅 Blob 存储帐户的示例(包含系统密钥的占位符):

版本 2.x(及更高版本)运行时

az eventgrid resource event-subscription create -g myResourceGroup \
    --provider-namespace Microsoft.Storage --resource-type storageAccounts \
    --resource-name myblobstorage12345 --name myFuncSub \
    --included-event-types Microsoft.Storage.BlobCreated \
    --subject-begins-with /blobServices/default/containers/images/blobs/ \
    --endpoint https://mystoragetriggeredfunction.chinacloudsites.cn/runtime/webhooks/eventgrid?functionName=imageresizefunc&code=<key>

1.x 版运行时

az eventgrid resource event-subscription create -g myResourceGroup \
    --provider-namespace Microsoft.Storage --resource-type storageAccounts \
    --resource-name myblobstorage12345 --name myFuncSub \
    --included-event-types Microsoft.Storage.BlobCreated \
    --subject-begins-with /blobServices/default/containers/images/blobs/ \
    --endpoint https://mystoragetriggeredfunction.chinacloudsites.cn/admin/extensions/EventGridExtensionConfig?functionName=imageresizefunc&code=<key>

有关如何创建订阅的详细信息,请参阅 Blob 存储快速入门或其他事件网格快速入门。

获取系统密钥

可以使用以下 API (HTTP GET) 获取系统密钥:

版本 2.x(及更高版本)运行时

http://{functionappname}.chinacloudsites.cn/admin/host/systemkeys/eventgrid_extension?code={masterkey}

1.x 版运行时

http://{functionappname}.chinacloudsites.cn/admin/host/systemkeys/eventgridextensionconfig_extension?code={masterkey}

这是一个管理 API,因此它需要函数应用主密钥。 请不要混淆系统密钥(用于调用事件网格触发器函数)和主密钥(用于针对函数应用执行管理任务)。 订阅事件网格主题时,请务必使用系统密钥。

下面是提供系统密钥的响应示例:

{
  "name": "eventgridextensionconfig_extension",
  "value": "{the system key for the function}",
  "links": [
    {
      "rel": "self",
      "href": "{the URL for the function, without the system key}"
    }
  ]
}

可以从门户中的“函数应用设置”选项卡获取函数应用的主密钥。

重要

主密钥提供对函数应用的管理员访问权限。 不要与第三方共享此密钥或将其分发到本机客户端应用程序中。

有关详细信息,请参阅 HTTP 触发器参考文章中的授权密钥

或者,可以发送 HTTP PUT 以自行指定密钥值。

使用查看器 Web 应用进行本地测试

若要在本地测试事件网格触发器,必须获取从云中的来源位置传送到本地计算机的事件网格 HTTP 请求。 实现此目的的方法之一是在线捕获请求,然后手动将其重新发送到本地计算机:

  1. 创建查看器 Web 应用,用于捕获事件消息。
  2. 创建事件网格订阅,用于向查看器应用发送事件。
  3. 生成请求,并从查看器应用复制请求正文。
  4. 将请求手动发布到事件网格触发器函数的 localhost URL。

完成测试后,可以更新终结点,将同一订阅用于生产。 使用 az eventgrid event-subscription update Azure CLI 命令。

创建查看器 Web 应用

若要简化事件消息捕获,可部署用于显示事件消息的预建 Web 应用。 所部署的解决方案包括应用服务计划、应用服务 Web 应用和 GitHub 中的源代码。

选择“部署到 Azure”将解决方案部署到你的订阅。 在 Azure 门户中,为参数提供值。

Button to Deploy to Azure.

部署可能需要几分钟才能完成。 部署成功后,请查看 Web 应用以确保它正在运行。 在 Web 浏览器中导航到 https://<your-site-name>.chinacloudsites.cn

查看站点,但是尚未有事件发布到它。

查看新站点

创建事件网格订阅

创建要测试的类型的事件网格订阅,并将 Web 应用中的 URL 作为事件通知的终结点。 Web 应用的终结点必须包括后缀 /api/updates/。 因此,完整的 URL 是 https://<your-site-name>.chinacloudsites.cn/api/updates

有关如何使用 Azure 门户创建订阅的信息,请参阅事件网格文档中的创建自定义事件 - Azure 门户

生成请求

触发一个事件,以便向 Web 应用终结点生成 HTTP 流量。 例如,如果创建了 Blob 存储订阅,请上传或删除一个 Blob。 Web 应用中显示请求后,请复制请求正文。

首先会接收订阅验证请求,忽略任何验证请求,并复制事件请求。

从 Web 应用复制请求正文

手动发布请求

在本地运行事件网格函数。 需要手动设置 Content-Typeaeg-event-type 标头,而其他所有值都可以保留为默认值。

使用 Postmancurl 等工具创建 HTTP POST 请求:

  • 设置 Content-Type: application/json 标头。
  • 设置 aeg-event-type: Notification 标头。
  • 将 RequestBin 数据粘贴到请求正文。
  • 发布到事件网格触发器函数的 URL。
    • 对于 2.x 及更高版本,请使用以下模式:

      http://localhost:7071/runtime/webhooks/eventgrid?functionName={FUNCTION_NAME}
      
    • 对于 1.x,请使用:

      http://localhost:7071/admin/extensions/EventGridExtensionConfig?functionName={FUNCTION_NAME}
      

functionName 参数必须是在 FunctionName 特性中指定的名称。

以下屏幕截图显示了 Postman 中的标头和请求正文:

Postman 中的标头

Postman 中的请求正文

事件网格触发器函数将会执行,并显示类似于以下示例的日志:

事件网格触发器函数日志示例

后续步骤