Триггер службы "Сетка событий" для службы "Функции Azure"Event Grid trigger for Azure Functions

В этом руководстве показано, как обрабатывать события службы Сетка событий в службе "Функции Azure".This article explains how to handle Event Grid events in Azure Functions.

Служба "Сетка событий" — это служба Azure, которая отправляет HTTP-запросы для уведомления о событиях, которые происходят в издателях.Event Grid is an Azure service that sends HTTP requests to notify you about events that happen in publishers. Издатель — это служба или ресурс, в котором происходит событие.A publisher is the service or resource that originates the event. Например, учетная запись хранения больших двоичных объектов Azure является издателем, а отправка или удаление большого двоичного объекта — это событие.For example, an Azure blob storage account is a publisher, and a blob upload or deletion is an event. Некоторые службы Azure имеют встроенную поддержку публикации событий в службу "Сетка событий".Some Azure services have built-in support for publishing events to Event Grid.

Обработчики событий получают и обрабатывают события.Event handlers receive and process events. Служба "Функции Azure" является одной из нескольких служб Azure, в которых есть встроенная поддержка обработки событий Сетки событий.Azure Functions is one of several Azure services that have built-in support for handling Event Grid events. В этой статье вы узнаете, как использовать триггер службы "Сетка событий" для вызова функции при получении события из Сетки событий.In this article, you learn how to use an Event Grid trigger to invoke a function when an event is received from Event Grid.

При желании можно использовать триггер HTTP для обработки событий службы "Сетка событий". Дополнительные сведения см. в разделе Использование триггера HTTP в качестве триггера службы "Сетка событий" этой статьи.If you prefer, you can use an HTTP trigger to handle Event Grid Events; see Use an HTTP trigger as an Event Grid trigger later in this article. Сейчас, если событие доставляется в схему CloudEvents, триггер службы "Сетка событий" нельзя использовать в приложении "Функции Azure".Currently, you can't use an Event Grid trigger for an Azure Functions app when the event is delivered in the CloudEvents schema. В этом случае необходимо использовать триггер HTTP.Instead, use an HTTP trigger.

Это справочные сведения для разработчиков функций Azure.This is reference information for Azure Functions developers. Если вы новичок в функциях Azure, начните со следующих ресурсов:If you're new to Azure Functions, start with the following resources:

Packages — функции 2. x и более поздних версийPackages - Functions 2.x and higher

Триггер службы "Сетка событий" предоставляется в пакете NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid версии 2.х.The Event Grid trigger is provided in the Microsoft.Azure.WebJobs.Extensions.EventGrid NuGet package, version 2.x. Исходный код для пакета находится в репозитории GitHub azure-functions-eventgrid-extension.Source code for the package is in the azure-functions-eventgrid-extension GitHub repository.

В следующей таблице указано как добавить поддержку для этой привязки в каждой среде разработки.The following table tells how to add support for this binding in each development environment.

Среда разработкиDevelopment environment Добавление поддержкиTo add support
Локальная разработка – библиотека классов C#Local development - C# class library Установка пакетаInstall the package
Локальная разработка — скрипт C#, JavaScript, F#, Java и PythonLocal development - C# script, JavaScript, F#, Java and Python Регистрация расширенияRegister the extension
Разработка на порталеPortal development Установка при добавлении выходной привязкиInstall when adding output binding

Дополнительные сведения об обновлении существующих расширений привязки на портале, не переиздавая проект приложения-функции, см. раздел Обновление расширений.To learn how to update existing binding extensions in the portal without having to republish your function app project, see Update your extensions.

Пакеты – Функции 1.xPackages - Functions 1.x

Триггер службы "Сетка событий" предоставляется в пакете NuGet Microsoft.Azure.WebJobs.Extensions.EventGrid версии 1.х.The Event Grid trigger is provided in the Microsoft.Azure.WebJobs.Extensions.EventGrid NuGet package, version 1.x. Исходный код для пакета находится в репозитории GitHub azure-functions-eventgrid-extension.Source code for the package is in the azure-functions-eventgrid-extension GitHub repository.

В следующей таблице указано как добавить поддержку для этой привязки в каждой среде разработки.The following table tells how to add support for this binding in each development environment.

Среда разработкиDevelopment environment Для добавления поддержки вTo add support in
Функции 1.xFunctions 1.x
Локальная разработка – библиотека классов C#Local development - C# class library Установка пакетаInstall the package
Локальная разработка – Скрипт C#, JavaScript, F#Local development - C# script, JavaScript, F# АвтоматическийAutomatic
Разработка на порталеPortal development АвтоматическийAutomatic

ПримерExample

Просмотрите пример триггера Сетки событий для конкретного языка:See the language-specific example for an Event Grid trigger:

Пример триггера HTTP см. в разделе Использование триггера HTTP в качестве триггера службы "Сетка событий" в этой статье.For an HTTP trigger example, see How to use HTTP trigger later in this article.

C#(2. x и выше)C# (2.x and higher)

В следующем примере показана функция C#, которая выполняет привязку к EventGridEvent:The following example shows a C# function that binds to EventGridEvent:

using Microsoft.Azure.EventGrid.Models;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.EventGrid;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

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

Ознакомьтесь с дополнительными сведениями о пакетах, конфигурации и использовании.For more information, see Packages, Attributes, Configuration, and Usage.

C# (версия 1.x)C# (Version 1.x)

В следующем примере показана функция C# службы "Функции" 1.х, которая выполняет привязку к JObject.The following example shows a Functions 1.x C# function that binds to JObject:

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#C# script example

В следующем примере показаны привязка триггера в файле function.json и функция сценария C#, которая использует эту привязку.The following example shows a trigger binding in a function.json file and a C# script function that uses the binding.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

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

C#Скрипт (версия 2. x и более поздние)C# script (Version 2.x and higher)

Ниже приведен пример, который привязывается к EventGridEvent:Here's an example that binds to EventGridEvent:

#r "Microsoft.Azure.EventGrid"
using Microsoft.Azure.EventGrid.Models;
using Microsoft.Extensions.Logging;

public static void Run(EventGridEvent eventGridEvent, ILogger log)
{
    log.LogInformation(eventGridEvent.Data.ToString());
}

Ознакомьтесь с дополнительными сведениями о пакетах, конфигурации и использовании.For more information, see Packages, Attributes, Configuration, and Usage.

Скрипт C# (версия 1.x)C# script (Version 1.x)

Ниже приведен код сценария C# службы "Функции" 1.х, который выполняет привязку к JObject:Here's Functions 1.x C# script code that binds to JObject:

#r "Newtonsoft.Json"

using Newtonsoft.Json;
using Newtonsoft.Json.Linq;

public static void Run(JObject eventGridEvent, TraceWriter log)
{
    log.Info(eventGridEvent.ToString(Formatting.Indented));
}

Пример JavaScriptJavaScript example

В следующем примере показана привязка триггера в файле function.json и функция JavaScript, которая использует привязку.The following example shows a trigger binding in a function.json file and a JavaScript function that uses the binding.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

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

Ниже показан код JavaScript.Here's the JavaScript code:

module.exports = 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));
    context.done();
};

Пример на PythonPython example

В следующем примере показаны привязка триггера в файле function.json и функция Python, которая использует эту привязку.The following example shows a trigger binding in a function.json file and a Python function that uses the binding.

Данные привязки в файле function.json:Here's the binding data in the function.json file:

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

Ниже приведен код Python.Here's the Python code:

import logging
import azure.functions as func


def main(event: func.EventGridEvent):
    logging.info("Python Event Grid function processed a request.")
    logging.info("  Subject: %s", event.subject)
    logging.info("  Time: %s", event.event_time)
    logging.info("  Data: %s", event.get_json())

Триггер — пример для JavaTrigger - Java examples

В этом разделе содержатся следующие примеры:This section contains the following examples:

В следующих примерах показана привязка триггера в файле function.json и функции Java, использующая привязку и печатающая событие; сначала событие принимается как String, затем — как POJO.The following examples show trigger binding in a function.json file and Java functions that use the binding and print out an event, first receiving the event as String and second as a POJO.

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

Триггер сетки событий, строковый параметр (Java)Event Grid trigger, String parameter (Java)

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

Триггер сетки событий, параметр POJO (Java)Event Grid trigger, POJO parameter (Java)

В этом примере используется следующий POJO, представляющий свойства верхнего уровня события сетки событий.This example uses the following POJO, representing the top-level properties of an Event Grid event:

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 для использования функцией.Upon arrival, the event's JSON payload is de-serialized into the EventSchema POJO for use by the function. Это позволяет функции использовать свойства событий в объектно-ориентированном стиле.This allows the function to access the event's properties in an object-oriented way.

  @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 для параметров, значение которых должно быть получено от EventGrid.In the Java functions runtime library, use the EventGridTrigger annotation on parameters whose value would come from EventGrid. Параметры с этими заметками запускают функцию, когда происходит событие.Parameters with these annotations cause the function to run when an event arrives. Эта заметка может использоваться с собственными типами Java, объектами POJO или значениями, допускающими значения NULL, используя Optional<T>.This annotation can be used with native Java types, POJOs, or nullable values using Optional<T>.

АтрибутыAttributes

В библиотеках классов C# используйте атрибут EventGridTrigger.In C# class libraries, use the EventGridTrigger attribute.

Вот как выглядит атрибут EventGridTrigger в сигнатуре метода:Here's an EventGridTrigger attribute in a method signature:

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

Полный пример см. в разделе "Пример C#".For a complete example, see C# example.

НастройкаConfiguration

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json.The following table explains the binding configuration properties that you set in the function.json file. В атрибуте EventGridTrigger не задаются параметры или свойства конструкции.There are no constructor parameters or properties to set in the EventGridTrigger attribute.

свойство function.jsonfunction.json property ОписаниеDescription
typetype Обязательное. Необходимо задать значение eventGridTrigger.Required - must be set to eventGridTrigger.
directiondirection Обязательное. Необходимо задать значение in.Required - must be set to in.
namename Обязательное. Имя переменной, используемой в коде функции, для параметра, получающего данные события.Required - the variable name used in function code for the parameter that receives the event data.

ИспользованиеUsage

В функциях C# и F# в службе "Функции Azure" 1.х для триггера службы "Сетка событий" можно использовать следующие типы параметров:For C# and F# functions in Azure Functions 1.x, you can use the following parameter types for the Event Grid trigger:

  • JObject
  • string

Для C# функций F# и в функциях Azure 2. x и более поздних версий также можно использовать следующий тип параметра для триггера службы "Сетка событий":For C# and F# functions in Azure Functions 2.x and higher, you also have the option to use the following parameter type for the Event Grid trigger:

  • Microsoft.Azure.EventGrid.Models.EventGridEvent — определяет свойства для полей, которые являются общими для всех типов событий.Microsoft.Azure.EventGrid.Models.EventGridEvent- Defines properties for the fields common to all event types.

Примечание

В службе "Функции" 1.х при попытке сделать привязку к Microsoft.Azure.WebJobs.Extensions.EventGrid.EventGridEvent в компиляторе появится сообщение о том, что это не рекомендуется, и совет использовать Microsoft.Azure.EventGrid.Models.EventGridEvent.In Functions v1 if you try to bind to Microsoft.Azure.WebJobs.Extensions.EventGrid.EventGridEvent, the compiler will display a "deprecated" message and advise you to use Microsoft.Azure.EventGrid.Models.EventGridEvent instead. Чтобы использовать более новый тип, ссылайтесь на пакет NuGet Microsoft.Azure.EventGrid и полностью определите имя типа EventGridEvent, добавив префикс Microsoft.Azure.EventGrid.Models.To use the newer type, reference the Microsoft.Azure.EventGrid NuGet package and fully qualify the EventGridEvent type name by prefixing it with Microsoft.Azure.EventGrid.Models. Сведения о том, как ссылаться на пакеты NuGet в функции сценария C#, см. в разделе об использовании пакетов NuGet.For information about how to reference NuGet packages in a C# script function, see Using NuGet packages

Для функций JavaScript параметр, названный по свойству name в файле function.json, имеет ссылку на объект события.For JavaScript functions, the parameter named by the function.json name property has a reference to the event object.

Схема событийEvent schema

Данные для события службы "Сетка событий" получаются в качестве объекта JSON в теле HTTP-запроса.Data for an Event Grid event is received as a JSON object in the body of an HTTP request. JSON должен быть аналогичным приведенному ниже:The JSON looks similar to the following example:

[{
  "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"
}]

Показанный пример является массивом из одного элемента.The example shown is an array of one element. Сетка событий всегда отправляет массив, который может содержать более одного события.Event Grid always sends an array and may send more than one event in the array. Среда выполнения вызывает функцию один раз для каждого элемента массива.The runtime invokes your function once for each array element.

Свойства верхнего уровня в данных JSON события одинаковы для всех типов событий, тогда как содержимое свойства data определено для каждого типа события.The top-level properties in the event JSON data are the same among all event types, while the contents of the data property are specific to each event type. Пример показан для события хранилища BLOB-объектов.The example shown is for a blob storage event.

Описания распространенных и связанных с событием свойств см. в разделе Свойства события в документации по службе "Сетка событий".For explanations of the common and event-specific properties, see Event properties in the Event Grid documentation.

Тип EventGridEvent определяет только свойства верхнего уровня. Свойство Data имеет значение JObject.The EventGridEvent type defines only the top-level properties; the Data property is a JObject.

Создание подпискиCreate a subscription

Чтобы начать получать HTTP-запросы Сетки событий, создайте подписку службы "Сетка событий", которая указывает URL-адрес конечной точки, вызывающей функцию.To start receiving Event Grid HTTP requests, create an Event Grid subscription that specifies the endpoint URL that invokes the function.

портала AzureAzure portal

Для функций, разрабатываемых на портале Azure с использованием триггера службы "Сетка событий", выберите Добавить подписку сетки событий.For functions that you develop in the Azure portal with the Event Grid trigger, select Add Event Grid subscription.

Создание подписки на портале

Когда вы щелкните эту ссылку, откроется страница создания подписки на событие с автоматически заполненным URL-адресом конечной точки.When you select this link, the portal opens the Create Event Subscription page with the endpoint URL prefilled.

Автоматически заполненный URL-адрес конечной точки

Дополнительные сведения о создании подписок с помощью портала Azure см. в разделе Создание и перенаправление пользовательских событий с помощью портала Azure и службы "Сетка событий" документации по службе "Сетка событий".For more information about how to create subscriptions by using the Azure portal, see Create custom event - Azure portal in the Event Grid documentation.

Azure CLIAzure CLI

Чтобы создать подписку с помощью Azure CLI, используйте команду az eventgrid event-subscription create.To create a subscription by using the Azure CLI, use the az eventgrid event-subscription create command.

Для команды нужен URL-адрес конечной точки, который вызывает функцию.The command requires the endpoint URL that invokes the function. В следующем примере показан шаблон URL-адреса в зависимости от версии:The following example shows the version-specific URL pattern:

Среда выполнения версии 2. x (и выше)Version 2.x (and higher) runtime

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

Среда выполнения версии 1.xVersion 1.x runtime

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

Системный ключ — это ключ авторизации, который необходимо включить в URL-адрес конечной точки для триггера службы "Сетка событий".The system key is an authorization key that has to be included in the endpoint URL for an Event Grid trigger. В следующем разделе показано, как получить системный ключ.The following section explains how to get the system key.

Ниже приведен пример, который подписывается на учетную запись хранения больших двоичных объектов (с заполнителем для системного ключа):Here's an example that subscribes to a blob storage account (with a placeholder for the system key):

Среда выполнения версии 2. x (и выше)Version 2.x (and higher) runtime

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.azurewebsites.net/runtime/webhooks/eventgrid?functionName=imageresizefunc&code=<key>

Среда выполнения версии 1.xVersion 1.x runtime

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.azurewebsites.net/admin/extensions/EventGridExtensionConfig?functionName=imageresizefunc&code=<key>

Дополнительные сведения о создании подписки см. в разделе Примеры использования хранилища больших двоичных объектов или других коротких руководствах по использованию службы "Сетка событий".For more information about how to create a subscription, see the blob storage quickstart or the other Event Grid quickstarts.

Получение системного ключаGet the system key

Системный ключ можно получить с помощью следующего API-интерфейса (HTTP GET):You can get the system key by using the following API (HTTP GET):

Среда выполнения версии 2. x (и выше)Version 2.x (and higher) runtime

http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgrid_extension?code={masterkey}

Среда выполнения версии 1.xVersion 1.x runtime

http://{functionappname}.azurewebsites.net/admin/host/systemkeys/eventgridextensionconfig_extension?code={masterkey}

Это API администратора, поэтому для него нужен главный ключ приложения-функции.This is an admin API, so it requires your function app master key. Не путайте системный ключ (для вызова функции триггера службы "Сетка событий") с главным ключом (для выполнения административных задач в приложении-функции).Don't confuse the system key (for invoking an Event Grid trigger function) with the master key (for performing administrative tasks on the function app). Во время оформления подписки на раздел службы "Сетка событий" необходимо использовать системный ключ.When you subscribe to an Event Grid topic, be sure to use the system key.

Ниже приведен пример ответа, который предоставляет системный ключ:Here's an example of the response that provides the system key:

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

Можно получить главный ключ для приложения-функции на вкладке Параметры приложения-функции на портале.You can get the master key for your function app from the Function app settings tab in the portal.

Важно!

Главный ключ предоставляет административный доступ к приложению-функции.The master key provides administrator access to your function app. Не передавайте этот ключ третьим лицам и не распространяйте его в собственных клиентских приложениях.Don't share this key with third parties or distribute it in native client applications.

Дополнительные сведения см. в разделе Ключи авторизации в справочнике по триггерам HTTP.For more information, see Authorization keys in the HTTP trigger reference article.

Кроме того, вы можете отправить HTTP-запрос PUT, чтобы самостоятельно указать значение ключа.Alternatively, you can send an HTTP PUT to specify the key value yourself.

Локальное тестирование с помощью веб-приложения средства просмотраLocal testing with viewer web app

Чтобы протестировать триггер службы "Сетка событий" локально, необходимо отправить HTTP-запросы службы "Сетка событий", переданные из своего источника в облаке, на локальный компьютер.To test an Event Grid trigger locally, you have to get Event Grid HTTP requests delivered from their origin in the cloud to your local machine. Для этого можно записать запросы в сети и вручную отправить их на локальный компьютер:One way to do that is by capturing requests online and manually resending them on your local machine:

  1. Создайте веб-приложение средства просмотра, которое собирает сообщения о событиях.Create a viewer web app that captures event messages.
  2. Создайте подписку службы "Сетка событий", которая отправляет события в приложение средства просмотра.Create an Event Grid subscription that sends events to the viewer app.
  3. Создайте запрос и скопируйте текст запроса из приложения средства просмотра.Generate a request and copy the request body from the viewer app.
  4. Вручную вставьте запрос в URL-адрес localhost функции триггера службы "Сетка событий".Manually post the request to the localhost URL of your Event Grid trigger function.

Закончив тестирование, можно использовать ту же подписку для рабочей среды, обновив конечную точку.When you're done testing, you can use the same subscription for production by updating the endpoint. Используйте команду Azure CLI az eventgrid event-subscription update.Use the az eventgrid event-subscription update Azure CLI command.

Создание веб-приложения средства просмотраCreate a viewer web app

Чтобы упростить запись сообщений о событиях, разверните готовое веб-приложение, которое отображает сообщения о событиях.To simplify capturing event messages, you can deploy a pre-built web app that displays the event messages. Развернутое решение содержит план службы приложений, веб-приложение службы приложений и исходный код из GitHub.The deployed solution includes an App Service plan, an App Service web app, and source code from GitHub.

Выберите Развернуть в Azure, чтобы развернуть решение в своей подписке.Select Deploy to Azure to deploy the solution to your subscription. На портале Azure укажите значения остальных параметров.In the Azure portal, provide values for the parameters.

Завершение развертывания может занять несколько минут.The deployment may take a few minutes to complete. Когда развертывание успешно завершится, откройте веб-приложение и убедитесь, что оно работает.After the deployment has succeeded, view your web app to make sure it's running. Откройте браузер и перейдите по адресу https://<your-site-name>.azurewebsites.net.In a web browser, navigate to: https://<your-site-name>.azurewebsites.net

Вы увидите сайт без опубликованных событий.You see the site but no events have been posted to it yet.

Представление нового сайта

Создание подписки Сетки событийCreate an Event Grid subscription

Создайте подписку "Сетка событий" того типа, который требуется протестировать, и предоставьте URL-адрес из веб-приложения как конечную точку для уведомления о событиях.Create an Event Grid subscription of the type you want to test, and give it the URL from your web app as the endpoint for event notification. Конечная точка веб-приложения должна содержать суффикс /api/updates/.The endpoint for your web app must include the suffix /api/updates/. Таким образом, полный URL-адрес будет выглядеть следующим образом: https://<your-site-name>.azurewebsites.net/api/updatesSo, the full URL is https://<your-site-name>.azurewebsites.net/api/updates

Дополнительные сведения о создании подписок с помощью портала Azure см. в разделе Создание пользовательского события с помощью портала Azure в документации по службе "Сетка событий".For information about how to create subscriptions by using the Azure portal, see Create custom event - Azure portal in the Event Grid documentation.

Создание запросаGenerate a request

Активируйте событие, которое будет создавать HTTP-трафик в конечную точку веб-приложения.Trigger an event that will generate HTTP traffic to your web app endpoint. Например, если вы создали подписку хранилища BLOB-объектов, отправьте или удалите большой двоичный объект.For example, if you created a blob storage subscription, upload or delete a blob. Скопируйте текст запроса, когда запрос отобразится в веб-приложении.When a request shows up in your web app, copy the request body.

Сначала будет получен запрос на подтверждение подписки. Игнорируйте такие запросы и скопируйте запрос события.The subscription validation request will be received first; ignore any validation requests, and copy the event request.

Копирование текста запроса из веб-приложения

Публикация запроса вручнуюManually post the request

Запустите функцию службы "Сетка событий" локально.Run your Event Grid function locally.

Используйте такие средства, как Postman или cURL, чтобы создать HTTP-запрос POST:Use a tool such as Postman or curl to create an HTTP POST request:

  • Задайте заголовок Content-Type: application/json.Set a Content-Type: application/json header.
  • Задайте заголовок aeg-event-type: Notification.Set an aeg-event-type: Notification header.
  • Вставьте данные RequestBin в текст запроса.Paste the RequestBin data into the request body.
  • Опубликуйте по URL-адресу функции триггера сетки событий.Post to the URL of your Event Grid trigger function.
    • Для 2. x и более поздних версий используйте следующий шаблон:For 2.x and higher use the following pattern:

      http://localhost:7071/runtime/webhooks/eventgrid?functionName={FUNCTION_NAME}
      
    • Для использования с 1. x:For 1.x use:

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

Для параметра functionName нужно указать имя, заданное в атрибуте FunctionName.The functionName parameter must be the name specified in the FunctionName attribute.

На следующих снимках экрана показаны заголовки и текст запроса в Postman:The following screenshots show the headers and request body in Postman:

Заголовки в Postman

Текст запроса в Postman

Функция триггера службы "Сетка событий" выполняет и показывает журналы, похожие на приведенные ниже:The Event Grid trigger function executes and shows logs similar to the following example:

Пример журналов функций триггера службы "Сетка событий"

Локальное тестирование с помощью ngrokLocal testing with ngrok

Другим способом локально проверить триггер Сетки событий является автоматизация HTTP-подключения между Интернетом и компьютером разработчика.Another way to test an Event Grid trigger locally is to automate the HTTP connection between the Internet and your development computer. Это можно сделать с помощью такого средства, как ngrok:You can do that with a tool like ngrok:

  1. Создайте конечную точку ngrok.Create an ngrok endpoint.
  2. Запустите функцию триггера службы "Сетка событий".Run the Event Grid trigger function.
  3. Создайте подписку службы "Сетка событий", которая отправляет события в конечную точку ngrok.Create an Event Grid subscription that sends events to the ngrok endpoint.
  4. Активируйте событие.Trigger an event.

Закончив тестирование, можно использовать ту же подписку для рабочей среды, обновив конечную точку.When you're done testing, you can use the same subscription for production by updating the endpoint. Используйте команду Azure CLI az eventgrid event-subscription update.Use the az eventgrid event-subscription update Azure CLI command.

Создание конечной точки ngrokCreate an ngrok endpoint

Скачайте ngrok.exe из ngrok и выполните следующую команду:Download ngrok.exe from ngrok, and run with the following command:

ngrok http -host-header=localhost 7071

Параметр -host-header необходим, так как среда выполнения функций ожидает запросов от localhost при выполнении на локальном узле.The -host-header parameter is needed because the functions runtime expects requests from localhost when it runs on localhost. 7071 — номер порта по умолчанию, если среда выполнения запущена локально.7071 is the default port number when the runtime runs locally.

Команда создает выходные данные следующего вида:The command creates output like the following:

Session Status                online
Version                       2.2.8
Region                        United States (us)
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://263db807.ngrok.io -> localhost:7071
Forwarding                    https://263db807.ngrok.io -> localhost:7071

Connections                   ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00

Для подписки службы "Сетка событий" используется URL-адрес https://{subdomain}.ngrok.io.You'll use the https://{subdomain}.ngrok.io URL for your Event Grid subscription.

Запуск функций триггера службы "Сетка событий"Run the Event Grid trigger function

Служба "Сетка событий" не обрабатывает URL-адрес ngrok особым образом, поэтому при создании подписки функция должна выполняться локально.The ngrok URL doesn't get special handling by Event Grid, so your function must be running locally when the subscription is created. В противном случае ответ проверки не отправляется и происходит сбой при создании подписки.If it isn't, the validation response doesn't get sent and the subscription creation fails.

Создание подпискиCreate a subscription

Создайте подписку службы "Сетка событий" типа, который необходимо протестировать, и присвойте ее конечной точке ngrok.Create an Event Grid subscription of the type you want to test, and give it your ngrok endpoint.

Используйте этот шаблон конечной точки для функций 2. x и более поздних версий:Use this endpoint pattern for Functions 2.x and higher:

https://{SUBDOMAIN}.ngrok.io/runtime/webhooks/eventgrid?functionName={FUNCTION_NAME}

Для Функций версии 1.x используйте этот шаблон конечной точки:Use this endpoint pattern for Functions 1.x:

https://{SUBDOMAIN}.ngrok.io/admin/extensions/EventGridExtensionConfig?functionName={FUNCTION_NAME}

Для параметра {FUNCTION_NAME} нужно указать имя, заданное в атрибуте FunctionName.The {FUNCTION_NAME} parameter must be the name specified in the FunctionName attribute.

Ниже приведен пример с использованием Azure CLI:Here's an example using the Azure CLI:

az eventgrid event-subscription create --resource-id /subscriptions/aeb4b7cb-b7cb-b7cb-b7cb-b7cbb6607f30/resourceGroups/eg0122/providers/Microsoft.Storage/storageAccounts/egblobstor0122 --name egblobsub0126 --endpoint https://263db807.ngrok.io/runtime/webhooks/eventgrid?functionName=EventGridTrigger

Дополнительные сведения о создании подписки см. в разделе Создание подписки ранее в этой статье.For information about how to create a subscription, see Create a subscription earlier in this article.

Активация событияTrigger an event

Активируйте событие, которое будет создавать HTTP-трафик в конечную точку ngrok.Trigger an event that will generate HTTP traffic to your ngrok endpoint. Например, если вы создали подписку хранилища BLOB-объектов, отправьте или удалите большой двоичный объект.For example, if you created a blob storage subscription, upload or delete a blob.

Функция триггера службы "Сетка событий" выполняет и показывает журналы, похожие на приведенные ниже:The Event Grid trigger function executes and shows logs similar to the following example:

Пример журналов функций триггера службы "Сетка событий"

Использование триггера HTTP в качестве триггера службы "Сетка событий"Use an HTTP trigger as an Event Grid trigger

События службы "Сетка событий" получаются в качестве HTTP-запросов, поэтому их можно обрабатывать с использованием триггера HTTP, а не триггера службы "Сетка событий".Event Grid events are received as HTTP requests, so you can handle events by using an HTTP trigger instead of an Event Grid trigger. Одна из возможных причин — получение большего контроля над URL-адресом конечной точки, вызывающим функцию.One possible reason for doing that is to get more control over the endpoint URL that invokes the function. Еще одна причина — необходимость получения событий в схеме CloudEvents.Another reason is when you need to receive events in the CloudEvents schema. В настоящее время триггер службы "Сетка событий" не поддерживает схему CloudEvents.Currently, the Event Grid trigger doesn't support the CloudEvents schema. В примерах в этом разделе показаны решения для схемы "Сетка событий" и схемы CloudEvents.The examples in this section show solutions for both Event Grid schema and CloudEvents schema.

При использовании триггера HTTP необходимо написать код действий, которые триггер службы "Сетка событий" выполняет автоматически:If you use an HTTP trigger, you have to write code for what the Event Grid trigger does automatically:

  • Отправляет запрос проверки в запрос подтверждения подписки.Sends a validation response to a subscription validation request.
  • Вызывает функцию один раз для каждого элемента массива событий, содержащихся в тексте запроса.Invokes the function once per element of the event array contained in the request body.

Дополнительные сведения об URL-адресе, используемом для вызова функции, выполняемой локально или в Azure, см. в справочной документации по привязке триггера HTTP.For information about the URL to use for invoking the function locally or when it runs in Azure, see the HTTP trigger binding reference documentation

Схема службы "Сетка событий"Event Grid schema

Следующий пример кода C# для триггера HTTP имитирует поведение триггера службы "Сетка событий".The following sample C# code for an HTTP trigger simulates Event Grid trigger behavior. Этот пример можно использовать для событий, доставленных в схеме "Сетка событий".Use this example for events delivered in the Event Grid schema.

[FunctionName("HttpTrigger")]
public static async Task<HttpResponseMessage> Run(
    [HttpTrigger(AuthorizationLevel.Anonymous, "post")]HttpRequestMessage req,
    ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var messages = await req.Content.ReadAsAsync<JArray>();

    // If the request is for subscription validation, send back the validation code.
    if (messages.Count > 0 && string.Equals((string)messages[0]["eventType"],
        "Microsoft.EventGrid.SubscriptionValidationEvent",
        System.StringComparison.OrdinalIgnoreCase))
    {
        log.LogInformation("Validate request received");
        return req.CreateResponse<object>(new
        {
            validationResponse = messages[0]["data"]["validationCode"]
        });
    }

    // The request is not for subscription validation, so it's for one or more events.
    foreach (JObject message in messages)
    {
        // Handle one event.
        EventGridEvent eventGridEvent = message.ToObject<EventGridEvent>();
        log.LogInformation($"Subject: {eventGridEvent.Subject}");
        log.LogInformation($"Time: {eventGridEvent.EventTime}");
        log.LogInformation($"Event data: {eventGridEvent.Data.ToString()}");
    }

    return req.CreateResponse(HttpStatusCode.OK);
}

Следующий пример кода JavaScript для триггера HTTP имитирует поведение триггера службы "Сетка событий".The following sample JavaScript code for an HTTP trigger simulates Event Grid trigger behavior. Этот пример можно использовать для событий, доставленных в схеме "Сетка событий".Use this example for events delivered in the Event Grid schema.

module.exports = function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    var messages = req.body;
    // If the request is for subscription validation, send back the validation code.
    if (messages.length > 0 && messages[0].eventType == "Microsoft.EventGrid.SubscriptionValidationEvent") {
        context.log('Validate request received');
        var code = messages[0].data.validationCode;
        context.res = { status: 200, body: { "ValidationResponse": code } };
    }
    else {
        // The request is not for subscription validation, so it's for one or more events.
        // Event Grid schema delivers events in an array.
        for (var i = 0; i < messages.length; i++) {
            // Handle one event.
            var message = messages[i];
            context.log('Subject: ' + message.subject);
            context.log('Time: ' + message.eventTime);
            context.log('Data: ' + JSON.stringify(message.data));
        }
    }
    context.done();
};

Код обработки событий переходит в цикл через массив messages.Your event-handling code goes inside the loop through the messages array.

Схема CloudEventsCloudEvents schema

Следующий пример кода C# для триггера HTTP имитирует поведение триггера службы "Сетка событий".The following sample C# code for an HTTP trigger simulates Event Grid trigger behavior. Этот пример можно использовать для событий, доставленных в схеме CloudEvents.Use this example for events delivered in the CloudEvents schema.

[FunctionName("HttpTrigger")]
public static async Task<HttpResponseMessage> Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    var requestmessage = await req.Content.ReadAsStringAsync();
    var message = JToken.Parse(requestmessage);

    if (message.Type == JTokenType.Array)
    {
        // If the request is for subscription validation, send back the validation code.
        if (string.Equals((string)message[0]["eventType"],
        "Microsoft.EventGrid.SubscriptionValidationEvent",
        System.StringComparison.OrdinalIgnoreCase))
        {
            log.LogInformation("Validate request received");
            return req.CreateResponse<object>(new
            {
                validationResponse = message[0]["data"]["validationCode"]
            });
        }
    }
    else
    {
        // The request is not for subscription validation, so it's for an event.
        // CloudEvents schema delivers one event at a time.
        log.LogInformation($"Source: {message["source"]}");
        log.LogInformation($"Time: {message["eventTime"]}");
        log.LogInformation($"Event data: {message["data"].ToString()}");
    }

    return req.CreateResponse(HttpStatusCode.OK);
}

Следующий пример кода JavaScript для триггера HTTP имитирует поведение триггера службы "Сетка событий".The following sample JavaScript code for an HTTP trigger simulates Event Grid trigger behavior. Этот пример можно использовать для событий, доставленных в схеме CloudEvents.Use this example for events delivered in the CloudEvents schema.

module.exports = function (context, req) {
    context.log('JavaScript HTTP trigger function processed a request.');

    var message = req.body;
    // If the request is for subscription validation, send back the validation code.
    if (message.length > 0 && message[0].eventType == "Microsoft.EventGrid.SubscriptionValidationEvent") {
        context.log('Validate request received');
        var code = message[0].data.validationCode;
        context.res = { status: 200, body: { "ValidationResponse": code } };
    }
    else {
        // The request is not for subscription validation, so it's for an event.
        // CloudEvents schema delivers one event at a time.
        var event = JSON.parse(message);
        context.log('Source: ' + event.source);
        context.log('Time: ' + event.eventTime);
        context.log('Data: ' + JSON.stringify(event.data));
    }
    context.done();
};

Дальнейшие действияNext steps