创建按计划运行管道的触发器

适用于： Azure 数据工厂 Azure Synapse Analytics

本文提供有关计划触发器和创建、启动和监视计划触发器的步骤的信息。 有关其他类型的触发器，请参阅管道执行和触发器。

创建计划触发器时，请指定该触发器的开始日期、重复周期或结束日期等计划，并将其与管道相关联。 管道和触发器具有“多对多”关系。 多个触发器可以启动单个管道。 单个触发器可以启动多个管道。

以下部分提供以不同方式创建计划触发器的步骤。

Azure 数据工厂和 Azure Synapse 门户体验

可以创建计划触发器，用于将管道计划为定期运行（例如每小时运行一次或每天运行一次）。

1. 切换到数据工厂中的“编辑”选项卡或 Azure Synapse 中的“集成”选项卡。

   • Azure 数据工厂
   • Azure Synapse

   

2. 在菜单上选择“触发器”，然后选择“新建/编辑”。

   

3. 在“添加触发器”页中选择“选择触发器”，然后选择“新建”。

   

4. 在“新建触发器”页上：

   1. 确认在“类型”中选择了“计划”。

   2. 对于“开始日期”，请指定触发器的开始日期/时间。 默认情况下，它设置为采用协调世界时 (UTC) 格式的当前日期/时间。

   3. 指定创建触发器的时区。 时区设置应用于“高级定期选项”中的“开始日期”、“结束日期”和“计划执行时间”。 更改“时区”设置不会自动更改开始日期。 请确保“开始日期”在指定的时区中是正确的。 “触发器的计划执行时间”被视为在开始日期后。 （确保开始日期至少比执行时间短 1 分钟，否则它会在下一个重复周期中触发管道。）

      注意

      对于实施夏令时的时区，如果重复周期设置为“天数”或更大的单位数，则触发器时间会根据此每年两次的变更自动调整。 若要选择退出夏令时变更，请选择不实施夏令时的时区，例如 UTC。

      夏令时调整仅适用于重复周期设置为“天数”或更大单位数的触发器。 如果触发器设置为“时数”或“分钟数”频率，它将继续定期触发。

   4. 指定触发器的“重复周期”。 从下拉列表中选择一个值（“每分钟”、“每小时”、“每日”、“每周”或“每月”）。 在文本框中输入乘数。 例如，如果希望触发器每隔 15 分钟运行一次，请选择“每分钟”，并在文本框中输入“15”。

   5. 在“定期”下，如果从下拉列表中选择“日”、“周”或“月”，可以看到“高级定期选项”。

      

   6. 若要指定结束日期时间，请选择“指定结束日期”。 指定“结束日期”信息，然后选择“确定”。

      每次管道运行都需要付出相关成本。 若要进行测试，需确保只触发管道几次。 但是，请确保在发布时间和结束时间之间有足够的时间来运行管道。 只有在发布解决方案之后，触发器才会生效，而不是在 UI 中保存触发器就会使该触发器生效。

      

      

5. 在“新建触发器”窗口中，选择“已激活”选项中的“是”，然后选择“确定”。 以后，可以使用此复选框停用该触发器。

   

6. 在“新建触发器”窗口中查看警告消息，然后选择“确定”。

   

7. 选择“全部发布”，发布所做的更改。 在发布更改之前，触发器不会开始触发管道运行。

   

8. 切换到左侧的“管道运行”选项卡，然后选择“刷新”以刷新列表。 可以看到计划的触发器触发的管道运行。 请注意“触发因素”列中的值。 如果使用“立即触发”选项，将在列表中看到手动触发器运行。

   • Azure 数据工厂
   • Azure Synapse

   

9. 切换到“触发器运行”>“计划”视图。

   • Azure 数据工厂
   • Azure Synapse

   

Azure PowerShell

本部分介绍如何使用 Azure PowerShell 创建、启动和监视计划触发器。 若要查看此示例的运行过程，请先完成快速入门：使用 Azure PowerShell 创建数据工厂。 然后，将以下代码添加到 main 方法，该代码用于创建并启动一个每 15 分钟运行一次的计划触发器。 该触发器与快速入门中创建的名为 Adfv2QuickStartPipeline 的管道相关联。

Prerequisites

• Azure 订阅。 如果还没有 Azure 订阅，可以在开始前创建一个免费帐户。
• Azure PowerShell。 请遵循使用 PowerShellGet 在 Windows 上安装 Azure PowerShell 中的说明。

示例代码

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 元素指定在其中创建触发器的时区。 此设置会影响 startTime 和 endTime。

   • endTime 元素比 startTime 元素的值晚一小时。 因此，触发器将在开始时间之后的 15 分钟、30 分钟和 45 分钟运行管道。 不要忘记将开始时间更新为当前 UTC 时间，将结束时间更新为比开始时间晚一小时。

     重要说明

     对于 UTC 时区，startTime 和 endTime 需要遵循格式 yyyy-MM-ddTHH:mm:ssZ。对于其他时区，startTime 和 endTime 遵循 yyyy-MM-ddTHH:mm:ss 格式。

     按照 ISO 8601 标准，时间戳的 Z 后缀将日期/时间标记为 UTC 时区，使 timeZone 字段变得无用。 如果 UTC 时区缺少 Z 后缀，则在触发器激活时，结果将出现错误。

   • 触发器与 Adfv2QuickStartPipeline 管道关联。 若要将多个管道与某个触发器相关联，请添加多个 pipelineReference 节。

   • 快速入门中的管道采用两个 parameters 值：inputPath 和 outputPath。 可以通过触发器传递这些参数的值。

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 中获取触发器运行。 若要获取有关触发器运行的信息，请定期执行以下命令。 更新 TriggerRunStartedAfter 和 TriggerRunStartedBefore 值可匹配触发器定义中的值：

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

   注意

   计划触发器的触发时间是采用 UTC 时间戳指定的。 TriggerRunStartedAfter 和 TriggerRunStartedBefore 同时预计 UTC 时间戳。

   若要在 Azure 门户中监视触发器运行和管道运行，请参阅监视管道运行。

Azure CLI

本部分介绍如何使用 Azure CLI 创建、启动和监视计划触发器。 若要查看此示例的运行过程，请先完成快速入门：使用 Azure CLI 创建 Azure 数据工厂。 然后，按照步骤创建并启动每 15 分钟运行一次的计划触发器。 该触发器与快速入门中创建的名为 Adfv2QuickStartPipeline 的管道相关联。

Prerequisites

• 在 Azure Cloud Shell 中使用 Bash 环境。 有关详细信息，请参阅 Azure Cloud Shell 入门。

  

• 如果要在本地运行 CLI 引用命令，请安装 Azure CLI。 如果在 Windows 或 macOS 上运行，请考虑在 Docker 容器中运行 Azure CLI。 有关详细信息，请参阅如何在 Docker 容器中运行 Azure CLI。

  • 如果使用的是本地安装，请使用 az login 命令登录到 Azure CLI。 要完成身份验证过程，请遵循终端中显示的步骤。 有关其他登录选项，请参阅 使用 Azure CLI 向 Azure 进行身份验证。

  • 如果系统发出提示，则在首次使用时安装 Azure CLI 扩展。 有关扩展的详细信息，请参阅 使用和管理 Azure CLI 中的扩展。

  • 运行 az version 以查找所安装的版本和依赖库。 若要升级到最新版本，请运行 az upgrade。

示例代码

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 元素指定在其中创建触发器的时区。 此设置会影响 startTime 和 endTime。

   • endTime 元素比 startTime 元素的值晚一小时。 因此，触发器将在开始时间之后的 15 分钟、30 分钟和 45 分钟运行管道。 不要忘记将开始时间更新为当前 UTC 时间，将结束时间更新为比开始时间晚一小时。

     重要说明

     对于 UTC 时区，startTime 和 endTime 需要遵循格式 yyyy-MM-ddTHH:mm:ssZ。对于其他时区，startTime 和 endTime 遵循 yyyy-MM-ddTHH:mm:ss 格式。

     按照 ISO 8601 标准，时间戳的 Z 后缀将日期/时间标记为 UTC 时区，使 timeZone 字段变得无用。 如果 UTC 时区缺少 Z 后缀，则在触发器激活时，结果将出现错误。

   • 触发器与 Adfv2QuickStartPipeline 管道关联。 若要将多个管道与某个触发器相关联，请添加多个 pipelineReference 节。

   • 快速入门中的管道采用两个 parameters 值：inputPath 和 outputPath。 可以通过触发器传递这些参数的值。

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-after 和 last-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-after 和 last-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 资源管理器模板

可以使用 Azure 资源管理器模板创建触发器。 有关分步说明，请参阅使用 Azure 资源管理器模板创建 Azure 数据工厂。

将触发器开始时间传递给管道

Azure 数据工厂版本 1 支持使用以下系统变量读取或写入分区的数据：SliceStart、SliceEnd、WindowStart 和 WindowEnd。 在数据工厂和 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>"
                }
           }
      ]
  }
}

架构概述

下表概述了与触发器的定期触发和计划相关的主要架构元素。

架构默认值、限制和示例

时区选项

下面是计划触发器支持的一些时区。

此列表不完整。 有关时区选项的完整列表，请参阅门户中的触发器创建页。

startTime 属性

下表说明了 startTime 属性如何控制触发器运行。

让我们查看一个示例，了解在开始时间是过去的时间，并且指定了定期触发但未指定计划的情况下，会发生什么事情。 假设当前时间为 2017-04-08 13:00，开始时间为 2017-04-07 14:00，定期触发为每两天触发一次。 （通过将 frequency 属性设置为 day，将 interval 属性设置为 2 来定义 recurrence 值。）请注意，startTime 值为过去的时间，发生在当前时间之前。

在这些情况下，首次执行时间为 2017-04-0914:00。 计划程序引擎从开始时间计算执行循环。 过去的所有实例会被丢弃。 引擎将使用将来发生的下一个实例。 在本方案中，开始时间为 2017-04-072:00pm，因此下一个实例为从该时间算起的 2 天，即 2017-04-092:00pm。

首次执行时间是相同的，即使 startTime 值为 2017-04-05 14:00 或 2017-04-01 14:00。 在首次执行后，使用该计划计算后续执行。 因此，后续执行时间分别为 2017-04-112:00pm、2017-04-132:00pm、2017-04-152:00pm，依此类推。

最后，如果没有在触发器的计划中设置小时或分钟，则会将第一次执行时对应的小时或分钟值用作默认值。

schedule 属性

使用 schedule 可以限制触发器执行的次数。 例如，如果触发器的频率为按月，根据计划仅在第 31 天运行，则该触发器仅在有 31 日的月份运行。

计划还可以增加触发器执行的次数。 例如，如果触发器的频率为按月，根据计划在每月的第 1 天和第 2 天运行，则该触发器会在当月的第 1 天和第 2 天运行，而不是每月运行一次。

如果指定了多个 schedule 元素，则求值时会根据计划设置按从大到小的顺序进行。 求值从周次开始，然后是月份日期、工作日、小时，最后是分钟。

下表详细描述了 schedule 元素。

触发器定期触发计划示例

本部分提供定期触发计划的示例，着重于 schedule 对象及其元素。

这些示例假定 interval 值为 1，且根据计划定义，frequency 值是正确的。 例如，不能在 frequency 值为 day 的同时，在 schedule 对象中有一个 monthDays 修改项。 上一部分的表中提到了此类限制。

相关内容

• 有关触发器的详细信息，请参阅管道执行和触发器。
• 若要了解如何引用管道中的触发器元数据，请参阅引用管道运行中的触发器元数据。