Azure Functions 的 Azure 事件方格觸發程序

發行項
06/13/2024

使用函式觸發程式來回應事件方格來源所傳送的事件。您必須擁有來源的事件訂用帳戶，才能接收事件。若要瞭解如何建立事件訂閱，請參閱建立訂用帳戶。如需系結設定和組態的相關信息，請參閱概觀。

注意

內部負載平衡器 App Service 環境（ASE）中原生不支援事件方格觸發程式。觸發程式會使用 HTTP 要求，在沒有閘道進入虛擬網路的情況下無法連線到函式應用程式。

重要

本文使用索引標籤來支援多個版本的 Node.js 程式設計模型。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活且更直覺的體驗。如需 v4 模型運作方式的更多詳細資料，請參閱 Azure Functions Node.js 開發人員指南。若要深入了解 v3 與 v4 之間的差異，請參閱移轉指南。

Azure Functions 支援兩種適用於 Python 的程式設計模型。您定義系結的方式取決於您所選擇的程式設計模型。

Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。如需詳細資訊，請參閱 Python 開發人員指南。

本文支援這兩種程序設計模型。

範例

如需 HTTP 觸發程式範例，請參閱接收 HTTP 端點的事件。

與事件方格觸發程式搭配使用的輸入參數類型取決於下列三個因素：

Functions 執行階段版本
系結延伸模組版本
C# 函式的形式。

您可以使用下列其中一種 C# 模式來建立 C# 函式：

隔離的背景工作模型：在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。需要隔離的背景工作進程，才能支援在 LTS 和非 LTS 版本 .NET 和 .NET Framework 上執行的 C# 函式。隔離背景工作進程函式的延伸模組會使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空間。
同進程模型：在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。在此模型的變化中，函式可以使用 C# 腳本來執行，主要支援 C# 入口網站編輯。進程內函式的延伸模組會使用 Microsoft.Azure.WebJobs.Extensions.* 命名空間。

重要

內含式模型支援將於 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));
        }
    }
}

本區段包含下列範例：

事件方格觸發程式，String 參數
事件方格觸發程式，POJO 參數

下列範例顯示 Java 中的觸發程式系結，該系結會使用系結併產生事件，先以 POJO 的形式接收事件String，第二個接收事件。

事件方格觸發程式，String 參數

  @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 承載會還原串行化為 POJO， EventSchema 以供函式使用。此程式可讓函式以面向物件的方式存取事件的屬性。

  @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 或使用可為 Null 的值使用 Optional<T>。

模型 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 註釋可讓您藉由提供組態值，以宣告方式設定事件方格系結。如需詳細資訊，請參閱範例和組態小節。

options傳遞給 app.eventGrid() 方法的物件目前不支援模型 v4 的任何屬性。

下表說明您在 function.json 檔案中設定的繫結設定屬性。

屬性	描述
type	必要項目 - 必須設定為 `eventGridTrigger`。
direction	必要項目 - 必須設定為 `in`。
name	必要項目 - 函式程式碼中用於接收事件資料之參數的變數名稱。

組態

下表說明您在 function.json 檔案中設定的繫結設定屬性。沒有要在 EventGridTrigger 屬性中設定的建構函式參數或屬性。

function.json 屬性	描述
type	必要項目 - 必須設定為 `eventGridTrigger`。
direction	必要項目 - 必須設定為 `in`。
name	必要項目 - 函式程式碼中用於接收事件資料之參數的變數名稱。

如需完整範例，請參閱範例一節。

使用方式

事件方格觸發程式會使用 Webhook HTTP 要求，其可以使用與 HTTP 觸發程式相同的host.json設定來設定。

事件方格觸發程式所支援的參數類型取決於 Functions 運行時間版本、擴充套件版本，以及所使用的 C# 形式。

當您想要讓函式處理單一事件時，Event Grid 觸發程式可以繫結至下列類型：

類型	描述
JSON 可序列化型別	函式會嘗試將事件的 JSON 數據還原串行化為純舊 CLR 物件（POCO）類型。
`string`	事件做為字串。
BinaryData¹	事件訊息的位元組。
CloudEvent¹	事件物件。當事件方格設定為使用 CloudEvents 架構傳遞時，請使用。
EventGridEvent¹	事件物件。當事件方格設定為使用事件方格架構傳遞時，請使用。

當您想要讓函式處理一批事件時，Event Grid 觸發程式可以繫結至下列類型：

類型	描述
`CloudEvent[]`¹、 `EventGridEvent[]`¹、 `string[]`, `BinaryData[]`¹	來自批次的事件陣列。每個專案都代表一個事件。

¹ 若要使用這些類型，您必須參考 Microsoft.Azure.Functions.Worker.Extensions.EventGrid 3.3.0 或更新版本，以及 SDK 類型系結的常見相依性。

事件方格事件實例可透過與屬性相關聯的 EventGridTrigger 參數取得，類型為 EventSchema。

事件方格實例可透過在 function.json 檔案的 name 屬性中設定的參數取得。

事件方格實例可透過在 function.json 檔案的屬性中設定的參數取得，類型為 func.EventGridEvent。name

結構描述

事件方格事件的數據會以 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.windows.net/{containername}/blobname.jpg",
    "sequencer": "000000000000272D000000000003D60F",
    "storageDiagnostics": {
      "batchId": "{guid}"
    }
  },
  "dataVersion": "",
  "metadataVersion": "1"
}]

顯示的範例是一個元素的陣列。事件方格一律會傳送陣列，而且可能會傳送陣列中的多個事件。運行時間會針對每個數位專案叫用函式一次。

事件 JSON 數據中的最上層屬性在所有事件類型中都相同，而屬性的內容 data 則專屬於每個事件類型。顯示的範例是用於 Blob 記憶體事件。

如需常見和事件特定屬性的說明，請參閱事件方格檔中的事件屬性。

下一步

如果您有問題，請在這裡提交問題給小組
分派事件方格事件

共用方式為

Azure Functions 的 Azure 事件方格觸發程序

範例

事件方格觸發程式，String 參數

事件方格觸發程式，POJO 參數

屬性

註釋

組態

組態

使用方式

結構描述

下一步

意見反應

其他資源