Бөлісу құралы:


Триггер таймера для Azure Functions

В этой статье объясняется, как работать с триггерами таймера в Azure Functions. Триггер таймера позволяет выполнять функцию по расписанию.

Это справочная информация для разработчиков Azure Functions. Если вы не знакомы с Azure Functions, начните со следующих ресурсов:

Сведения о том, как вручную запустить функцию, активируемую с помощью таймера, см. в статье о ручном запуске функции, неактивируемой HTTP-запросом.

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

Исходный код пакета расширения таймера находится в репозитории azure-webjobs-sdk-extensions GitHub.

Important

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

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

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

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

Example

В этом примере показана функция C#, которая выполняется каждый раз, когда значение минут кратное пяти. Например, если функция запускается в 18:55:00, следующее выполнение будет в 19:00:00. Объект TimerInfo передается в функцию.

Функцию C# можно создать с помощью одного из следующих режимов C#:

  • Изолированная рабочая модель: скомпилированная функция C#, которая выполняется в рабочем процессе, изолированном от среды выполнения. Изолированный рабочий процесс необходим для поддержки функций C#, работающих в LTS и версиях, отличных от LTS, .NET и платформы .NET. Расширения для изолированных рабочих процессов используют пространства имен Microsoft.Azure.Functions.Worker.Extensions.*.
  • Модель внутрипроцессного процесса: скомпилированная функция C#, которая выполняется в том же процессе, что и среда выполнения Функций. В варианте этой модели функции можно запускать с помощью скриптов C#, которая поддерживается главным образом для редактирования портала C#. Расширения для функций в процессе используют пространства имен Microsoft.Azure.WebJobs.Extensions.*.
[Function(nameof(TimerFunction))]
[FixedDelayRetry(5, "00:00:10")]
public static void Run([TimerTrigger("0 */5 * * * *")] TimerInfo timerInfo,
    FunctionContext context)
{
    var logger = context.GetLogger(nameof(TimerFunction));
    logger.LogInformation($"Function Ran. Next timer schedule = {timerInfo.ScheduleStatus?.Next}");
}

Следующий пример функции активируется и выполняется каждые пять минут. Примечания @TimerTrigger функции определяет расписание, используя тот же формат строки, что и выражения CRON.

@FunctionName("keepAlive")
public void keepAlive(
  @TimerTrigger(name = "keepAliveTrigger", schedule = "0 */5 * * * *") String timerInfo,
      ExecutionContext context
 ) {
     // timeInfo is a JSON string, you can deserialize it to an object using your favorite JSON library
     context.getLogger().info("Timer is triggered: " + timerInfo);
}

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

import datetime
import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="mytimer")
@app.timer_trigger(schedule="0 */5 * * * *", 
              arg_name="mytimer",
              run_on_startup=False) 
def test_function(mytimer: func.TimerRequest) -> None:
    utc_timestamp = datetime.datetime.utcnow().replace(
        tzinfo=datetime.timezone.utc).isoformat()
    if mytimer.past_due:
        logging.info('The timer is past due!')
    logging.info('Python timer trigger function ran at %s', utc_timestamp)

В следующем примере показана функция триггера TypeScript таймера.

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<void> {
    context.log('Timer function processed request.');
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    handler: timerTrigger1,
});

В следующем примере показана функция триггера JavaScript таймера.

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

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    handler: (myTimer, context) => {
        context.log('Timer function processed request.');
    },
});

Данные привязки в файле function.json:

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

Далее приведен код функции таймера в файле run.ps1:

# Input bindings are passed in via param block.
param($myTimer)

# Get the current universal time in the default string format.
$currentUTCtime = (Get-Date).ToUniversalTime()

# The 'IsPastDue' property is 'true' when the current function invocation is later than scheduled.
if ($myTimer.IsPastDue) {
    Write-Host "PowerShell timer is running late!"
}

# Write an information log with the current time.
Write-Host "PowerShell timer trigger function ran! TIME: $currentUTCtime"

Attributes

In-process библиотека C# использует TimerTriggerAttribute из Microsoft. Azure. WebJobs.Extensions в то время как библиотека C# использует библиотеку TimerTriggerAttribute из Microsoft. Azure. Functions.Worker.Extensions.Timer для определения функции. Вместо этого в скрипте C# используется файл конфигурации function.json.

Свойство Атрибута Description
Расписание Значение выражения CRON или TimeSpan. TimeSpan можно использовать только для приложения-функции, которая работает в плане службы приложений. Вы можете поместить выражение расписания в параметр приложения и присвоить этому свойству имя параметра приложения, заключенное в знаки %, следующим образом: %ScheduleAppSetting%.
RunOnStartup Если настроено значение true, функция вызывается при запуске среды выполнения. Например, среда выполнения запускается, когда приложение-функция выходит из спящего режима (в который она перешла из-за отсутствия активности), При перезапуске приложения-функции из-за изменений функций и при горизонтальном масштабировании приложения-функции. Используйте с осторожностью.RunOnStartup редко должен быть установлен true, особенно в рабочей среде.
UseMonitor Установите значение true илиfalse, чтобы указать, следует ли отслеживать расписание. При мониторинге расписания его экземпляры сохраняются, чтобы обеспечить его корректную обработку даже при перезапуске экземпляров приложения-функции. Если значение явно не задано, для расписаний с интервалом повторения более чем 1 минута или равным 1 минуте по умолчанию используется true. Для расписаний, выполняющихся чаще одного раза в минуту, значением по умолчанию является false.

Decorators

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

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

Property Description
arg_name Имя переменной, представляющей объект таймера в коде функции.
schedule Выражение NCRONTAB или значение TimeSpan. TimeSpan можно использовать только для приложения-функции, которая работает в плане службы приложений. Вы можете поместить выражение расписания в параметр приложения и присвоить этому свойству имя параметра приложения, заключенное в знаки %, например: "%ScheduleAppSetting%".
run_on_startup Если настроено значение true, функция вызывается при запуске среды выполнения. Например, среда выполнения запускается, когда приложение-функция выходит из спящего режима (в который она перешла из-за отсутствия активности), При перезапуске приложения-функции из-за изменений функций и при горизонтальном масштабировании приложения-функции. Используйте с осторожностью.runOnStartup редко должен быть установлен true, особенно в рабочей среде.
use_monitor Установите значение true илиfalse, чтобы указать, следует ли отслеживать расписание. При мониторинге расписания его экземпляры сохраняются, чтобы обеспечить его корректную обработку даже при перезапуске экземпляров приложения-функции. Если значение явно не задано, для расписаний с интервалом повторения более чем 1 минута или равным 1 минуте по умолчанию используется true. Для расписаний, выполняющихся чаще одного раза в минуту, значением по умолчанию является false.

Сведения о функциях Python, определенных с помощью function.json<>/c0> см. в разделе Configuration.

Annotations

Примечания @TimerTrigger функции определяет schedule тот же строковый формат, что и выражения CRON. Эта заметка поддерживает следующие параметры:

Configuration

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

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

Property Description
расписание Выражение NCRONTAB или значение TimeSpan. TimeSpan можно использовать только для приложения-функции, которая работает в плане службы приложений. Вы можете поместить выражение расписания в параметр приложения и присвоить этому свойству имя параметра приложения, заключенное в знаки %, например: "%ScheduleAppSetting%".
runOnStartup Если настроено значение true, функция вызывается при запуске среды выполнения. Например, среда выполнения запускается, когда приложение-функция выходит из спящего режима (в который она перешла из-за отсутствия активности), При перезапуске приложения-функции из-за изменений функций и при горизонтальном масштабировании приложения-функции. Используйте с осторожностью.runOnStartup редко должен быть установлен true, особенно в рабочей среде.
useMonitor Установите значение true илиfalse, чтобы указать, следует ли отслеживать расписание. При мониторинге расписания его экземпляры сохраняются, чтобы обеспечить его корректную обработку даже при перезапуске экземпляров приложения-функции. Если значение явно не задано, для расписаний с интервалом повторения более чем 1 минута или равным 1 минуте по умолчанию используется true. Для расписаний, выполняющихся чаще одного раза в минуту, значением по умолчанию является false.

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

свойство function.json Description
type Этому свойству необходимо присвоить значение "timerTrigger". Это свойство устанавливается автоматически при создании триггера на портале Azure.
направление Для этого свойства необходимо задать значение "in". Это свойство устанавливается автоматически при создании триггера на портале Azure.
name Имя переменной, представляющей объект таймера в коде функции.
расписание Выражение NCRONTAB или значение TimeSpan. TimeSpan можно использовать только для приложения-функции, которая работает в плане службы приложений. Вы можете поместить выражение расписания в параметр приложения и присвоить этому свойству имя параметра приложения, заключенное в знаки %, например: "%ScheduleAppSetting%".
runOnStartup Если настроено значение true, функция вызывается при запуске среды выполнения. Например, среда выполнения запускается, когда приложение-функция выходит из спящего режима (в который она перешла из-за отсутствия активности), При перезапуске приложения-функции из-за изменений функций и при горизонтальном масштабировании приложения-функции. Используйте с осторожностью.runOnStartup редко должен быть установлен true, особенно в рабочей среде.
useMonitor Установите значение true илиfalse, чтобы указать, следует ли отслеживать расписание. При мониторинге расписания его экземпляры сохраняются, чтобы обеспечить его корректную обработку даже при перезапуске экземпляров приложения-функции. Если значение явно не задано, для расписаний с интервалом повторения более чем 1 минута или равным 1 минуте по умолчанию используется true. Для расписаний, выполняющихся чаще одного раза в минуту, значением по умолчанию является false.

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

Caution

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

Подробные примеры см. в разделе Примеры.

Usage

При вызове функции триггера с таймером объект таймера передается в функцию. Далее представлен JSON в качестве примера объекта таймера.

{
    "Schedule":{
        "AdjustForDST": true
    },
    "ScheduleStatus": {
        "Last":"2016-10-04T10:15:00+00:00",
        "LastUpdated":"2016-10-04T10:16:00+00:00",
        "Next":"2016-10-04T10:20:00+00:00"
    },
    "IsPastDue":false
}
{
    "schedule":{
        "adjustForDST": true
    },
    "scheduleStatus": {
        "last":"2016-10-04T10:15:00+00:00",
        "lastUpdated":"2016-10-04T10:16:00+00:00",
        "next":"2016-10-04T10:20:00+00:00"
    },
    "isPastDue":false
}

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

Выражения NCRONTAB

Azure Functions использует библиотеку NCronTab для интерпретации выражений NCRONTAB. Выражение NCRONTAB аналогично выражению CRON, за исключением того, что оно включает дополнительное шестое поле в начале для обеспечения точности времени в секундах:

{second} {minute} {hour} {day} {month} {day-of-week}

Каждое поле может принимать значение одного из следующих типов:

Type Example Когда активируется
Определенное значение 0 5 * * * * Один раз каждый час дня на пятой минуте каждого часа
Все значения (*) 0 * 5 * * * В каждую минуту в час, в течение часа 5
Диапазон (оператор -) 5-7 * * * * * Три раза в минуту — с 5-й по 7-ю секунды каждую минуту каждого часа каждого дня
Набор значений (оператор ,) 5,8,10 * * * * * Три раза в минуту — на 5-й, 8-й и 10-й секундах каждую минуту каждого часа каждого дня
Значение интервала (оператор /) 0 */5 * * * * 12 раз в час — в 0 секунд каждой 5-й минуты каждого часа каждого дня

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

  • В течение нескольких дней числовые значения — от 0 до 6, где 0 начинается с воскресенья.
  • Имена указываются на английском языке. Например: Monday, January.
  • Регистр в именах не учитывается.
  • Допускается сокращение имен. Мы рекомендуем использовать три буквы для аббревиаций. Например: Mon, Jan.

Примеры NCRONTAB

Ниже приведены некоторые примеры выражений NCRONTAB, которые можно использовать для триггера таймера в Azure Functions.

Example Когда активируется
0 */5 * * * * через каждые пять минут
0 0 * * * * через каждый час
0 0 */2 * * * через каждые 2 часа
0 0 9-17 * * * один раз в час с 9:00 до 17:00
0 30 9 * * * каждый день в 9:30
0 30 9 * * 1-5 каждый рабочий день в 9:30
0 30 9 * Jan Mon в 9:30 каждый понедельник в январе

Note

Выражение NCRONTAB поддерживает как пять полей , так и шесть полей . Позиция шестого поля — это значение секунд, которое расположено в начале выражения. Если выражение CRON является недопустимым, Azure тест функции портала отобразит ошибку 404, если Application Insights подключены дополнительные сведения регистрируются там.

Часовые пояса NCRONTAB

Числа в выражении NCRONTAB ссылаются на время и дату, а не интервал времени. Например, значение 5 в поле hour означает 5:00, а не каждые 5 часов.

Часовой пояс по умолчанию, используемый с выражениями CRON — время в формате UTC. Если нужно использовать другой часовой пояс в выражении CRON, создайте параметр приложения с именем WEBSITE_TIME_ZONE для вашего приложения функции.

Значение этого параметра зависит от операционной системы и плана, в рамках которого выполняется приложение-функция.

Операционная система Plan Value
Windows All Задайте для значения имя требуемого часового пояса, заданного второй строкой из каждой пары, заданной командой Windows tzutil.exe /L
Линукс Premium
Dedicated
Задайте для значения имя требуемого часового пояса, как показано в базе данных tz

Note

WEBSITE_TIME_ZONE и TZ в настоящее время не поддерживаются при работе на Linux в плане Flex Consumption или Consumption. В этом случае параметр WEBSITE_TIME_ZONE или TZ может создавать проблемы, связанные с SSL, и привести к остановке работы метрик для приложения.

Например, восточное время в США (представленное Eastern Standard Time (Windows) или America/New_York (Linux)) в настоящее время использует UTC-05:00 во время стандартного времени и UTC-04:00 во время дневного света. Чтобы активировать триггер таймера в 10:00 по восточному времени каждый день, создайте параметр приложения-функции с именем WEBSITE_TIME_ZONE, задайте значение Eastern Standard Time (Windows) или America/New_York (Linux), а затем используйте следующее выражение NCRONTAB:

"0 0 10 * * *"

При использовании WEBSITE_TIME_ZONEвремя корректируется для изменения времени в определенном часовом поясе, включая летнее время и изменения в стандартном времени.

TimeSpan

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

В отличие от выражения NCRONTAB, TimeSpan значение указывает интервал времени между вызовом каждой функции. Если функция будет выполняться дольше заданного временного интервала, она немедленно будет активирована таймером.

Когда значения выражения TimeSpan в виде стоки меньше 24, hh:mm:ss будет использовать формат hh. Когда первые две цифры больше или равны 24, будет использован следующий формат dd:hh:mm. Далее приводятся некоторые примеры.

Example Когда активируется
"01:00:00" каждый час
"00:01:00" ежеминутно
"25:00:00:00" каждые 25 дней
"1.00:00:00" Каждый день

Scale-out

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

Совместное использование хранилища приложениями-функциями

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

Версия службы "Функции" Setting
2.x (и более поздние версии) переменная среды AzureFunctionsWebHost__hostid
1.x id в host.json

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

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

Поведение повторных попыток

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

Вызов триггера таймера вручную

Триггер таймера для Azure Functions предоставляет веб-перехватчик HTTP, который можно вызвать вручную, чтобы активировать функцию. Это может быть полезным в указанных ниже случаях.

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

Подробную информацию о том, как вручную вызвать функцию, активируемую по таймеру, см. в статье о ручном запуске функции, не активируемой HTTP-запросом.

Troubleshooting

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

Connections

Триггеры таймера имеют неявную зависимость от хранилища BLOB-объектов, за исключением локального запуска с помощью Azure Functions основных инструментов. Система использует хранилище BLOB-объектов для координации между несколькими экземплярами при горизонтальном масштабировании приложения. Он обращается к хранилищу BLOB-объектов с помощью подключения к хранилищу узлов .AzureWebJobsStorage Если вы настроите хранилище узла для использования подключения на основе удостоверений, удостоверение должно иметь роль владельца данных BLOB-объектов хранилища , которая является требованием по умолчанию для хранилища узлов.

Дальнейшие шаги