共用方式為


建立依排程執行管線的觸發程序

適用於:Azure Data Factory Azure Synapse Analytics

提示

試用 Microsoft Fabric 中的 Data Factory,這是適用於企業的全方位分析解決方案。 Microsoft Fabric 涵蓋從資料移動到資料科學、即時分析、商業智慧和報告的所有項目。 了解如何免費開始新的試用

本文提供有關排程觸發程序的資訊,以及建立、啟動和監視排程觸發程序的步驟。 如需了解其他類型的觸發程序,請參閱管線執行和觸發程序

建立排程觸發程序時,您需為觸發程序指定排程,例如開始日期、週期、結束日期等,然後與管線建立關聯。 管道和觸發程序具有多對多關聯性。 多個觸發程序可以啟動單一管道。 單一觸發程序可以啟動多個管道。

下列各節提供以各種不同方式建立排程觸發程序的步驟。

Azure Data Factory 和 Azure Synapse 入口網站體驗

您可以建立排程觸發程序,將管線排定為定期執行,例如每小時、每天。

注意

如需有關建立管線和排程觸發程序的完整逐步解說,其中將觸發程序與管線建立關聯,並執行和監視管線,請參閱快速入門:使用 Data Factory UI 來建立資料處理站

  1. 切換至 Data Factory 中的 [編輯] 索引標籤,或 Azure Synapse Analytics 中的 [整合] 索引標籤。


  1. 選取功能表上的 [觸發程序],然後選取 [新增/編輯]

    顯示新觸發程序選單的螢幕擷取畫面。

  2. 在 [新增觸發程序] 頁面上,選取 [選擇觸發程序],然後選取 [新增]

    螢幕擷取畫面,其中顯示新增觸發程序窗格。

  3. 在 [新的觸發程序] 頁面上:

    1. 確認已針對 [類型] 選取 [排程]

    2. 在 [開始日期] 中,指定觸發程序的開始日期時間。 預設為目前的日期時間,以國際標準時間 (UTC) 表示。

    3. 指定建立觸發程序的時區。 時區設定套用至 [進階週期選項] 中的 [開始日期]、[結束日期] 和 [排程執行時間]。 變更時區設定不會自動變更開始日期。 請確定開始日期在指定的時區中正確。 觸發程序的排程運行時間會被視為在開始日期後。 (確定開始日期至少比運行時間少 1 分鐘,否則會在下一次週期中觸發管線。)

      注意

      在遵守日光節約的時區,如果週期設定為或更長,則會考量一年兩次的變更,自動調整觸發時間。 若不採用日光節約變更,選取未遵守日光節約的時區,例如 UTC。

      日光節約調整僅適用於週期設定為或更長的觸發程序。 如果觸發程序設定為小時分鐘頻率,則會繼續定期引發。

    4. 指定觸發程序的 [週期]。 請從下拉式清單 (每分鐘每小時每天每週每月) 中選取其中一個值。 在文字方塊中輸入乘數。 例如,如果您想要讓觸發程序每隔 15 分鐘執行一次,您可以選取 [每分鐘],然後在文字方塊中輸入 15

    5. 在 [週期] 中,如果您從下拉式清單中選擇,您可以找到 [進階週期選項]

      顯示日期、週和月進階週期選項的螢幕擷取畫面。

    6. 若要指定結束日期時間,請選取 [指定結束日期]。 指定結束資訊,然後選取 [確定]

      每次執行管線都會產生關聯成本。 如果您是在進行測試,您或許會想要確保只觸發管線幾次。 不過,請確定發佈時間與結束時間之間有足夠的時間可供管線執行。 只有在發佈解決方案之後,觸發程序才會生效,而不是在 UI 中儲存觸發程序時。

      顯示觸發程序設定的螢幕擷取畫面。

      顯示結束日期和時間之觸發程序設定的螢幕擷取畫面。

  4. 在 [新增觸發程序] 視窗中,在 [進階] 選項中選取 [是],並選取 [確定]。 您可以稍後使用此核取方塊來停用觸發程序。

    顯示啟用選項的螢幕擷取畫面。

  5. 在 [新增觸發程序] 視窗中,檢閱警告訊息,並選取 [確定]

    顯示選取 [OK] 按鈕的螢幕擷取畫面。

  6. 按一下 [全部發佈] 以發佈變更。 直到發佈變更,觸發程序才會開始觸發管線執行。

    顯示 [全部發佈] 按鈕的螢幕擷取畫面。

  7. 切換至左側的 [管線執行] 索引標籤,並選取 [重新整理] 以重新整理清單。 您會看到所排定之觸發程序所觸發的管線回合。 請留意 [觸發方式] 資料行中的值。 如果您使用 [立即觸發] 選項,就會在清單中看到手動觸發程序回合。


  1. 切換至 [觸發程序執行]>[排程] 檢視。


Azure PowerShell

注意

建議您使用 Azure Az PowerShell 模組來與 Azure 互動。 若要開始使用,請參閱安裝 Azure PowerShell (部分機器翻譯)。 若要了解如何移轉至 Az PowerShell 模組,請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az

本節說明如何使用 Azure PowerShell 來建立、啟動及監視排程觸發程序。 若要查看此範例如何運作,請先完成快速入門:使用 Azure PowerShell 來建立資料處理站。 然後,將下列程式碼新增至 main 方法中,以建立並啟動一個每隔 15 分鐘執行一次的排程觸發程序。 此觸發程序會與您在快速入門中所建立之名為 Adfv2QuickStartPipeline 的管線關聯。

必要條件

範例指令碼

  1. 在 *C:\ADFv2QuickStartPSH* 資料夾中,使用下列內容建立名為 MyTrigger.json 的 JSON 檔案:

    重要

    在您儲存 JSON 檔案之前,請先將 startTime 元素的值設定為目前的 UTC 時間。 將 endTime 元素的值設定為目前 UTC 時間的一小時之後。

    {
        "properties": {
            "name": "MyTrigger",
            "type": "ScheduleTrigger",
            "typeProperties": {
                "recurrence": {
                    "frequency": "Minute",
                    "interval": 15,
                    "startTime": "2017-12-08T00:00:00Z",
                    "endTime": "2017-12-08T01:00:00Z",
                    "timeZone": "UTC"
                }
            },
            "pipelines": [{
                    "pipelineReference": {
                        "type": "PipelineReference",
                        "referenceName": "Adfv2QuickStartPipeline"
                    },
                    "parameters": {
                        "inputPath": "adftutorial/input",
                        "outputPath": "adftutorial/output"
                    }
                }
            ]
        }
    }
    

    在 JSON 程式碼片段中:

    • 觸發程序的 type 元素會設定為 ScheduleTrigger

    • frequency 元素會設定為 Minute,而 interval 元素會設定為 15。 因此,觸發程序在開始與結束時間之間,每 15 分鐘執行一次管線。

    • timeZone 元素指定建立觸發程序的時區。 這個設定會影響 startTimeendTime

    • endTime 元素是在 startTime 元素值的一小時之後。 因此,觸發程序在開始時間之後的 15 分鐘、30 分鐘及 45 分鐘執行管線。 請別忘記將開始時間更新為目前的 UTC 時間,並將結束時間更新為開始時間的一小時之後。

      重要

      針對UTC時區,startTimeendTime 必須遵循 yyyy-MM-ddTHH:mm:ssZ 格式。對於其他時區,startTimeendTime 遵循 yyyy-MM-ddTHH:mm:ss 格式。

      根據 ISO 8601 標準,時間戳記的 Z 尾碼將日期時間標示為 UTC 時區,使 timeZone 欄位變得無用。 UTC 時區遺漏 Z 尾碼時,將導致觸發程序啟用時發生錯誤。

    • 觸發程序與 Adfv2QuickStartPipeline 管線相關聯。 若要將多個管線與觸發程序建立關聯,請新增更多個 pipelineReference 區段。

    • 快速入門中的管線會採用兩個 parameters 值:inputPathoutputPath。 您從觸發程序傳遞這些參數的值。

  2. 使用 Set-AzDataFactoryV2Trigger Cmdlet 建立觸發程序:

    Set-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger" -DefinitionFile "C:\ADFv2QuickStartPSH\MyTrigger.json"
    
  3. 使用 Get-AzDataFactoryV2Trigger Cmdlet,確認觸發程序的狀態為 Stopped

    Get-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"
    
  4. 使用 Start-AzDataFactoryV2Trigger Cmdlet 啟動觸發程序:

    Start-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"
    
  5. 使用 Get-AzDataFactoryV2Trigger Cmdlet,確認觸發程序的狀態為 Started

    Get-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"
    
  6. 使用 Get-AzDataFactoryV2TriggerRun Cmdlet,取得 Azure PowerShell 中的觸發程序執行。 若要取得有關觸發程序回合的資訊,請定期執行以下命令。 更新 TriggerRunStartedAfterTriggerRunStartedBefore 值,以符合觸發程序定義中的值:

    Get-AzDataFactoryV2TriggerRun -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -TriggerName "MyTrigger" -TriggerRunStartedAfter "2017-12-08T00:00:00" -TriggerRunStartedBefore "2017-12-08T01:00:00"
    

    注意

    排程觸發程序的觸發時間以 UTC 時間戳記指定。 TriggerRunStartedAfterTriggerRunStartedBefore 也預期 UTC時間戳記。

    若要在 Azure 入口網站中監視觸發程序回合和管線回合,請參閱監視管線回合

Azure CLI

本節說明如何使用 Azure CLI 來建立、啟動及監視排程觸發程序。 若想看到此範例實際運作,請先完成快速入門:透過使用 Azure CLI 來建立 Azure Data Factory。 然後,遵循步驟來建立並啟動排程觸發程序,每 15 分鐘執行一次。 此觸發程序會與您在快速入門中所建立之名為 Adfv2QuickStartPipeline 的管線關聯。

必要條件

範例指令碼

  1. 在工作目錄中,使用觸發程式的屬性建立名為 MyTrigger.json 的 JSON 檔案。 針對此範例,請使用下列內容:

    重要

    在您儲存 JSON 檔案之前,請先將 startTime 元素的值設定為目前的 UTC 時間。 將 endTime 元素的值設定為目前 UTC 時間的一小時之後。

    {
        "name": "MyTrigger",
        "type": "ScheduleTrigger",
        "typeProperties": {
            "recurrence": {
                "frequency": "Minute",
                "interval": 15,
                "startTime": "2017-12-08T00:00:00Z",
                "endTime": "2017-12-08T01:00:00Z",
                "timeZone": "UTC"
            }
        },
        "pipelines": [{
                "pipelineReference": {
                    "type": "PipelineReference",
                    "referenceName": "Adfv2QuickStartPipeline"
                },
                "parameters": {
                    "inputPath": "adftutorial/input",
                    "outputPath": "adftutorial/output"
                }
            }
        ]
    }
    

    在 JSON 程式碼片段中:

    • 觸發程序的 type 元素會設定為 ScheduleTrigger

    • frequency 元素會設定為 Minute,而 interval 元素會設定為 15。 因此,觸發程序在開始與結束時間之間,每 15 分鐘執行一次管線。

    • timeZone 元素指定建立觸發程序的時區。 這個設定會影響 startTimeendTime

    • endTime 元素是在 startTime 元素值的一小時之後。 因此,觸發程序在開始時間之後的 15 分鐘、30 分鐘及 45 分鐘執行管線。 請別忘記將開始時間更新為目前的 UTC 時間,並將結束時間更新為開始時間的一小時之後。

      重要

      針對UTC時區,startTime 和 endTime 必須遵循 yyyy-MM-ddTHH:mm:ssZ 格式。對於其他時區,startTimeendTime 遵循 yyyy-MM-ddTHH:mm:ss 格式。

      根據 ISO 8601 標準,時間戳記的 Z 尾碼將日期時間標示為 UTC 時區,使 timeZone 欄位變得無用。 如果 UTC 時區遺漏 Z 後綴,則觸發程序啟用時,結果是錯誤。

    • 觸發程序與 Adfv2QuickStartPipeline 管線相關聯。 若要將多個管線與觸發程序建立關聯,請新增更多個 pipelineReference 區段。

    • 快速入門中的管線會採用兩個 parameters 值:inputPathoutputPath。 您從觸發程序傳遞這些參數的值。

  2. 使用 az datafactory trigger create 命令建立觸發程序:

    az datafactory trigger create --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory"  --name "MyTrigger" --properties @MyTrigger.json  
    
  3. 使用 az datafactory trigger show 命令,確認觸發程序的狀態為 Stopped

    az datafactory trigger show --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger" 
    
  4. 使用 az datafactory trigger start 命令啟動觸發程序:

    az datafactory trigger start --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger" 
    
  5. 使用 az datafactory trigger show 命令,確認觸發程序的狀態為 Started

    az datafactory trigger show --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger" 
    
  6. 使用 az datafactory trigger-run query-by-factory 命令,取得 Azure CLI 中的觸發程序執行。 若要取得有關觸發程序執行的資訊,請定期執行以下命令。 更新 last-updated-afterlast-updated-before 值,以符合觸發程序定義中的值:

    az datafactory trigger-run query-by-factory --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --filters operand="TriggerName" operator="Equals" values="MyTrigger" --last-updated-after "2017-12-08T00:00:00" --last-updated-before "2017-12-08T01:00:00"
    

    注意

    排程觸發程序的觸發時間以 UTC 時間戳記指定。 last-updated-afterlast-updated-before 也需要 UTC 時間戳記。

    若要在 Azure 入口網站中監視觸發程序回合和管線回合,請參閱監視管線回合

.NET SDK

本節說明如何使用 .NET SDK 來建立、啟動及監視觸發程序。 若要查看此範例如何運作,請先完成快速入門:使用 .NET SDK 來建立資料處理站。 然後,將下列程式碼新增至 main 方法中,以建立並啟動一個每隔 15 分鐘執行一次的排程觸發程序。 此觸發程序會與您在快速入門中所建立之名為 Adfv2QuickStartPipeline 的管線關聯。

若要建立並啟動一個每隔 15 分鐘執行一次的排程觸發程序,請將下列程式碼新增至 main 方法中:

            // Create the trigger
            Console.WriteLine("Creating the trigger");

            // Set the start time to the current UTC time
            DateTime startTime = DateTime.UtcNow;

            // Specify values for the inputPath and outputPath parameters
            Dictionary<string, object> pipelineParameters = new Dictionary<string, object>();
            pipelineParameters.Add("inputPath", "adftutorial/input");
            pipelineParameters.Add("outputPath", "adftutorial/output");

            // Create a schedule trigger
            string triggerName = "MyTrigger";
            ScheduleTrigger myTrigger = new ScheduleTrigger()
            {
                Pipelines = new List<TriggerPipelineReference>()
                {
                    // Associate the Adfv2QuickStartPipeline pipeline with the trigger
                    new TriggerPipelineReference()
                    {
                        PipelineReference = new PipelineReference(pipelineName),
                        Parameters = pipelineParameters,
                    }
                },
                Recurrence = new ScheduleTriggerRecurrence()
                {
                    // Set the start time to the current UTC time and the end time to one hour after the start time
                    StartTime = startTime,
                    TimeZone = "UTC",
                    EndTime = startTime.AddHours(1),
                    Frequency = RecurrenceFrequency.Minute,
                    Interval = 15,
                }
            };

            // Now, create the trigger by invoking the CreateOrUpdate method
            TriggerResource triggerResource = new TriggerResource()
            {
                Properties = myTrigger
            };
            client.Triggers.CreateOrUpdate(resourceGroup, dataFactoryName, triggerName, triggerResource);

            // Start the trigger
            Console.WriteLine("Starting the trigger");
            client.Triggers.Start(resourceGroup, dataFactoryName, triggerName);

若要在 UTC 以外的時區建立觸發程序,需要下列設定:

<<ClientInstance>>.SerializationSettings.DateFormatHandling = Newtonsoft.Json.DateFormatHandling.IsoDateFormat;
<<ClientInstance>>.SerializationSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Unspecified;
<<ClientInstance>>.SerializationSettings.DateParseHandling = DateParseHandling.None;
<<ClientInstance>>.DeserializationSettings.DateParseHandling = DateParseHandling.None;
<<ClientInstance>>.DeserializationSettings.DateFormatHandling = Newtonsoft.Json.DateFormatHandling.IsoDateFormat;
<<ClientInstance>>.DeserializationSettings.DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Unspecified;

若要監視觸發程序回合,請將下列程式碼新增至範例中的最後一個 Console.WriteLine 陳述式之前:

            // Check that the trigger runs every 15 minutes
            Console.WriteLine("Trigger runs. You see the output every 15 minutes");

            for (int i = 0; i < 3; i++)
            {
                System.Threading.Thread.Sleep(TimeSpan.FromMinutes(15));
                List<TriggerRun> triggerRuns = client.Triggers.ListRuns(resourceGroup, dataFactoryName, triggerName, DateTime.UtcNow.AddMinutes(-15 * (i + 1)), DateTime.UtcNow.AddMinutes(2)).ToList();
                Console.WriteLine("{0} trigger runs found", triggerRuns.Count);

                foreach (TriggerRun run in triggerRuns)
                {
                    foreach (KeyValuePair<string, string> triggeredPipeline in run.TriggeredPipelines)
                    {
                        PipelineRun triggeredPipelineRun = client.PipelineRuns.Get(resourceGroup, dataFactoryName, triggeredPipeline.Value);
                        Console.WriteLine("Pipeline run ID: {0}, Status: {1}", triggeredPipelineRun.RunId, triggeredPipelineRun.Status);
                        List<ActivityRun> runs = client.ActivityRuns.ListByPipelineRun(resourceGroup, dataFactoryName, triggeredPipelineRun.RunId, run.TriggerRunTimestamp.Value, run.TriggerRunTimestamp.Value.AddMinutes(20)).ToList();
                    }
                }
            }

若要在 Azure 入口網站中監視觸發程序回合和管線回合,請參閱監視管線回合

Python SDK

本節說明如何使用 Python SDK 來建立、啟動及監視觸發程序。 若要查看此範例運作,請先完成 快速入門:使用 Python SDK 建立資料處理站。 然後,將下列程式碼新增至 Python 指令碼中的 monitor the pipeline run 程式碼區塊之後。 此程式碼會建立一個在指定的開始和結束時間之間,每隔 15 分鐘執行一次的排程觸發程序。 請將 start_time 變數更新為目前的 UTC 時間,並將 end_time 變數更新為目前 UTC 時間的一小時之後。

    # Create a trigger
    tr_name = 'mytrigger'
    scheduler_recurrence = ScheduleTriggerRecurrence(frequency='Minute', interval='15',start_time='2017-12-12T04:00:00Z', end_time='2017-12-12T05:00:00Z', time_zone='UTC')
    pipeline_parameters = {'inputPath':'adftutorial/input', 'outputPath':'adftutorial/output'}
    pipelines_to_run = []
    pipeline_reference = PipelineReference('copyPipeline')
    pipelines_to_run.append(TriggerPipelineReference(pipeline_reference, pipeline_parameters))
    tr_properties = TriggerResource(properties=ScheduleTrigger(description='My scheduler trigger', pipelines = pipelines_to_run, recurrence=scheduler_recurrence))
    adf_client.triggers.create_or_update(rg_name, df_name, tr_name, tr_properties)

    # Start the trigger
    adf_client.triggers.start(rg_name, df_name, tr_name)

若要在 Azure 入口網站中監視觸發程序回合和管線回合,請參閱監視管線回合

Azure Resource Manager 範本

您可以使用 Azure Resource Manager 範本來建立觸發程序。 如需逐步指示,請參閱使用 Azure Resource Manager 範本建立 Azure Data Factory

將觸發程序開始時間傳遞給管線

第 1 版 Azure Data Factory 支援使用下列系統變數 SliceStartSliceEndWindowStartWindowEnd 來讀取或寫入分割的資料。 在目前版本的 Data Factory 和 Azure Synapse 管線中,您可以使用管線參數來實現此行為。 觸發程序的開始時間和排程時間會設定為管線參數的值。 在以下範例中,會將觸發程序的排程時間傳遞給管線的 scheduledRunTime 參數來作為值:

"parameters": {
    "scheduledRunTime": "@trigger().scheduledTime"
}

JSON 結構描述

下列 JSON 定義將說明如何使用排程和週期來建立排程觸發程序:

{
  "properties": {
    "type": "ScheduleTrigger",
    "typeProperties": {
      "recurrence": {
        "frequency": <<Minute, Hour, Day, Week, Month>>,
        "interval": <<int>>,             // Optional, specifies how often to fire (default to 1)
        "startTime": <<datetime>>,
        "endTime": <<datetime - optional>>,
        "timeZone": "UTC"
        "schedule": {                    // Optional (advanced scheduling specifics)
          "hours": [<<0-23>>],
          "weekDays": [<<Monday-Sunday>>],
          "minutes": [<<0-59>>],
          "monthDays": [<<1-31>>],
          "monthlyOccurrences": [
               {
                    "day": <<Monday-Sunday>>,
                    "occurrence": <<1-5>>
               }
           ]
        }
      }
    },
   "pipelines": [
            {
                "pipelineReference": {
                    "type": "PipelineReference",
                    "referenceName": "<Name of your pipeline>"
                },
                "parameters": {
                    "<parameter 1 Name>": {
                        "type": "Expression",
                        "value": "<parameter 1 Value>"
                    },
                    "<parameter 2 Name>" : "<parameter 2 Value>"
                }
           }
      ]
  }
}

重要

parameters 屬性是 pipelines 元素的必要屬性。 如果您的管線未採用任何參數,您就必須為 parameters 屬性加入一個空的 JSON 定義。

結構描述概觀

下表提供與觸發程序之週期和排程相關的主要結構描述元素概觀。

JSON 屬性 描述
startTime 日期時間值。 在簡易排程中,startTime 屬性的值會套用至第一個發生項目。 在複雜的排程中,觸發程序會在到了指定的 startTime 值才啟動。
針對 UTC 時區,格式為 'yyyy-MM-ddTHH:mm:ssZ'。 針對其他時區,格式為 yyyy-MM-ddTHH:mm:ss
endTime 觸發程序的結束日期和時間。 觸發程序在指定的結束日期和時間之後便不再執行。 此屬性的值不可以是過去的時間。 這個屬性為選擇性。
針對 UTC 時區,格式為 'yyyy-MM-ddTHH:mm:ssZ'。 針對其他時區,格式為 yyyy-MM-ddTHH:mm:ss
timeZone 建立觸發程序的時區。 這個設定會影響 startTimeendTimeschedule。 請參閱支援的時區清單
recurrence 指定觸發程序之週期規則的 recurrence 物件。 迴圈物件支援 frequencyintervalendTimecountschedule 元素。 定義 recurrence 物件時,必須一併定義 frequency 元素。 其他 recurrence 物件元素則為選用元素。
frequency 觸發程序重複執行時的頻率單位。 支援的值包括:minute,hour,dayweekmonth
interval 代表 frequency 值之間隔的整數值,用來決定觸發程序執行的頻率。 例如,如果 interval3,且 frequencyweek,則觸發程序會每隔 3 周遞歸一次。
schedule 觸發程序的週期排程。 具有指定之 frequency 值的觸發程序會根據週期排程來改變其週期。 schedule 屬性會根據分鐘、小時、星期幾、月日及週數來修改週期。

重要

針對UTC時區,startTimeendTime 必須遵循 yyyy-MM-ddTHH:mm:ssZ 格式。對於其他時區,startTimeendTime 遵循 yyyy-MM-ddTHH:mm:ss 格式。

根據 ISO 8601 標準,時間戳記的 Z 尾碼將日期時間標示為 UTC 時區,使 timeZone 欄位變得無用。 如果 UTC 時區遺漏 Z 後綴,則觸發程序啟用時,結果是錯誤。

結構描述預設值、限制及範例

JSON 屬性 類型 必要 預設值 有效值 範例
startTime String Yes ISO 8601 日期時間 針對 UTC 時區:"startTime" : "2013-01-09T09:30:00-08:00Z"
針對其他時區:"2013-01-09T09:30:00-08:00"
timeZone String Yes 時區值 "UTC"
recurrence Object Yes Recurrence 物件 "recurrence" : { "frequency" : "monthly", "interval" : 1 }
interval 數字 No 1 1 到 1,000 "interval":10
endTime String Yes 代表未來時間的日期時間值 針對 UTC 時區:"endTime" : "2013-02-09T09:30:00-08:00Z"
針對其他時區:"endTime" : "2013-02-09T09:30:00-08:00"
schedule Object No Schedule 物件 "schedule" : { "minute" : [30], "hour" : [8,17] }

時區選項

以下是排程觸發程序支援的一些時區。

Time zone UTC 時差 (非日光節約) timeZone 值 遵守日光節約 時間戳記格式
國際標準時間 0 UTC No 'yyyy-MM-ddTHH:mm:ssZ'
太平洋時間 (PT) -8 Pacific Standard Time Yes 'yyyy-MM-ddTHH:mm:ss'
中部時間 (CT) -6 Central Standard Time Yes 'yyyy-MM-ddTHH:mm:ss'
東部時間 (ET) 5- Eastern Standard Time Yes 'yyyy-MM-ddTHH:mm:ss'
格林威治標準時間 (GMT) 0 GMT Standard Time Yes 'yyyy-MM-ddTHH:mm:ss'
歐洲中部標準時間 1+ W. Europe Standard Time Yes 'yyyy-MM-ddTHH:mm:ss'
印度標準時間 (IST) +5:30 India Standard Time No 'yyyy-MM-ddTHH:mm:ss'
中國標準時間 +8 China Standard Time No 'yyyy-MM-ddTHH:mm:ss'

這不是完整清單。 如需時區選項的完整清單,請參閱入口網站的觸發程序建立頁面

startTime 屬性

下表說明 startTime 屬性如何控制觸發程序執行。

startTime 值 週期性無排程 週期性有排程
開始時間已過去 計算開始時間之後的第一個未來執行時間,並在該時間執行。

根據從上次執行時間算出的時間來執行後續的執行作業。

請參閱本表後面的範例。
觸發程序會在「到了」指定的開始時間才啟動。 第一次執行是根據從開始時間算出的排程。

根據週期排程執行後續的執行作業。
開始時間在未來或現在 在指定的開始時間執行一次。

根據從上次執行時間算出的時間來執行後續的執行作業。
觸發程序會在「到了」指定的開始時間才啟動。 第一次執行是根據從開始時間算出的排程。

根據週期排程執行後續的執行作業。

我們來看看一個範例:當開始時間在過去、具有週期性但無排程時,會發生什麼情況。 假設目前時間是 2017-04-08 13:00,開始時間是 2017-04-07 14:00,而週期是每隔兩天。 (recurrence 值是藉由將 frequency 屬性設定為 day,並將 interval 屬性設定為 2來定義。)請注意,startTime 值是過去的時間,發生在目前時間之前。

根據這些條件,第一次執行在 2017-04-09 14:00。 排程器引擎會從開始時間計算執行週期。 過去的任何執行個體都會遭到捨棄。 引擎會使用下一個在未來發生的執行個體。 在此案例中,開始時間是 2017-04-07 2:00pm,因此下一個執行個體在該時間之後的兩天,亦即 2017-04-09 2:00pm

即使 startTime 值為 2017-04-05 14:002017-04-01 14:00,第一次執行時間仍然相同。 在第一次執行之後,就會使用排程來算出後續的執行時間。 因此,後續的執行在 2017-04-11 2:00pm2017-04-13 2:00pm2017-04-15 2:00pm,依此類推。

最後,當未在觸發程序的排程中設定小時或分鐘時,將會使用第一次執行的小時或分鐘作為預設值。

schedule 屬性

使用排程可以限制觸發程序的執行次數。 例如,如果將每月執行的觸發程序排定為只在 31 日執行,則該觸發程序將只會在有第 31 天的月份執行。

排程也可以增加觸發程序的執行次數。 例如,如果將每月執行的觸發程序排定在月份的 1 日和 2 日執行,該觸發程序就會在月份的第 1 天和第 2 天執行,而不是一個月執行一次。

指定多個 schedule 元素時,評估順序會從最大到最小排程設定。 評估會從週數開始,然後依序是月日、星期幾、小時,最後是分鐘。

下表詳細說明 schedule 元素。

JSON 元素 描述 有效值
minutes 一小時內觸發程序執行的分鐘數。
  • 整數
  • 一連串整數
hours 一天內觸發程序執行的小時數。
  • 整數
  • 一連串整數
weekDays 觸發程序在一週中的執行日。 此值只能與 weekly 頻率搭配指定。
  • 星期一、星期二、星期三、星期四、星期五、星期六、星期日。
  • 日期值陣列 (最大陣列大小為 7)。
  • 日值不區分大小寫。
monthlyOccurrences 觸發程序在一個月中的執行日。 此值只能與 monthly 頻率搭配指定。
  • monthlyOccurrences 物件的陣列:{ "day": day, "occurrence": occurrence }
  • day 屬性是觸發程序在一週中的執行日。 例如,具有 day{Sunday} 值的 monthlyOccurrences 屬性意謂著月份中的每個星期日。 day 屬性 (Attribute) 是必要項。
  • occurrence 屬性係指所指定的 day 在月份中出現的位置。 例如,具有 dayoccurrence{Sunday, -1} 值的 monthlyOccurrences 屬性意謂著月份中的上個星期日。 occurrence 屬性是選擇性的。
monthDays 觸發程序在一個月中的執行日。 此值只能與 monthly 頻率搭配指定。
  • <= -1 且 >= -31 的任何值
  • >= 1 且 <= 31 的任何值
  • 值的陣列

觸發程序週期排程的範例

本節提供週期排程的範例,並將焦點放在 schedule 物件及其元素。

這些範例會假設 interval 值為 1,且 frequency 值根據排程定義是正確的。 例如,您不能有 dayfrequency 值,而且在 schedule 物件中也有 monthDays 修改。 在上一節的表格中已提到這類限制。

範例 描述
{"hours":[5]} 在每天的上午 5:00 執行。
{"minutes":[15], "hours":[5]} 在每天的上午 5:15 執行。
{"minutes":[15], "hours":[5,17]} 在每天的上午 5:15 和下午 5:15 執行。
{"minutes":[15,45], "hours":[5,17]} 在每天的上午 5:15、上午 5:45、下午 5:15 及下午 5:45 執行。
{"minutes":[0,15,30,45]} 每隔 15 分鐘執行一次。
{hours":[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23]} 每小時執行一次。 此觸發程序每小時執行一次。 已指定值時,分鐘會受 startTime 值控制。 如果未指定值,分鐘就會受建立時間控制。 例如,如果開始時間或建立時間 (無論套用哪一個) 為下午 12:25,觸發程序就會在 00:25、01:25、02:25、… 及 23:25 執行。

此排程相當於 hourfrequency 值觸發程序、1interval值,且沒有 schedule。 此排程可以與不同的 frequencyinterval 值搭配使用,以建立其他觸發程序。 例如,當 frequency 值為 month 時,排程一個月只會執行一次,而不是像 frequency 值為 day 時會每天執行。
{"minutes":[0]} 在每小時整點執行。 此觸發程序會在每小時整點執行,從上午 12:00 開始,接著在上午 1:00、上午 2:00,依此類推。

此排程相當於 hourfrequency 值的觸發程序,以及零分鐘 startTime 值,或沒有 schedule,但 dayfrequency值。 如果 frequency 值為 weekmonth,排程將只會分別在每週的一天或每個月的一天執行。
{"minutes":[15]} 在每小時的 15 分執行。 此觸發程序會在每小時的 15 分執行,從上午 00:15 開始,接著在上午 1:15、上午 2:15,依此類推,並在下午 11:15 結束。
{"hours":[17], "weekDays":["saturday"]} 在每週星期六的下午 5:00 執行。
{"hours":[17], "weekDays":["monday", "wednesday", "friday"]} 在每週星期一、星期三及星期五的下午 5:00 執行。
{"minutes":[15,45], "hours":[17], "weekDays":["monday", "wednesday", "friday"]} 在每週星期一、星期三及星期五的下午 5:15 和 5:45 執行。
{"minutes":[0,15,30,45], "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]} 在工作日每隔 15 分鐘執行一次。
{"minutes":[0,15,30,45], "hours": [9, 10, 11, 12, 13, 14, 15, 16] "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]} 在工作日的上午 9:00 與下午 4:45 之間每隔 15 分鐘執行一次。
{"weekDays":["tuesday", "thursday"]} 在星期二和星期四的指定開始時間執行。
{"minutes":[0], "hours":[6], "monthDays":[28]} 在每個月的第 28 天上午 6:00 點執行 (假設 monthfrequency 值)。
{"minutes":[0], "hours":[6], "monthDays":[-1]} 在月份最後一天的上午 6:00 執行。 若要在月份的最後一天執行觸發程序,請使用 -1,而不要使用 28、29、30 或 31。
{"minutes":[0], "hours":[6], "monthDays":[1,-1]} 在每個月第一天和最後一天的上午 6:00 執行。
{monthDays":[1,14]} 在每個月第一天和第十四天的指定開始時間執行。
{"minutes":[0], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1}]} 在每個月第一個星期五的上午 5:00 執行。
{"monthlyOccurrences":[{"day":"friday", "occurrence":1}]} 在每個月第一個星期五的指定開始時間執行。
{"monthlyOccurrences":[{"day":"friday", "occurrence":-3}]} 在每個月倒數第三個星期五的指定開始時間執行。
{"minutes":[15], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]} 在每個月第一個和最後一個星期五的上午 5:15 執行。
{"monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]} 在每個月第一個和最後一個星期五的指定開始時間執行。
{"monthlyOccurrences":[{"day":"friday", "occurrence":5}]} 在每個月第五個星期五的指定開始時間執行。 如果月份中沒有第五個星期五,管線就不會執行,由於它已排定為只在第五個星期五執行。 若要在月份中最後一個出現的星期五執行觸發程序,請考慮使用 -1 而不是 5 來作為 occurrence 的值。
{"minutes":[0,15,30,45], "monthlyOccurrences":[{"day":"friday", "occurrence":-1}]} 在月份中最後一個星期五每隔 15 分鐘執行一次。
{"minutes":[15,45], "hours":[5,17], "monthlyOccurrences":[{"day":"wednesday", "occurrence":3}]} 在每個月第三個星期三的上午 5:15、上午 5:45、下午 5:15 及下午 5:45 執行。