Azure Functions のタイマー トリガー

この記事では、Azure Functions でタイマー トリガーを使用する方法について説明します。 タイマー トリガーを使用すると、スケジュールに基づいて関数を実行できます。

これは、Azure Functions の開発者向けリファレンス情報です。 Azure Functions を初めて使用する場合は、先に次のリソースを参照してください。

タイマーによってトリガーされる関数を手動で実行する方法については、「HTTP によってトリガーされない関数を手動で実行する」を参照してください。

このバインドのサポートは、すべての開発環境で自動的に提供されます。 手動でパッケージをインストールしたり、拡張機能を登録したりする必要はありません。

タイマー拡張機能パッケージのソース コードは、azure-webjobs-sdk-extensions GitHub リポジトリにあります。

この例では、分の値が 5 の倍数になるたびに実行される C# 関数を示します。 たとえば、関数が 18:55:00 に開始された場合、次の実行は 19:00:00 になります。 TimerInfo オブジェクトが関数に渡されます。

A C# 関数は、次の C# モードのいずれかを使用して作成できます。

  •     インプロセス クラス ライブラリ: Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数。
  •     分離プロセス クラス ライブラリ: そのランタイムから分離されたプロセスで実行されるコンパイル済みの C# 関数。 .NET 5.0 で実行されている C# 関数をサポートするには、分離プロセスが必要です。
  • C# スクリプト: Azure portal で c# 関数を作成するときに主に使用されます。
[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}");
}

次の例の関数は、5 分ごとにトリガーして実行します。 関数の @TimerTrigger 注釈では、@TimerTriggerと同じ文字列形式を使用してスケジュールが定義されています。

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

次の例では、function.json ファイルのタイマー トリガー バインドと、バインドを使用する関数コードを示します。関数にはタイマーを表すインスタンスが渡されます。 この関数では、この関数呼び出しがスケジュールのミスの発生によるものかどうかを示すログが書き込まれます。

function.json ファイルのバインディング データを次に示します。

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

JavaScript コードを次に示します。

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

次に示すのは、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"

次に示す Python コードで関数に渡されるオブジェクトの型は、azure.functions.TimerRequest オブジェクトです。

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)

属性

インプロセス分離プロセスの C# ライブラリはどちらも、TimerTriggerAttribute 属性を使って関数を定義します。

代わりに、C# スクリプトでは、function.json 構成ファイルを使用します。

属性のプロパティ 説明
[スケジュール] CRON 式または TimeSpan 値。 TimeSpan は、App Service プランで実行している関数アプリに対してのみ使うことができます。 スケジュール式をアプリの設定に含めて、% 記号で囲まれたアプリ設定名にこのプロパティを設定できます (例: %ScheduleAppSetting%)。
runOnStartup true の場合、関数はランタイムの開始時に呼び出されます。 たとえば、ランタイムが開始するのは、関数アプリが非アクティブになってアイドル状態に移行した後で起動したとき、 関数が変化したために関数アプリが再起動するとき、関数アプリがスケールアウトするときなどです。"使うときは注意してください"。runOnStartuptrue に設定する必要があるとしても、(運用環境では特に) まれなことです。
UseMonitor true または false に設定し、スケジュールを監視する必要があるかどうかを示します。 スケジュールの監視はスケジュールの発生を維持し、関数アプリのインスタンスが再起動するときでもスケジュールが正しく維持されることを保証するのに役立ちます。 このプロパティを明示的に設定しない場合、繰り返し間隔が 1 分以上のスケジュールの既定値は true です。 1 分間に 2 回以上トリガーするスケジュールの既定値は false です。

注釈

関数の @TimerTrigger 注釈では、CRON 式と同じ文字列形式を使って schedule が定義されています。 この注釈では、次の設定がサポートされます。

構成

次の表は、function.json ファイルで設定したバインド構成のプロパティを説明しています。

function.json のプロパティ 説明
type "timerTrigger" に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
direction "in" に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
name 関数コード内のタイマー オブジェクトを表す変数の名前。
schedule CRON 式または TimeSpan 値。 TimeSpan は、App Service プランで実行している関数アプリに対してのみ使うことができます。 スケジュール式をアプリ設定に含めて、たとえば "%ScheduleAppSetting%" のように、 % 記号で囲まれたアプリ設定名にこのプロパティを設定できます。
runOnStartup true の場合、関数はランタイムの開始時に呼び出されます。 たとえば、ランタイムが開始するのは、関数アプリが非アクティブになってアイドル状態に移行した後で起動したとき、 関数が変化したために関数アプリが再起動するとき、関数アプリがスケールアウトするときなどです。"使うときは注意してください"。runOnStartuptrue に設定する必要があるとしても、(運用環境では特に) まれなことです。
useMonitor true または false に設定し、スケジュールを監視する必要があるかどうかを示します。 スケジュールの監視はスケジュールの発生を維持し、関数アプリのインスタンスが再起動するときでもスケジュールが正しく維持されることを保証するのに役立ちます。 このプロパティを明示的に設定しない場合、繰り返し間隔が 1 分以上のスケジュールの既定値は true です。 1 分間に 2 回以上トリガーするスケジュールの既定値は false です。

ローカルで開発する場合は、 コレクション内の local.settings.json ファイルにアプリケーション設定を追加します。

注意事項

運用環境では、runOnStartuptrue に設定しないでください。 この設定を使用すると、まったく予期できないときにコードが実行されます。 特定の運用環境の設定では、これらの追加の実行によって、従量課金プランでホストされるアプリのコストが大幅に高くなる可能性があります。 たとえば、runOnStartup を有効にすると、ご利用の関数アプリがスケーリングされるたびに、トリガーが呼び出されます。 runOnStartup を運用環境で有効にする前に、ご利用の関数の運用環境での動作を完全に理解していることを確認してください。

完全な例については、セクションの例を参照してください。

使用法

タイマー トリガー関数が呼び出されると、タイマー オブジェクトが関数に渡されます。 次の JSON は、タイマー オブジェクトの 1 つの表現例です。

{
    "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 Functions では、NCRONTAB 式を解釈するのに NCronTab ライブラリが使用されます。 NCRONTAB 式は CRON 式に似ていますが、秒単位の時間精度に使用するために、追加の 6 番目のフィールドが最初に含まれている点が異なります。

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

各フィールドは、次の種類の値のいずれかを持つことができます。

Type トリガーのタイミング
特定の値 0 5 * * * * 1 時間ごとに 1 回、1 日の毎時 5 分
すべての値 (*) 0 * 5 * * * 5 時から始まる 1 時間で 1 分ごと
範囲 (- 演算子) 5-7 * * * * * 1 分間に 3 回 - 各日、各時間、毎分 5 秒から 7 秒
値のセット (, 演算子) 5,8,10 * * * * * 1 分間に 3 回 - 各日、各時間、毎分 5 秒、8 秒、10 秒
間隔値 (/ 演算子) 0 */5 * * * * 1 時間に 12 回 - 各日、毎時 5 分 0 秒

月や曜日を指定するには、数値、名前、または名前の省略形を使用できます。

  • 曜日については、数値は 0 から 6 で指定します (0 は日曜日です)。
  • 名前は英語で指定します。 例: Monday, January
  • 名前の大文字と小文字は区別されません。
  • 名前は省略形でも指定できます。 省略形は 3 文字にすることをお勧めします。 例: Mon, Jan

NCRONTAB の例

Azure Functions のタイマー トリガーに使用できる NCRONTAB 式の例をいくつか示します。

トリガーのタイミング
0 */5 * * * * 5 分ごとに 1 回
0 0 * * * * 毎正時に 1 回
0 0 */2 * * * 2 時間に 1 回
0 0 9-17 * * * 午前 9 時から午後 5 時ま、1 時間に 1 回
0 30 9 * * * 毎日午前 9 時 30 分
0 30 9 * * 1-5 平日の毎日午前 9 時 30 分
0 30 9 * Jan Mon 1 月の毎週月曜日の午前 9時 30分

Note

NCRONTAB 式は、5 フィールド6 フィールドの両方の形式をサポートしています。 6 番目のフィールド位置は、式の先頭に配置される秒の値です。

NCRONTAB タイム ゾーン

CRON 式に出現する値は、時間間隔ではなく時刻と日付を示します。 たとえば、hour フィールドの 5 は、5 時間ごとではなく、午前 5 時 00 分を示します。

CRON 式で使用する既定のタイム ゾーンは、協定世界時 (UTC) です。 別のタイム ゾーンに基づく CRON 式を使うには、Function App 用に WEBSITE_TIME_ZONE という名前のアプリ設定を作成します。

この設定の値は、関数アプリを実行するオペレーティング システムとプランによって異なります。

オペレーティング システム プラン
Windows All Windows コマンド tzutil.exe /L によって指定された各ペアの 2 行目に指定されているように、この値を目的のタイム ゾーンの名前に設定します。
Linux Premium
専用
この値を、tz データベースに関するページに示されている目的のタイム ゾーンの名前に設定します。

Note

Linux 従量課金プランでは、現在 WEBSITE_TIME_ZONE はサポートされていません。

たとえば、米国の東部標準時 (Eastern Standard Time (Windows) または America/New_York (Linux)) では現在、標準時では UTC-05:00、夏時間では UTC-04:00 を使用します。 タイマー トリガーが毎日東部標準時の午前 10 時に発生するように設定するには、関数アプリのアプリ設定を WEBSITE_TIME_ZONE という名前で作成し、その値を Eastern Standard Time (Windows) または America/New_York (Linux) に設定して、次の NCRONTAB 式を使用します。

"0 0 10 * * *"

WEBSITE_TIME_ZONE を使用すると、夏時間などの特定のタイムゾーンでの時間変更や標準時での変更に対応するように、時刻が調整されます。

TimeSpan

TimeSpan は、App Service プランで実行している関数アプリに対してのみ使うことができます。

CRON 式とは異なり、TimeSpan の値は各関数呼び出しの間の時間間隔を指定します。 指定された間隔より長く実行した後で関数が完了すると、タイマーすぐに関数を再び呼び出します。

TimeSpan は文字列として表され、hh が 24 未満のときの形式は hh:mm:ss です。 最初の 2 つの数字が 24 以上のときの形式は dd:hh:mm です。 次に例をいくつか示します。

トリガーのタイミング
"01:00:00" 1 時間ごと
"00:01:00" 1 分ごと
"25:00:00:00" 25 日ごと
"1.00:00:00" 毎日

スケールアウト

関数アプリが複数のインスタンスにスケールアウトする場合は、タイマーによってトリガーされる関数の 1 つのインスタンスだけがすべてのインスタンスで実行されます。 未処理の呼び出しがまだ実行中の場合は、再度トリガーされません。

ストレージを共有する関数アプリ

App Service にデプロイされていない関数アプリの間でストレージ アカウントを共有している場合は、ホスト ID を各アプリに明示的に割り当てることが必要な場合があります。

Functions バージョン 設定
2.x (以上) AzureFunctionsWebHost__hostid 環境変数
1.x id での id

識別値を省略するか、各関数アプリの識別構成に異なる値を手動で設定することができます。

1 つの関数アプリが複数のインスタンスにスケールアウトされる場合、タイマー インスタンスが 1 しか存在しないようにするために、タイマー トリガーではストレージ ロックが使用されます。 2 つの関数アプリで同じ識別構成が共有されていて、それぞれでタイマー トリガーが使用されている場合は、1 つのタイマーのみが実行されます。

再試行の動作

キュー トリガーとは異なり、タイマー トリガーは関数が失敗した後で再試行しません。 失敗した関数は、次のスケジュール時刻まで再び呼び出されることはありません。

タイマー トリガーを手動で呼び出す

Azure Functions のタイマー トリガーには、手動で関数をトリガーするために呼び出すことができる HTTP Webhook が用意されています。 これは、次のようなシナリオで非常に役立ちます。

  • 統合テスト
  • スモーク テストまたはウォームアップ アクティビティの一部としてのスロット スワップ
  • データベース内のキャッシュまたはルックアップ テーブルに直ちにデータを入力する関数の初期デプロイ

タイマーによってトリガーされる関数を手動で呼び出す方法の詳細については、HTTP によってトリガーされない関数を手動で実行する方法に関するページを参照してください。

トラブルシューティング

タイマー トリガーが期待どおりに機能しない場合の対処方法については、タイマー トリガーが設定された関数が発生しない問題の調査と報告に関するページを参照してください。

次のステップ