Триггеры таймера для службы "Функции Azure"

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

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

• Справочник разработчика по функциям Azure

• Основные понятия. Триггеры и привязки в функциях Azure

• Как программировать и тестировать функции Azure в локальной среде

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

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

Source code for the timer extension package is in the azure-webjobs-sdk-extensions GitHub repository.

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));
    logger.LogInformation($"Function Ran. Next timer schedule = {timerInfo.ScheduleStatus?.Next}");
}

[FunctionName("TimerTriggerCSharp")]
public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, ILogger log)
{
    if (myTimer.IsPastDue)
    {
        log.LogInformation("Timer is running late!");
    }
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
}

@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);
}

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)

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

import datetime
import logging

import azure.functions as func


def main(mytimer: func.TimerRequest) -> None:
    utc_timestamp = datetime.datetime.now(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)

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,
});

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

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

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

module.exports = async function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    if (myTimer.isPastDue)
    {
        context.log('Node is running late!');
    }
    context.log('Node timer trigger function ran!', timeStamp);   
};

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

# 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"

When you're developing locally, add your application settings in the local.settings.json file in the Values collection.

See the Example section for complete examples.

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
}

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

NCRONTAB expressions

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

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

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

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

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

NCRONTAB examples

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

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

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

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

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

Например, для Восточного времени США (представленного параметром 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. Далее приводятся некоторые примеры.

Scale-out

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

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

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

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

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

Retry behavior

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

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

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

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

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

Troubleshooting

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

Connections

Триггеры таймера имеют неявную зависимость от хранилища BLOB-объектов, за исключением локального запуска с помощью Функции Azure основных средств. Система использует хранилище BLOB-объектов для координации между несколькими экземплярами при горизонтальном масштабировании приложения. Он обращается к хранилищу BLOB-объектов с помощью подключения к хранилищу узлов .AzureWebJobsStorage If you configure the host storage to use an identity-based connection, the identity should have the Storage Blob Data Owner role, which is the default requirement for host storage.

Next steps