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

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

Сведения об установке и настройке см. в обзорной статье.

Используйте выходную привязку Центров событий для записи событий в поток событий. Чтобы записывать события в центр событий, необходимо иметь разрешение на отправку в него событий.

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

Внимание

В этой статье используются вкладки для поддержки нескольких версий модели программирования Node.js. Модель версии 4 общедоступна и предназначена для более гибкого и интуитивно понятного интерфейса для разработчиков JavaScript и TypeScript. Дополнительные сведения о том, как работает модель версии 4, см. в руководстве разработчика по Функции Azure Node.js. Дополнительные сведения о различиях между версиями 3 и 4 см. в руководстве по миграции.

Функции Azure поддерживает две модели программирования для Python. Способ определения привязок зависит от выбранной модели программирования.

версия 2

Модель программирования Python версии 2 позволяет определять привязки с помощью декораторов непосредственно в коде функции Python. Дополнительные сведения см. в руководстве разработчика Python.

версия 1

Модель программирования Python версии 1 требует определения привязок в отдельном файле function.json в папке функции. Дополнительные сведения см. в руководстве разработчика Python.

Эта статья поддерживает обе модели программирования.

Пример

Изолированная рабочая модель

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

[Function(nameof(EventHubFunction))]
[FixedDelayRetry(5, "00:00:10")]
[EventHubOutput("dest", Connection = "EventHubConnection")]
public string EventHubFunction(
    [EventHubTrigger("src", Connection = "EventHubConnection")] string[] input,
    FunctionContext context)
{
    _logger.LogInformation("First Event Hubs triggered message: {msg}", input[0]);

    var message = $"Output message created at {DateTime.Now}";
    return message;
}

Модель внутрипроцессного процесса

Внимание

Поддержка будет завершена для модели в процессе 10 ноября 2026 г. Настоятельно рекомендуется перенести приложения в изолированную рабочую модель для полной поддержки.

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

[FunctionName("EventHubOutput")]
[return: EventHub("outputEventHubMessage", Connection = "EventHubConnectionAppSetting")]
public static string Run([TimerTrigger("0 */5 * * * *")] TimerInfo myTimer, ILogger log)
{
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
    return $"{DateTime.Now}";
}

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

[FunctionName("EH2EH")]
public static async Task Run(
    [EventHubTrigger("source", Connection = "EventHubConnectionAppSetting")] EventData[] events,
    [EventHub("dest", Connection = "EventHubConnectionAppSetting")]IAsyncCollector<EventData> outputEvents,
    ILogger log)
{
    foreach (EventData eventData in events)
    {
        // Do some processing:
        string newEventBody = DoSomething(eventData);

        // Queue the message to be sent in the background by adding it to the collector.
        // If only the event is passed, an Event Hubs partition to be assigned via
        // round-robin for each batch.
        await outputEvents.AddAsync(new EventData(newEventBody));

        // If your scenario requires that certain events are grouped together in an
        // Event Hubs partition, you can specify a partition key.  Events added with 
        // the same key will always be assigned to the same partition.        
        await outputEvents.AddAsync(new EventData(newEventBody), "sample-key");
    }
}

Модель версии 4

В следующем примере показана функция TypeScript таймера, которая отправляет одно сообщение в концентратор событий:

import { app, InvocationContext, output, Timer } from '@azure/functions';

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.eventHub({
        eventHubName: 'myeventhub',
        connection: 'MyEventHubSendAppSetting',
    }),
    handler: timerTrigger1,
});

Чтобы вывести несколько сообщений, верните массив вместо одного объекта. Например:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Модель версии 3

Примеры TypeScript не документируются для модели версии 3.

Модель версии 4

В следующем примере показана функция JavaScript таймера, которая отправляет одно сообщение в концентратор событий:

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

const eventHubOutput = output.eventHub({
    eventHubName: 'myeventhub',
    connection: 'MyEventHubSendAppSetting',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: eventHubOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

Чтобы вывести несколько сообщений, верните массив вместо одного объекта. Например:

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

Модель версии 3

В следующем примере показаны привязка триггера центра событий в файле function.json и функция, которая использует эту привязку. Эта функция записывает выходное сообщение в центр событий.

В следующем примере показаны данные привязки центров событий в файле function.json, который отличается для среды выполнения Функций версии 1.x по сравнению с более поздними версиями.

{
    "type": "eventHub",
    "name": "outputEventHubMessage",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Ниже приведен код JavaScript, который отправляет отдельное сообщение.

module.exports = function (context, myTimer) {
    var timeStamp = new Date().toISOString();
    context.log('Message created at: ', timeStamp);   
    context.bindings.outputEventHubMessage = "Message created at: " + timeStamp;
    context.done();
};

Ниже приведен код JavaScript, который отправляет несколько сообщений.

module.exports = function(context) {
    var timeStamp = new Date().toISOString();
    var message = 'Message created at: ' + timeStamp;

    context.bindings.outputEventHubMessage = [];

    context.bindings.outputEventHubMessage.push("1 " + message);
    context.bindings.outputEventHubMessage.push("2 " + message);
    context.done();
};

Скоро должны появиться полные примеры PowerShell.

В следующем примере показана привязка триггера концентратора событий и функция Python, использующая привязку. Эта функция записывает сообщение в концентратор событий. Пример зависит от того, используется ли модель программирования Python версии 1 или версии 2.

версия 2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")
def eventhub_output(req: func.HttpRequest, event: func.Out[str]):
    body = req.get_body()
    if body is not None:
        event.set(body.decode('utf-8'))
    else:    
        logging.info('req body is none')
    return 'ok'

Ниже приведен код Python, который отправляет несколько сообщений:

import logging
import azure.functions as func
from typing import List

app = func.FunctionApp()

@app.function_name(name="eventhub_output")
@app.route(route="eventhub_output")
@app.event_hub_output(arg_name="event",
                      event_hub_name="<EVENT_HUB_NAME>",
                      connection="<CONNECTION_SETTING>")

def eventhub_output(req: func.HttpRequest, event: func.Out[List[str]]) -> func.HttpResponse:
    my_messages=["message1", "message2","message3"]
    event.set(my_messages)
    return func.HttpResponse(f"Messages sent")

версия 1

В приведенных ниже примерах показаны данные привязки Центров событий в файле function.json.

{
    "type": "eventHub",
    "name": "$return",
    "eventHubName": "myeventhub",
    "connection": "MyEventHubSendAppSetting",
    "direction": "out"
}

Ниже приведен код Python, который отправляет отдельное сообщение.

import datetime
import logging
import azure.functions as func


def main(timer: func.TimerRequest) -> str:
    timestamp = datetime.datetime.utcnow()
    logging.info('Message created at: %s', timestamp)
    return 'Message created at: {}'.format(timestamp)

Ниже приведен код Python, который отправляет несколько сообщений:

import logging
from typing import List
import azure.functions as func


def main(req: func.HttpRequest, messages:func.Out[List[str]]) -> func.HttpResponse:
    logging.info('Python HTTP trigger function processed a request.')
    messages.set([{"message1"}, {"message2"}])
    return func.HttpResponse(f"Messages sent")

В следующем примере показана функция Java, которая записывает сообщение, содержащее текущее время в концентратор событий.

@FunctionName("sendTime")
@EventHubOutput(name = "event", eventHubName = "samples-workitems", connection = "AzureEventHubConnection")
public String sendTime(
   @TimerTrigger(name = "sendTimeTrigger", schedule = "0 */5 * * * *") String timerInfo)  {
     return LocalDateTime.now().toString();
 }

В библиотеке среды выполнения функций Java используйте заметку @EventHubOutput о параметрах, значение которых будет опубликовано в Центрах событий. Параметр должен быть типа OutputBinding<T>, где T — это POJO или любой собственный тип Java.

Атрибуты

Библиотеки C# в процессе и изолированном рабочем процессе используют атрибут для настройки привязки. Вместо этого скрипт C# использует файл конфигурации function.json, как описано в руководстве по скриптам C#.

Изолированная рабочая модель

Используйте атрибут [EventHubOutputAttribute], чтобы определить выходную привязку к центру событий, которая поддерживает следующие свойства.

Параметры	Description
EventHubName	Имя концентратора событий. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.
Соединение	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к центрам событий. Дополнительные сведения см. в разделе Подключения.

Модель внутрипроцессного процесса

Используйте атрибут EventHubAttribute для определения выходной привязки к центру событий, который поддерживает следующие свойства.

Параметры	Description
EventHubName	Имя концентратора событий. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.
Соединение	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к центрам событий. Дополнительные сведения см. в разделе Подключения.

Декораторы

Применяется только к модели программирования Python версии 2.

Для функций Python версии 2, определенных с помощью декоратора, эти свойства поддерживаются для event_hub_output:

Свойство	Description
arg_name	Имя переменной, используемое в коде функции, которая представляет событие.
event_hub_name	имя концентратора событий. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.
connection	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к центрам событий. Дополнительные сведения см. в разделе Подключения.

Сведения о функциях Python, определенных с помощью function.json, см. в разделе "Конфигурация ".

Заметки

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

• name
• dataType
• eventHubName
• Подключение

Настройка

Применяется только к модели программирования Python версии 1.

Модель версии 4

В следующей таблице описываются свойства, которые можно задать для options объекта, переданного методу output.eventHub() .

Свойство	Description
eventHubName	Имя концентратора событий. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.
Подключение	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к центрам событий. Дополнительные сведения см. в разделе Подключения.

Модель версии 3

В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json.

Свойство	Описание
type	Должен иметь значениеeventHub.
direction	Должен иметь значениеout. Этот параметр задается автоматически при создании привязки на портале Azure.
name	Имя переменной, используемое в коде функции, которая представляет событие.
eventHubName	Имя концентратора событий. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.
Подключение	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к центрам событий. Дополнительные сведения см. в разделе Подключения.

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

Функции 2.x+

Свойство в function.json	Описание
type	Должен иметь значениеeventHub.
direction	Должен иметь значениеout. Этот параметр задается автоматически при создании привязки на портале Azure.
name	Имя переменной, используемое в коде функции, которая представляет событие.
eventHubName	Функции 2.x и более поздних версий. Имя концентратора событий. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.
Подключение	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к центрам событий. Дополнительные сведения см. в разделе Подключения.

Функции 1.x

Свойство в function.json	Описание
type	Должен иметь значениеeventHub.
direction	Должен иметь значениеout. Этот параметр задается автоматически при создании привязки на портале Azure.
name	Имя переменной, используемое в коде функции, которая представляет событие.
path	Только служба "Функции" версии 1.x. Имя концентратора событий. Если имя концентратора событий указано также в строке подключения, такое значение переопределяет это свойство во время выполнения.
Подключение	Имя параметра или коллекции параметров приложения, указывающих, как подключиться к центрам событий. Дополнительные сведения см. в разделе Подключения.

Если разработка ведется на локальном компьютере, добавьте параметры приложения в файл local.settings.json в коллекции Values.

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

Тип параметра, поддерживаемый выходной привязкой Центров событий, зависит от версии среды выполнения Функций, версии пакета расширения и используемой модальности C#.

Расширение версии 5.x+

Внутрипроцессные функции библиотеки классов C# поддерживают следующие типы:

• Azure.Messaging.EventHubs.EventData
• Строка
• массив байтов;
• Объект POCO

В этой версии EventData прекращена поддержка устаревшего типа Body. Вместо него теперь поддерживается тип EventBody.

Для отправки сообщений используйте параметр метода, например out string paramName. Для записи нескольких сообщений можно использовать ICollector<EventData> или IAsyncCollector<EventData> вместо out string. Ключи секций могут использоваться только с IAsyncCollector<EventData>.

Расширение версии 3.x+

Внутрипроцессные функции библиотеки классов C# поддерживают следующие типы:

• Microsoft.Azure.EventHubs.EventData
• Строка
• массив байтов;
• Объект POCO

Для отправки сообщений используйте параметр метода, например out string paramName. Для записи нескольких сообщений можно использовать ICollector<string> или IAsyncCollector<string> вместо out string.

Расширение версии 5.x+

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

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

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

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

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

Расширение версии 3.x+

Требуется определить пользовательский тип или использовать строку. Дополнительные параметры доступны в extension v5.x+.

Существует два варианта вывода сообщения Центров событий из функции с помощью заметки EventHubOutput :

• Возвращаемое значение. Применив заметку к самой функции, возвращаемое значение функции сохраняется в виде сообщения Центров событий.

• Императив. Чтобы явно задать значение сообщения, примените заметку к конкретному параметру типа OutputBinding<T>, где T находится POJO или любой собственный тип Java. При использовании этой конфигурации передача значения setValue методу сохраняет значение в виде сообщения Центров событий.

Скоро должны появиться полные примеры PowerShell.

Модель версии 4

Доступ к выходному сообщению, возвращая значение напрямую или используя context.extraOutputs.set().

Модель версии 3

Доступ к выходному событию с помощью context.bindings.<name>, где <name> — это значение, указанное в свойстве name файла function.json.

Существует два варианта вывода сообщения Центров событий из функции:

• Возвращаемое значение: задайте name для свойства в function.json значение $return. При этой конфигурации возвращаемое значение функции сохраняется в виде сообщения Центров событий.

• Императив. Передайте значение в метод set параметра, объявленного как тип Out . Переданное значение set сохраняется в виде сообщения Центров событий.

Связи

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

• Имя параметра приложения, содержащего строку подключения.
• Имя общего префикса для нескольких параметров приложения, а также определение подключения на основе удостоверений.

Если настроенное значение одновременно точно соответствует одному параметру и является префиксом для других параметров, то используется точное совпадение.

Connection string

Получите эту строку подключения, нажав кнопку Сведения о подключении для пространства имен, а не сам центр событий. Требуется строка подключения для пространства имен Центров событий, а не самого центра событий.

При использовании для триггеров строка подключения должна иметь по крайней мере разрешения на чтение для активации функции. При использовании для выходных привязок строка подключения должна иметь разрешения на отправку для отправки сообщений в поток событий.

Эта строка подключения должна храниться в параметре приложения с именем, соответствующим значению, которое указано свойством connection конфигурации привязки.

Подключения на основе удостоверений

Если вы используете расширение версии 5.x или выше, вместо использования строка подключения с секретом, вы можете использовать удостоверение Microsoft Entra. Для этого необходимо определить параметры под общим префиксом, который соответствует свойству connection в конфигурации триггера и привязки.

В этом режиме для расширения требуются следующие свойства:

Свойство	Шаблон переменной среды	Description	Пример значения
Пространство полных имен	<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace	Пространство полных имен центров событий.	myeventhubns.servicebus.windows.net

Для настройки подключения можно задать дополнительные свойства. См. раздел Общие свойства подключений на основе удостоверений.

Примечание.

При использовании Конфигурации приложений Azure или Key Vault для предоставления параметров подключений Управляемого удостоверения имена параметров должны использовать допустимый разделитель ключей, например : или /, вместо __, чтобы обеспечить правильное разрешение имен.

Например, <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace.

При размещении в службе "Функции Azure" для подключений на основе удостоверений используется управляемое удостоверение. По умолчанию используется назначаемое системой удостоверение, однако вы можете указать назначаемое пользователем удостоверение с помощью свойств credential и clientID. Обратите внимание, что настройка назначаемого пользователем удостоверения с идентификатором ресурса не поддерживается. При выполнении в других контекстах, например при локальной разработке, вместо этого используется удостоверение разработчика, хотя это можно настроить. См. раздел Локальная разработка с использованием подключений на основе удостоверений.

Предоставление разрешения удостоверению

Любое используемое удостоверение должно иметь разрешения на выполнение предполагаемых действий. Для большинства служб Azure это означает, что необходимо назначить роль в Azure RBAC, используя встроенные или настраиваемые роли, которые предоставляют эти разрешения.

Внимание

Иногда целевая служба может предоставлять разрешения, которые не являются обязательными для всех контекстов. Там, где это возможно, придерживайтесь принципа минимальных привилегий, предоставляя удостоверению лишь самые необходимые привилегии. Например, если приложению требуется только возможность чтения из источника данных, используйте роль, которая имеет разрешение только на чтение. Было бы неуместным назначить роль, которая также разрешает запись в эту службу, так как это разрешение не требуется для операции чтения. Соответственно необходимо еще проверить, что область действия назначенной роли ограничена только теми ресурсами, которые необходимо прочитать.

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

Тип привязки	Примеры встроенных ролей
Триггер	Получатель данных Центров событий Azure, Владелец данных Центров событий Azure
Выходные привязки	Отправитель данных Центров событий Azure

Исключения и коды возврата

Привязка	Справочные материалы
Event Hubs	Руководство по операциям

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

• Реагирование на события, отправляемые в поток событий Центра событий (Триггер)