Триггер хранилища очередей Azure для Функций Azure

Триггер хранилища очередей запускает функцию при добавлении сообщений в хранилище очередей Azure.

Кодирование

Функции ожидают строку в кодировке base64. Любая корректировка типа кодирования (для подготовки данных в виде строки в кодировке base64) должна быть реализована в вызывающей службе.

Пример

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

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

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

Атрибуты и заметки

В библиотеках классов C# используйте следующие атрибуты для настройки триггера очереди:

  • QueueTriggerAttribute

    Конструктор атрибута принимает имя очереди для отслеживания, как показано в следующем примере:

    [FunctionName("QueueTrigger")]
    public static void Run(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        ...
    }
    

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

    [FunctionName("QueueTrigger")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
        ILogger log)
    {
        ....
    }
    

    Полный пример см. здесь.

  • StorageAccountAttribute

    Предоставляет еще один способ указать используемую учетную запись хранения. Конструктор принимает имя параметра приложения, содержащего строку подключения к службе хранилища. Атрибут может применяться на уровне класса, метода или параметра. Ниже показан пример уровня класса и метода.

    [StorageAccount("ClassLevelStorageAppSetting")]
    public static class AzureFunctions
    {
        [FunctionName("QueueTrigger")]
        [StorageAccount("FunctionLevelStorageAppSetting")]
        public static void Run( //...
    {
        ...
    }
    

Используемая учетная запись хранения определяется в следующем порядке:

  • Свойство QueueTrigger атрибута Connection.
  • Атрибут StorageAccount, примененный к тому же параметру, что и QueueTrigger.
  • Атрибут StorageAccount, примененный к функции.
  • Атрибут StorageAccount, примененный к классу.
  • Параметр приложения AzureWebJobsStorage.

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

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

свойство function.json Свойство атрибута Описание
type Недоступно Нужно задать значение queueTrigger. Это свойство задается автоматически при создании триггера на портале Azure.
direction Недоступно Только в файле function.json. Нужно задать значение in. Это свойство задается автоматически при создании триггера на портале Azure.
name Недоступно Имя переменной, содержащей полезные данные элемента очереди в коде функции.
queueName QueueName Имя очереди для опроса.
connection; Соединение Имя параметра приложения, содержащего строку подключения к службе хранилища, используемой для этой привязки. Если имя параметра приложения начинается с AzureWebJobs, можно указать только остальную часть имени.

Например, если задать для connection значение MyStorage, среда выполнения службы "Функции" будет искать параметр приложения с именем MyStorage. Если оставить строку connection пустой, среда выполнения службы "Функции" будет использовать строку подключения к службе хранилища по умолчанию для параметра приложения с именем AzureWebJobsStorage.

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

При локальной разработке параметры приложения перейдут в файл local.settings.json.

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

По умолчанию

Для доступа к данным сообщения используйте параметр метода, например string paramName. Вы можете выполнить привязку к одному из следующих типов:

  • Объект. Среда выполнения службы "Функции" десериализует полезные данные JSON в экземпляр произвольного класса, определенного в коде.
  • string
  • byte[]
  • CloudQueueMessage

Если при попытке привязать к CloudQueueMessage вы получаете сообщение об ошибке, убедитесь, что у вас есть ссылка на правильную версию пакета SDK для службы хранилища.

Дополнительные типы

В приложениях, в которых используетсярасширение службы хранилища версии 5.0.0 или выше, также могут использоваться типы из пакета Azure SDK для .NET. В этой версии прекращена поддержка устаревшего типа CloudQueueMessage. Вместо него теперь поддерживаются следующие типы:

Примеры использования этих типов см. в разделе репозитория GitHub для расширения.

Метаданные сообщения

Триггер очереди предоставляет несколько свойств метаданных. Эти свойства можно использовать как часть выражений привязки в других привязках или как параметры в коде. Свойства являются элементами класса CloudQueueMessage.

Свойство Тип Описание
QueueTrigger string Полезные данные очереди (если это допустимая строка). Если полезные данные очереди сообщений представлены в виде строки, значение QueueTrigger совпадает со значением переменной, имя которой назначено свойством name в файле function.json.
DequeueCount int Количество раз, когда сообщение было выведено из очереди.
ExpirationTime DateTimeOffset Время истечения срока действия сообщения.
Id string Идентификатор сообщения в очереди.
InsertionTime DateTimeOffset Время, когда сообщение было добавлено в очередь.
NextVisibleTime DateTimeOffset Время, когда сообщение станет видимым в следующий раз.
PopReceipt string Уведомление о получении сообщения.

Сообщения о сбое

При сбое функции триггера очереди по умолчанию служба "Функции Azure" выполняет ее для заданного сообщения очереди еще пять раз (включая первую попытку). В случае сбоя всех пяти попыток среда выполнения функций добавляет сообщение в очередь с именем <имя_первоначальной_очереди>-poison. Можно написать функции для обработки сообщений из очереди подозрительных сообщений путем внесения их в журнал или отправки уведомления о необходимости ручного вмешательства.

Для обработки сообщений о сбоях вручную проверьте значение dequeueCount сообщения очереди.

Блокировка быстрого редактирования

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

При запуске функция начинает обработку сообщения при описанных ниже условиях.

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

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

Алгоритм опроса

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

В алгоритме заложена следующая логика:

  • При обнаружении сообщения среда выполнения начинает искать новое сообщение через 100 миллисекунд.
  • Если новое сообщение не обнаружено, примерно через 200 миллисекунд начинается повторный поиск.
  • После последующих неудачных попыток получения сообщения очереди время ожидания продолжает увеличиваться, пока не достигнет максимального времени ожидания, по умолчанию — одна минута.
  • Максимальное время ожидания настраивается при помощи свойства maxPollingInterval в файле host.json.

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

Примечание

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

Параллелизм

При наличии нескольких сообщений, ожидающих в очереди, триггер очереди извлекает пакет сообщений и в параллельном режиме вызывает экземпляры функций для обработки. По умолчанию в пакете содержится 16 сообщений. Когда число обрабатываемых сообщений снижается до 8, среда выполнения получает следующий пакет и начинает обработку содержащихся в нем сообщений. Поэтому максимальное количество сообщений, одновременно обрабатываемых каждой функцией на одной виртуальной машине, равно 24. Это ограничение применяется отдельно к каждой функции, активируемой с помощью очереди, на каждой виртуальной машине. Если приложение-функция масштабируется на несколько виртуальных машин, каждая машина будет ожидать триггеров и пытаться выполнить функции. Например, если приложение-функция масштабируется на 3 виртуальные машины, то максимальное количество параллельных экземпляров одной функции, активируемой с помощью очереди, равно 72.

Размер пакета и порог для получения нового пакета настраиваются в файле host.json. Если в приложении-функции требуется свести к минимуму параллельное выполнение функций, активируемых с помощью очереди, вы можете задать для размера пакета значение 1. Этот параметр позволяет исключить параллелизм только при условии, что приложение-функция выполняется на одной виртуальной машине.

Триггер очереди автоматически не дает функции одновременно обрабатывать сообщения очереди несколько раз.

Свойства host.json

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

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