Поделиться через

Триггер и привязки Центров событий Azure для службы "Функции Azure"

  • Статья

Здесь объясняется, как работать с привязками Центров событий Azure для службы "Функции Azure". Функции Azure поддерживают привязки триггера и выходные привязки для Центров событий.

Действие Тип
Реагирование на события, отправляемые в поток событий Центра событий. Триггер
Запись событий в поток событий Выходная привязка

Установка расширения

Устанавливаемый пакет расширения NuGet зависит от режима C#, который используется в приложении-функции:

Функции выполняются в изолированном рабочем процессе C#. Дополнительные сведения см. в руководстве по запуску Функции Azure C# в изолированном рабочем процессе.

Функциональные возможности расширения отличаются в зависимости от версии расширения:

В этой версии появляется возможность подключения с использованием удостоверения, а не секрета. Руководство по настройке приложений-функций с помощью управляемых удостоверений см. в руководстве по созданию приложения-функции с подключениями на основе удостоверений.

Эта версия поддерживает настройку триггеров и привязок с помощью интеграции .NET Aspire.

Добавьте расширение в проект, установив пакет NuGet версии 5.x.

Установка пакета

Расширение Центров событий входит в пакет расширений, который указан в файле проекта host.json. Возможно, потребуется изменить этот пакет, чтобы изменить версию привязки, а также в том случае если пакеты еще не установлены. Дополнительные сведения см. в разделе Пакет расширений.

В этой версии появляется возможность подключения с использованием удостоверения, а не секрета. Руководство по настройке приложений-функций с помощью управляемых удостоверений см. в руководстве по созданию приложения-функции с подключениями на основе удостоверений.

Эту версию расширения можно добавить из пакета расширений версии 3, добавив или заменив следующий код в файле host.json:

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

Для получения дополнительных сведений см. раздел Обновление расширений.

Типы привязки

Типы привязки, поддерживаемые для .NET, зависят от версии расширения и режима выполнения C#, что может быть одним из следующих вариантов:

Изолированная библиотека классов рабочих процессов, скомпилированная функция C# выполняется в процессе, изолированном от среды выполнения.

Выберите версию, чтобы просмотреть сведения о типе привязки для режима и версии.

Изолированный рабочий процесс поддерживает типы параметров в соответствии с таблицами ниже. Поддержка привязки к типам из Azure.Messaging.EventHubs доступна в предварительной версии.

Триггер Центров событий

Если требуется, чтобы функция обрабатывала одно событие, триггер Центров событий может привязаться к следующим типам:

Тип Описание
string Событие в виде строки. Используется, когда событие является простым текстом.
byte[] Байты события.
Сериализуемые в JSON типы Если событие содержит данные JSON, функции пытаются десериализировать данные JSON в обычный тип объекта CLR (POCO).
Azure.Messaging.EventHubs.EventData1 Объект события.
Если вы переносите все старые версии пакетов SDK центров событий, обратите внимание, что эта версия удаляет поддержку устаревшего Body типа в пользу EventBody.

Если требуется, чтобы функция обрабатывала пакет событий, триггер Центров событий может привязаться к следующим типам:

Тип Описание
string[] Массив событий из пакета в виде строк. Каждая запись представляет одно событие.
EventData[] 1 Массив событий из пакета в качестве экземпляров Azure.Messaging.EventHubs.EventData. Каждая запись представляет одно событие.
T[] где T является сериализуемый типJSON 1 Массив событий из пакета в качестве экземпляров пользовательского типа POCO. Каждая запись представляет одно событие.

1 Для использования этих типов необходимо ссылаться на Microsoft.Azure.Functions.Worker.Extensions.EventHubs 5.5.0 или более поздней версии , а также общие зависимости для привязок типов SDK.

Выходная привязка Центров событий

Если требуется, чтобы функция записывала одно событие, выходная привязка Центров событий может привязаться к следующим типам:

Тип Описание
string Событие в виде строки. Используется, когда событие является простым текстом.
byte[] Байты события.
Сериализуемые в JSON типы Объект, представляющий событие. Функции пытаются сериализовать обычный тип объекта CLR (POCO) в данные JSON.

Если требуется, чтобы функция записывала несколько событий, выходная привязка Центров событий может привязаться к следующим типам:

Тип Описание
T[] где T является одним из отдельных типов событий Массив, содержащий несколько событий. Каждая запись представляет одно событие.

Для других сценариев вывода создайте и используйте EventHubProducerClient с другими типами из Azure.Messaging.EventHubs напрямую. Пример использования внедрения зависимостей для создания типа клиента из пакета SDK Azure см. в статье "Регистрация клиентов Azure".

Параметры файла host.json

В файле host.json содержатся параметры, управляющие работой триггера Центров событий. Конфигурация будет разной в зависимости от версии расширения.

{
    "version": "2.0",
    "extensions": {
        "eventHubs": {
            "maxEventBatchSize" : 100,
            "minEventBatchSize" : 25,
            "maxWaitTime" : "00:05:00",            
            "batchCheckpointFrequency" : 1,
            "prefetchCount" : 300,
            "transportType" : "amqpWebSockets",
            "webProxy" : "https://proxyserver:8080",
            "customEndpointAddress" : "amqps://company.gateway.local",
            "targetUnprocessedEventThreshold" : 75,
            "initialOffsetOptions" : {
                "type" : "fromStart",
                "enqueuedTimeUtc" : ""
            },
            "clientRetryOptions":{
                "mode" : "exponential",
                "tryTimeout" : "00:01:00",
                "delay" : "00:00:00.80",
                "maximumDelay" : "00:01:00",
                "maximumRetries" : 3
            }
        }
    }
}
Свойство По умолчанию Description
maxEventBatchSize2 100 Максимальное количество событий, включенных в пакет для одного вызова. Должно быть не менее 1.
minEventBatchSize1 1 Минимальное количество событий, необходимых в пакете. Минимальное значение применяется только в том случае, если функция получает несколько событий и должна быть меньше maxEventBatchSize.
Минимальный размер не гарантируется строго. Частичный пакет отправляется, когда полный пакет не может быть подготовлен до maxWaitTime истечения срока действия. Частичные пакеты также, вероятно, для первого вызова функции после масштабирования.
maxWaitTime1 00:01:00 Максимальный интервал, который триггер должен ждать заполнения пакета перед вызовом функции. Время ожидания считается только в том случае, если minEventBatchSize больше 1 и в противном случае игнорируется. Если события minEventBatchSize были доступны до истечения времени ожидания, функция вызывается с частичным пакетом. Максимально допустимое время ожидания составляет 10 минут.

ПРИМЕЧАНИЕ. Этот интервал не является строгой гарантией точного времени вызова функции. Существует небольшое поле ошибки из-за точности таймера. При масштабировании первое вызов с частичным пакетом может произойти быстрее или может занять до двух раз настроенного времени ожидания.
batchCheckpointFrequency 1 Количество пакетов, обрабатываемых перед созданием контрольной точки для концентратора событий.
prefetchCount 300 Количество событий, запрашиваемых центрами событий и удерживаемых в локальном кэше, чтобы позволить чтениям избежать ожидания в сетевой операции.
transportType amqpTcp Протокол и транспорт, используемые для обмена данными с Центрами событий. Доступные параметры: amqpTcp, amqpWebSockets
webProxy null Прокси-сервер, используемый для взаимодействия с Центрами событий через веб-сокеты. Прокси-сервер нельзя использовать с транспортом amqpTcp.
customEndpointAddress null Адрес, используемый при установке подключения к Центрам событий, позволяющий маршрутизировать сетевые запросы через шлюз приложений или другой путь, необходимый для среды узла. Полное пространство имен для концентратора событий по-прежнему необходимо при использовании пользовательского адреса конечной точки, и оно должно быть явно указано или через строка подключения.
targetUnprocessedEventThreshold1 null Требуемое количество необработанных событий для каждого экземпляра функции. Пороговое значение используется в масштабировании на основе целевого объекта для переопределения порогового значения масштабирования по умолчанию, выводимого maxEventBatchSize из параметра. При установке общее количество необработанных событий делится на это значение, чтобы определить количество необходимых экземпляров функций. Число экземпляров округляется до числа, которое создает сбалансированное распределение секций.
initialOffsetOptions/type fromStart Расположение в потоке событий, с которого следует начать обработку, если контрольная точка не существует в хранилище. Применяется ко всем разделам. Дополнительные сведения см. в документации OffsetType. Доступные параметры: fromStart, fromEnd, fromEnqueuedTime
initialOffsetOptions/enqueuedTimeUtc null Указывает время в очереди для события в потоке, с которого начинается обработка. Если для initialOffsetOptions/type настроено значение fromEnqueuedTime, этот параметр является обязательным. Поддерживает время в любом формате, поддерживаемом в методе DateTime.Parse(), например 2020-10-26T20:31Z. Для ясности следует также указать часовой пояс. Если часовой пояс не указан, Функции предполагают, что используется местный часовой пояс компьютера, на котором запущено приложение-функция (при выполнении в Azure это время в формате UTC).
clientRetryOptions/mode exponential Режим, используемый для расчета интервалов повтора. Экспоненциальный режим пытается повторить попытки с задержкой на основе стратегии отката, в которой каждая попытка увеличит длительность ожидания перед повторным повтором. Фиксированный режим повторяет попытки с фиксированными интервалами с каждой задержкой с согласованной длительностью. Доступные параметры: exponential, fixed
clientRetryOptions/tryTimeout 00:01:00 Максимальное время ожидания выполнения операции центров событий для каждой попытки.
clientRetryOptions/delay 00:00:00.80 Коэффициент задержки или отсрочки, применяемый между повторными попытками.
clientRetryOptions/maximumDelay 00:00:01 Максимальная задержка между повторными попытками.
clientRetryOptions/maximumRetries 3 Максимальное количество повторных попыток, после которого связанная операция будет считаться неудавшейся.

1 Использование minEventBatchSize и maxWaitTime требует версии 5.3.0 Microsoft.Azure.WebJobs.Extensions.EventHubs пакета или более поздней версии.

2 Значение по умолчанию maxEventBatchSize изменилось в версии 6.0.0 Microsoft.Azure.WebJobs.Extensions.EventHubs пакета. В более ранних версиях это было 10.

Они clientRetryOptions используются для повторных операций между узлом функций и Центрами событий (например, получение событий и отправки событий). Дополнительные сведения о применении политик повторных попыток к отдельным функциям см. в руководстве по обработке ошибок Функции Azure.

См. сведения о файле host.json в Функциях Azure версии 2.x и выше.

Следующие шаги