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

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

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

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

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

Пример

В следующем примере показана функция 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<string> outputEvents,
    ILogger log)
{
    foreach (EventData eventData in events)
    {
        // do some processing:
        var myProcessedEvent = DoSomething(eventData);

        // then send the message
        await outputEvents.AddAsync(JsonConvert.SerializeObject(myProcessedEvent));
    }
}

В следующем примере показаны привязка триггера центра событий в файле 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.

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

В приведенных ниже примерах показаны данные привязки Центров событий в файле 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)

В следующем примере показана функция 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.

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

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

Заметки

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

Конфигурация

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Соединения

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

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

строку подключения.

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Важно!

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

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

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

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

Привязка Справочник
Концентратор событий Руководство по операциям

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