Триггеры таймера для службы "Функции Azure"
В этой статье описывается, как работать с триггерами таймера в службе "Функции Azure". Триггер таймера позволяет выполнять функцию по расписанию.
Это справочные сведения для разработчиков функций Azure. Если вы новичок в функциях Azure, начните со следующих ресурсов:
Ссылки для разработчиков C#:
Сведения о том, как вручную запустить функцию, активируемую с помощью таймера, см. в статье о ручном запуске функции, неактивируемой HTTP-запросом.
Поддержка этой привязки автоматически предоставляется во всех средах разработки. Не нужно вручную устанавливать пакет или регистрировать расширение.
Исходный код для пакета расширений таймера находится в репозитории GitHub azure-webjobs-sdk-extensions.
Внимание
В этой статье используются вкладки для поддержки нескольких версий модели программирования Node.js. Модель версии 4 общедоступна и предназначена для более гибкого и интуитивно понятного интерфейса для разработчиков JavaScript и TypeScript. Дополнительные сведения о том, как работает модель версии 4, см. в руководстве разработчика по Функции Azure Node.js. Дополнительные сведения о различиях между версиями 3 и 4 см. в руководстве по миграции.
Функции Azure поддерживает две модели программирования для Python. Способ определения привязок зависит от выбранной модели программирования.
Модель программирования Python версии 2 позволяет определять привязки с помощью декораторов непосредственно в коде функции Python. Дополнительные сведения см. в руководстве разработчика Python.
Эта статья поддерживает обе модели программирования.
Пример
В этом примере показана функция C#, которая выполняется каждый раз, когда значение минут кратное пяти. Например, если функция запускается в 18:55:00, следующее выполнение будет в 19:00:00. Объект TimerInfo передается в функцию.
Функцию C# можно создать с помощью одного из следующих режимов C#:
- Изолированная рабочая модель: скомпилированная функция C#, которая выполняется в рабочем процессе, изолированном от среды выполнения. Изолированный рабочий процесс необходим для поддержки функций C#, работающих в LTS и не LTS-версиях .NET и платформа .NET Framework. Расширения для изолированных рабочих процессов используют
Microsoft.Azure.Functions.Worker.Extensions.*пространства имен. - Модель внутрипроцессного процесса: скомпилированная функция C#, которая выполняется в том же процессе, что и среда выполнения Функций. В варианте этой модели функции можно запускать с помощью скриптов C#, которая поддерживается главным образом для редактирования портала C#. Расширения для функций в процессе используют
Microsoft.Azure.WebJobs.Extensions.*пространства имен.
Внимание
Поддержка будет завершена для модели в процессе 10 ноября 2026 г. Настоятельно рекомендуется перенести приложения в изолированную рабочую модель для полной поддержки.
//<docsnippet_fixed_delay_retry_example>
[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));
Следующий пример функции активируется и выполняется каждые пять минут. Аннотация @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);
}
В следующем примере показана привязка триггера таймера и код функции, использующий привязку, где экземпляр, представляющий таймер, передается функции. Эта функция выполняет запись в журнал, указывая, когда ее вызов выполняется из-за пропущенного запуска по расписанию. Пример зависит от того, используется ли модель программирования Python версии 1 или версии 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=True)
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"
Атрибуты
Библиотека 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. |
Декораторы
Применяется только к модели программирования Python версии 2.
Для функций Python версии 2, определенных с помощью декоратора, в следующих свойствах schedule:
| Свойство | Description |
|---|---|
arg_name |
Имя переменной, представляющей объект таймера в коде функции. |
schedule |
Значение выражения CRON или TimeSpan. TimeSpan можно использовать только для приложения-функции, которая работает в плане службы приложений. Вы можете поместить выражение расписания в параметр приложения и присвоить этому свойству имя параметра приложения, заключенное в знаки %, например: "%ScheduleAppSetting%". |
run_on_startup |
Если настроено значение true, функция вызывается при запуске среды выполнения. Например, среда выполнения запускается, когда приложение-функция выходит из спящего режима (в который она перешла из-за отсутствия активности), когда приложение-функция перезапускается из-за изменения функции или когда приложение-функция масштабируется. Используйте с осторожностью. Для runOnStartup особенно в рабочей среде, следует очень редко задавать значение true или не задавать вообще. |
use_monitor |
Установите значение true илиfalse, чтобы указать, следует ли отслеживать расписание. При мониторинге расписания его экземпляры сохраняются, чтобы обеспечить его корректную обработку даже при перезапуске экземпляров приложения-функции. Если значение явно не задано, для расписаний с интервалом повторения более чем 1 минута или равным 1 минуте по умолчанию используется true. Для расписаний, выполняющихся чаще одного раза в минуту, значением по умолчанию является false. |
Сведения о функциях Python, определенных с помощью function.json, см. в разделе "Конфигурация ".
Заметки
Аннотация @TimerTrigger для функции определяет schedule, используя тот же формат строки, что и выражения CRON. Эта заметка поддерживает следующие параметры:
Настройка
Применяется только к модели программирования Python версии 1.
В следующей таблице описываются свойства, которые можно задать для options объекта, переданного методу app.timer() .
| Свойство | Description |
|---|---|
| schedule | Значение выражения CRON или TimeSpan. TimeSpan можно использовать только для приложения-функции, которая работает в плане службы приложений. Вы можете поместить выражение расписания в параметр приложения и присвоить этому свойству имя параметра приложения, заключенное в знаки %, например: "%ScheduleAppSetting%". |
| runOnStartup | Если настроено значение true, функция вызывается при запуске среды выполнения. Например, среда выполнения запускается, когда приложение-функция выходит из спящего режима (в который она перешла из-за отсутствия активности), когда приложение-функция перезапускается из-за изменения функции или когда приложение-функция масштабируется. Используйте с осторожностью. Для runOnStartup особенно в рабочей среде, следует очень редко задавать значение true или не задавать вообще. |
| useMonitor | Установите значение true илиfalse, чтобы указать, следует ли отслеживать расписание. При мониторинге расписания его экземпляры сохраняются, чтобы обеспечить его корректную обработку даже при перезапуске экземпляров приложения-функции. Если значение явно не задано, для расписаний с интервалом повторения более чем 1 минута или равным 1 минуте по умолчанию используется true. Для расписаний, выполняющихся чаще одного раза в минуту, значением по умолчанию является false. |
В следующей таблице описываются свойства конфигурации привязки, которые задаются в файле function.json.
| Свойство в function.json | Описание |
|---|---|
| type | Этому свойству необходимо присвоить значение "timerTrigger". Это свойство задается автоматически при создании триггера на портале Azure. |
| direction | Для этого свойства необходимо задать значение "in". Это свойство задается автоматически при создании триггера на портале Azure. |
| name | Имя переменной, представляющей объект таймера в коде функции. |
| schedule | Значение выражения CRON или TimeSpan. TimeSpan можно использовать только для приложения-функции, которая работает в плане службы приложений. Вы можете поместить выражение расписания в параметр приложения и присвоить этому свойству имя параметра приложения, заключенное в знаки %, например: "%ScheduleAppSetting%". |
| runOnStartup | Если настроено значение true, функция вызывается при запуске среды выполнения. Например, среда выполнения запускается, когда приложение-функция выходит из спящего режима (в который она перешла из-за отсутствия активности), когда приложение-функция перезапускается из-за изменения функции или когда приложение-функция масштабируется. Используйте с осторожностью. Для runOnStartup особенно в рабочей среде, следует очень редко задавать значение true или не задавать вообще. |
| useMonitor | Установите значение true илиfalse, чтобы указать, следует ли отслеживать расписание. При мониторинге расписания его экземпляры сохраняются, чтобы обеспечить его корректную обработку даже при перезапуске экземпляров приложения-функции. Если значение явно не задано, для расписаний с интервалом повторения более чем 1 минута или равным 1 минуте по умолчанию используется true. Для расписаний, выполняющихся чаще одного раза в минуту, значением по умолчанию является false. |
Если разработка ведется на локальном компьютере, добавьте параметры приложения в файл local.settings.json в коллекции Values.
Внимание
Не устанавливайте для параметра runOnStartup значение true в рабочей среде. Использование этого параметра заставляет код выполняться в очень непредсказуемое время. В определенных рабочих ситуациях эти дополнительные выполнения могут привести значительно более высоким затратам для приложений, размещенных в планах потребления. Например, если runOnStartup включен, триггер вызывается всякий раз при масштабировании приложения-функции. Убедитесь, что вы полностью понимаете рабочее поведение своих функций перед включением runOnStartup в рабочей среде.
Подробные примеры см. в разделе Примеры.
Использование
При вызове функции триггера с таймером объект таймера передается в функцию. Далее представлен 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
}
Значение свойства isPastDue — true, когда текущая функция вызывается позже запланированного. Например перезапуск приложения-функции может привести к тому, что вызов будет пропущен.
Выражения NCRONTAB
Функции Azure используют библиотеку NCronTab для интерпретации выражений NCRONTAB. Выражение NCRONTAB аналогично выражению CRON, за исключением того, что оно включает дополнительное шестое поле в начале для обеспечения точности времени в секундах:
{second} {minute} {hour} {day} {month} {day-of-week}
Каждое поле может принимать значение одного из следующих типов:
| Тип | Пример | Когда активируется |
|---|---|---|
| Определенное значение | 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".
| Пример | Когда активируется |
|---|---|
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 каждый понедельник в январе |
Примечание.
Выражение NCRONTAB поддерживает форматы пяти полей и шести полей. Позиция шестого поля — это значение секунд, которое расположено в начале выражения.
Часовые пояса NCRONTAB
Числа в выражении CRON представляют собой время и дату, а не временной интервал. Например, значение 5 в поле hour означает 5:00, а не каждые 5 часов.
Часовой пояс по умолчанию, используемый с выражениями CRON — время в формате UTC. Если нужно использовать другой часовой пояс в выражении CRON, создайте параметр приложения с именем WEBSITE_TIME_ZONE для приложения-функции.
Значение этого параметра зависит от операционной системы и плана, в рамках которого выполняется приложение-функция.
| Операционная система | Планирование | Значение |
|---|---|---|
| Windows | Все | Задайте в качестве значения имя нужного часового пояса, которое задается второй строкой каждой пары параметров, определяемых командой Windows tzutil.exe /L |
| Linux | Premium Выделенные |
В качестве значения задайте имя нужного часового пояса, как указано в базе данных часовых поясов. |
Примечание.
WEBSITE_TIME_ZONE и TZ в настоящее время не поддерживаются при запуске в Linux в плане потребления. В этом случае можно задать 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 можно использовать только для приложения-функции, которая работает в плане службы приложений.
В отличие от выражения CRON значение TimeSpan задает интервал времени между каждым вызовом функции. Если функция будет выполняться дольше заданного временного интервала, она немедленно будет активирована таймером.
Когда значения выражения hh в виде стоки меньше 24, TimeSpan будет использовать формат hh:mm:ss. Когда первые две цифры больше или равны 24, будет использован следующий формат dd:hh:mm. Далее приводятся некоторые примеры.
| Пример | Когда активируется |
|---|---|
| "01:00:00" | каждый час |
| "00:01:00" | каждую минуту |
| "25:00:00:00" | каждые 25 дней |
| "1.00:00:00" | ежедневно |
Расширение
Если приложение-функция будет развернуто на несколько экземпляров, то только один из экземпляров активируемой по таймеру функции выполняется для всех экземпляров. Повторная активация не происходит, если необработанный вызов все еще выполняется.
Совместное использование хранилища приложениями-функциями
При совместном использовании учетных записей хранения в приложениях-функциях, которые не развернуты в службе приложений, может потребоваться явно назначить идентификатор узла каждому приложению.
| Версия службы "Функции" | Параметр |
|---|---|
| 2.x (и более поздние версии) | Переменная среды AzureFunctionsWebHost__hostid. |
| 1.x | id в host.json |
Вы можете пропустить идентифицирующее значение или вручную задать другое значение для каждой идентифицирующей конфигурации приложения-функции.
Для триггера таймера используется блокировка хранилища. Она гарантирует наличие только одного экземпляра таймера, когда приложение-функция масштабируется до нескольких экземпляров. Если у двух приложений-функций одна идентифицирующая конфигурация и для каждого используется триггер таймера, запустится только один таймер.
Поведение при повторе
В отличие от триггера очереди триггер таймера не осуществляет повторную попытку после того, как произошла ошибка выполнения функции. Когда функция возвращает ошибку, следующий раз она будет вызвана только по расписанию.
Вызов триггера таймера вручную
Триггер таймера для Функций Azure предоставляет веб-перехватчик HTTP, который можно вызвать для запуска функции вручную. Это может быть полезным в указанных ниже случаях.
- Тестирование интеграции
- Переключение слотов в рамках теста состояния или действия прогрева.
- Начальное развертывание функции для немедленного заполнения кэша или таблицы подстановки в базе данных.
Подробную информацию о том, как вручную вызвать функцию, активируемую по таймеру, см. в статье о ручном запуске функции, не активируемой HTTP-запросом.
Устранение неполадок
Дополнительные сведения о том, что делать, когда триггер таймера неисправен, см. в разделе Расследование проблем, когда функции, вызываемые таймером, не срабатывают.