Criar um gatilho que executa um pipeline com base em um agendamento

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Dica

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange desde movimentação de dados até ciência de dados, análise em tempo real, business intelligence e relatórios. Saiba como iniciar uma avaliação gratuita!

Este artigo fornece informações sobre o gatilho de agendamento e as etapas para criar, iniciar e monitorar um gatilho de agendamento. Para outros tipos de gatilhos, consulte Execução de pipeline e gatilhos.

Ao criar um gatilho de agendamento, especifique um agendamento (data de início, recorrência, data de término, etc.) para o gatilho e associe-o a um pipeline. Pipelines e gatilhos têm uma relação de muitos para muitos. Vários gatilhos podem disparar um único pipeline. Um único gatilho pode disparar vários pipelines.

As seções a seguir fornecem etapas para criar um gatilho de agendamento de diferentes maneiras.

Experiência do Azure Data Factory e do portal Synapse

Crie um gatilho de agendamento para agendar a execução periódica de um pipeline (por hora, diariamente, etc.).

Observação

Para concluir r um passo a passo de criação de um pipeline e um gatilho de agendamento,associe o gatilho ao pipeline, execute e monitore o pipeline, consulteInício Rápido: criar um data factory usando a interface do usuário do Data Factory.

1. Alternar para a guia Editar Data Factory ou a guia Integrar no Azure Synapse.

   Azure Data Factory

   

   Azure Synapse

   

---

2. Selecione Gatilho no menu e depois selecione Novo/Editar.

   

3. Na página Adicionar Gatilhos, selecione Escolher gatilho... e, em seguida, selecione +Novo.

   

4. Na páginaNovo Gatilho,faça as seguintes etapas:

   1. Confirme se Agendamento está selecionado para Tipo.

   2. Especifique a data e hora de ocorre de início do gatilho em Data de Início (UTC) . Ele é definido como data e hora de ocorre atual em UTC (Tempo Universal Coordenado) por padrão.

   3. Determine o fuso horário no qual o gatilho será criado. A configuração de fuso horário será aplicada daData de Início,Data de términoe tempos deexecução de agendamento nas opções de recorrência avançadas. Alterar a configuração de fuso horário a data de início não alterará automaticamente. Certifique-se de que a Data de Início esteja correta no fuso horário especificado. Observe que o Tempo de Execução Agendado do Gatilho será considerado postagem a Data de Início (Verifique se a Data de Início é pelo menos 1 minuto menor do que o tempo de execução e, em seguida, ele disparará o pipeline na próxima recorrência).

      Observação

      Para os fusos horários que observam o horário de verão, o tempo de disparo será ajustado automaticamente para a alteração de um ano duas vezes se a recorrência for definida como Dias ou acima. Para recusar a alteração do horário de verão, selecione um fuso horário que não observe o horário de verão, por exemplo, UTC

      Importante

      O ajuste de horário de verão ocorre apenas para o disparo com recorrência definida como Dias ou acima. Se o disparo for definido como a frequência de Horas ou Minutos, ele continuará sendo acionado em intervalos regulares.

   4. Especifique Recorrência para o gatilho. Selecione um dos valores na lista suspensa (A Cada minuto, Por hora, Diariamente, Semanalmente e Mensalmente). Insira o multiplicador na caixa de texto. Por exemplo, se você deseja que o gatilho seja executado uma vez a cada 15 minutos, selecione A Cada Minuto e insira 15 na caixa de texto.

   5. Na Recorrência, se você escolher “Dias, semanas ou meses” no menu suspenso, você poderá encontrar “Opções de recorrência avançadas”.

   6. Para especificar uma data e hora de término, selecioneespecifique uma data de términoe especifiquetérmino eme, em seguida, selecioneOK. Há um custo associado a cada execução do pipeline. Se estiver testando, recomendamos garantir que o pipeline é disparado apenas algumas vezes. No entanto, verifique se há tempo suficiente para a execução do pipeline entre a hora da publicação e a hora de término. O gatilho só entra em vigor depois de você publicar a solução, e não ao salvar o gatilho na interface do usuário.

      

      

5. Na janelaNovo Gatilho,selecioneSimna opçãoAtivado e, em seguida,selecione OK. Use essa caixa de seleção para desativar o gatilho mais tarde.

   

6. Na janelaNovo Gatilho, revise a mensagem de aviso e selecioneOK.

   

7. Escolha Publicar tudo para publicar as alterações. Até que você publique alterações, o gatilho não começará a disparar as execuções do pipeline.

   

8. Alterne para a guia Execuções de pipelineà esquerda e, em seguida, selecioneAtualizar para atualizar a lista. As execuções do pipeline disparadas pelo gatilho agendado serão exibidas. Observe os valores na coluna Disparado Por. Se você usar a opçãoDisparar Agora, você verá a execução de gatilho manual na lista.

   Azure Data Factory

   

   Azure Synapse

   

---

9. Alterne aExecuções de Gatilho \ Agendamentovisualização.

   Azure Data Factory

   

   Azure Synapse

   

---

Azure PowerShell

Observação

Recomendamos que você use o módulo Az PowerShell do Azure para interagir com o Azure. Confira Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo Az PowerShell, confira Migrar o Azure PowerShell do AzureRM para o Az.

Esta seção mostra como usar o Azure PowerShell para criar, iniciar e monitorar um gatilho de agendamento. Para ver essa amostra funcionando, primeiro acompanhe o Início Rápido: Criar um data factory usando o Azure PowerShell. Em seguida, adicione o seguinte código ao método principal, que cria e inicia um gatilho de agenda que é executado a cada 15 minutos. O gatilho é associado a um pipeline chamado Adfv2QuickStartPipeline que você cria como parte do Início Rápido.

Pré-requisitos

• Assinatura do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

• Azure PowerShell. Siga as instruções em Instalar o Azure PowerShell no Windows com o PowerShellGet.

Exemplo de código

1. Crie um arquivo JSON chamado MyTrigger.json na pasta C:\ADFv2QuickStartPSH\ com o seguinte conteúdo:

   Importante

   Antes de salvar o arquivo JSON, defina o valor do elemento startTime com a hora UTC atual. Defina o valor do elemento endTime como uma hora após a hora UTC atual.

   {
       "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"
                   }
               }
           ]
       }
   }
   

   No snippet JSON:

   • O elementotipodo gatilho é definido como “Gatilho de Agendamento”.

   • O elemento frequency é definido como “Minutes” e o elemento interval é definido como 15. Propriamente dito, o gatilho executa o pipeline a cada 15 minutos entre os horários de início e término.

   • O elementofuso horárioespecifica o fuso horário em que o gatilho é criado. Esta configuração afeta tantoStartTime quantoEndTime.

   • O elemento endTime é uma hora após o valor do elemento startTime. Propriamente dito, o gatilho executa o pipeline 15 minutos, 30 minutos e 45 minutos após a hora de início. Não se esqueça de atualizar a hora de início para a hora UTC atual e a hora de término para uma hora após a hora de início.

     Importante

     Para o fuso horário UTC, StartTime e endTime precisam seguir o formato ' aaaa-MM-ddTHH: mm:ssZ', enquanto para outras zonas de tempo, StartTime e EndTime seguem ' aaaa-mm-ddThh: mm: ss '.

     Por padrão, a ISO 8601,o sufixo Zpara o carimbo de data/hora marca o datetime do fuso horário UTC e renderizar o campo de fuso horário como inútil. Embora o sufixoZausente para o fuso horário UTC resultará em um erro naativaçãodo gatilho.

   • O gatilho está associado ao pipeline Adfv2QuickStartPipeline. Para associar vários pipelines a um gatilho, adicione mais seções pipelineReference.

   • O pipeline no Início Rápido usa dois valores de parameters: inputPath e outputPath. Você passa os valores para esses parâmetros por meio do gatilho.

2. Criar um gatilho usando o cmdletSet-AzDataFactoryV2Trigger:

   Set-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger" -DefinitionFile "C:\ADFv2QuickStartPSH\MyTrigger.json"
   

3. Confirme se o status do gatilho estáParadousando o cmdletGet-AzDataFactoryV2Trigger:

   Get-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"
   

4. Inicie o gatilho usando o cmdletStart-AzDataFactoryV2Trigger:

   Start-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"
   

5. Confirme se o status do gatilho estáIniciadousando o cmdletGet-AzDataFactoryV2Trigger:

   Get-AzDataFactoryV2Trigger -ResourceGroupName $ResourceGroupName -DataFactoryName $DataFactoryName -Name "MyTrigger"
   

6. Obtenha as execuções do gatilho em Azure PowerShell usando o cmdletGet-AzDataFactoryV2TriggerRun. Para obter as informações sobre as execuções do gatilho, execute o comando a seguir periodicamente. Atualize os valores de TriggerRunStartedAfter e TriggerRunStartedBefore para que correspondam aos valores na definição de gatilho:

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

   Observação

   O tempo do gatilho dos gatilhos de agendamento é especificado no carimbo de data/hora UTC. TriggerRunStartedAfter e TriggerRunStartedBefore também exijam carimbo de data/hora UTC

   Para monitorar as execuções de gatilho e de pipeline no portal do Azure, consulte Monitorar execuções de pipeline.

CLI do Azure

Esta seção mostra como usar a CLI do Azure para criar, iniciar e monitorar um gatilho de agendamento. Para ver essa amostra funcionando, primeiro acompanhe o Início Rápido: Criar um Azure Data Factory usando a CLI do Azure. Em seguida, siga as etapas abaixo para criar e iniciar um gatilho de agendamento que é executado a cada 15 minutos. O gatilho é associado a um pipeline chamado Adfv2QuickStartPipeline que você cria como parte do Início Rápido.

Pré-requisitos

• Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.

  

• Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para saber mais, confira Como executar a CLI do Azure em um contêiner do Docker.

  • Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.

  • Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.

  • Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Exemplo de código

1. No diretório de trabalho, crie um arquivo JSON chamado MyTrigger.json com as propriedades do gatilho. Para essa exemplo, use o seguinte conteúdo:

   Importante

   Antes de salvar o arquivo JSON, defina o valor do elemento startTime com a hora UTC atual. Defina o valor do elemento endTime como uma hora após a hora UTC atual.

   {
       "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"
               }
           }
       ]
   }
   

   No snippet JSON:

   • O elementotipodo gatilho é definido como “Gatilho de Agendamento”.

   • O elemento frequency é definido como “Minutes” e o elemento interval é definido como 15. Propriamente dito, o gatilho executa o pipeline a cada 15 minutos entre os horários de início e término.

   • O elementofuso horárioespecifica o fuso horário em que o gatilho é criado. Esta configuração afeta tantoStartTime quantoEndTime.

   • O elemento endTime é uma hora após o valor do elemento startTime. Propriamente dito, o gatilho executa o pipeline 15 minutos, 30 minutos e 45 minutos após a hora de início. Não se esqueça de atualizar a hora de início para a hora UTC atual e a hora de término para uma hora após a hora de início.

     Importante

     Para o fuso horário UTC, StartTime e endTime precisam seguir o formato ' aaaa-MM-ddTHH: mm:ssZ', enquanto para outras zonas de tempo, StartTime e EndTime seguem ' aaaa-mm-ddThh: mm: ss '.

     Por padrão, a ISO 8601,o sufixo Zpara o carimbo de data/hora marca o datetime do fuso horário UTC e renderizar o campo de fuso horário como inútil. Embora o sufixoZausente para o fuso horário UTC resultará em um erro naativaçãodo gatilho.

   • O gatilho está associado ao pipeline Adfv2QuickStartPipeline. Para associar vários pipelines a um gatilho, adicione mais seções pipelineReference.

   • O pipeline no Início Rápido usa dois valores de parameters: inputPath e outputPath. Você passa os valores para esses parâmetros por meio do gatilho.

2. Crie um gatilho usando o comando az datafactory trigger create:

   az datafactory trigger create --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory"  --name "MyTrigger" --properties @MyTrigger.json  
   

3. Confirme se o status do gatilho é Parado usando o comando az datafactory trigger show:

   az datafactory trigger show --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger" 
   

4. Inicie um gatilho usando o comando az datafactory trigger start:

   az datafactory trigger start --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger" 
   

5. Confirme se o status do gatilho é Iniciado usando o comando az datafactory trigger show:

   az datafactory trigger show --resource-group "ADFQuickStartRG" --factory-name "ADFTutorialFactory" --name "MyTrigger" 
   

6. Obtenha a execução de gatilho na CLI do Azure usando o comando az datafactory trigger-run query-by-factory. Para obter informações sobre as execuções do gatilho, execute o comando a seguir periodicamente. Atualize os valores de last-updated-after e last-updated-before para corresponder aos valores na definição de gatilho:

   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"
   

   Observação

   O tempo do gatilho dos gatilhos de agendamento é especificado no carimbo de data/hora UTC. última atualização-após e última atualização-antes também esperar carimbo de data/hora UTC

   Para monitorar as execuções de gatilho e de pipeline no portal do Azure, consulte Monitorar execuções de pipeline.

SDK .NET

Esta seção mostra como usar o SDK do .NET para criar, iniciar e monitorar um gatilho. Para ver essa amostra funcionando, primeiro acompanhe o Início Rápido: Criar um data factory usando o SDK do .NET. Em seguida, adicione o seguinte código ao método principal, que cria e inicia um gatilho de agenda que é executado a cada 15 minutos. O gatilho é associado a um pipeline chamado Adfv2QuickStartPipeline que você cria como parte do Início Rápido.

Para criar e iniciar um gatilho de agendamento que é executado a cada 15 minutos, adicione o seguinte código ao método principal:

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

Para criar gatilhos em um fuso horário diferente, por meio do UTC, as seguintes configurações são necessárias:

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

Para monitorar uma execução de gatilho, adicione o seguinte código antes da última instrução Console.WriteLine na amostra:

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

Para monitorar as execuções de gatilho e de pipeline no portal do Azure, consulte Monitorar execuções de pipeline.

SDK do Python

Esta seção mostra como usar o SDK do Python para criar, iniciar e monitorar um gatilho. Para ver essa amostra funcionando, primeiro acompanhe o Início Rápido: Criar um data factory usando o SDK do Python. Em seguida, adicione o bloco de código a seguir após o bloco de código “monitorar a execução do pipeline” no script do Python. Esse código cria um gatilho de agenda que é executado a cada 15 minutos entre os horários de início e término especificados. Atualize a variável start_time para a hora UTC atual e a variável end_time para uma hora após a hora UTC atual.

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

Para monitorar as execuções de gatilho e de pipeline no portal do Azure, consulte Monitorar execuções de pipeline.

Modelo do Azure Resource Manager

Você pode usar um modelo do Azure Resource Manager para criar um gatilho. Para obter instruções passo a passo, consulte Criar um Azure Data Factory usando um modelo do Resource Manager.

Passe a hora de início do gatilho para um pipeline

O Azure Data Factory versão 1 é compatível com leitura ou gravação de dados particionados usando as variáveis do sistema SliceStart, SliceEnd, WindowStart e WindowEnd. Na versão atual do Azure Data Factory e pipelines do Synapse, é possível obter esse comportamento usando um parâmetro de pipeline. A hora de início e a hora agendada para o gatilho estão definidos com o valor para o parâmetro do pipeline. No seguinte exemplo, o horário agendado para o gatilho é passado como um valor para o parâmetro scheduledRunTime do pipeline:

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

JSON schema

A seguinte definição de JSON mostra como criar um gatilho de agendamento com o agendamento e a recorrência:

{
  "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>"
                }
           }
      ]
  }
}

Importante

A propriedade parameters é uma propriedade obrigatória do elemento pipelines. Se o pipeline não usar nenhum parâmetro, será necessário incluir uma definição de JSON vazia na propriedade parameters.

Visão geral do esquema

A seguinte tabela fornece uma visão geral de alto nível dos principais elementos de esquema relacionados à recorrência e ao agendamento de um gatilho:

Propriedade JSON	Descrição
startTime	Um valor de Data/Hora. Para agendamentos simples, o valor da propriedade startTime aplica-se à primeira ocorrência. Para agendamentos complexos, o gatilho não é iniciado antes do valor de startTime especificado. Para o fuso horário UTC, o formato é'yyyy-MM-ddTHH:mm:ssZ', para outro fuso horário, o formato é 'yyyy-MM-ddTHH:mm:ss'.
endTime	A data e a hora de início do gatilho. O gatilho não é executado após a data e a hora de término especificadas. O valor da propriedade não pode estar no passado. Essa propriedade é opcional. Para o fuso horário UTC, o formato é'yyyy-MM-ddTHH:mm:ssZ', para outro fuso horário, o formato é 'yyyy-MM-ddTHH:mm:ss'.
timeZone	O fuso horário do gatilho é criado. Essa configuração afeta startTime, endTime e schedule. Confira alista de fusos horários compatíveis
recurrence	Um objeto de recorrência que especifica as regras de recorrência para o gatilho. O objeto de recorrência dá suporte aos elementos frequency, intervall, endTime, count e schedule. Quando um objeto de recorrência é definido, o elemento frequency é obrigatório. Os outros elementos do objeto de recorrência são opcionais.
frequency	A unidade de frequência com a qual o gatilho se repete. Os valores com suporte incluem “minute”, “hour”, “day”, “week” e “month”.
interval	Um inteiro positivo que indica o intervalo para o valor de frequência, que determina a frequência com a qual o gatilho é executado. Por exemplo, se interval for 3 e frequency é "week", o gatilho é repetido a cada 3 semanas.
schedule	O agendamento de recorrência do gatilho. Um gatilho com um valor de frequency especificado altera sua recorrência com base em um agendamento de recorrência. A propriedade schedule contém modificações para a recorrência que se baseiam em minutos, horas, dias da semana, dias do mês e número da semana.

Importante

Para o fuso horário UTC, StartTime e endTime precisam seguir o formato ' aaaa-MM-ddTHH: mm:ssZ', enquanto para outras zonas de tempo, StartTime e EndTime seguem ' aaaa-mm-ddThh: mm: ss '.

Por padrão, a ISO 8601,o sufixo Zpara o carimbo de data/hora marca o datetime do fuso horário UTC e renderizar o campo de fuso horário como inútil. Embora o sufixoZausente para o fuso horário UTC resultará em um erro naativaçãodo gatilho.

Padrões, limites e exemplos de esquema

Propriedade JSON	Tipo	Obrigatório	Valor padrão	Valores válidos	Exemplo
startTime	String	Sim	Nenhum	Data e hora ISO 8601	para fuso horário UTC"startTime" : "2013-01-09T09:30:00-08:00Z" para outro fuso horário"2013-01-09T09:30:00-08:00"
timeZone	String	Sim	Nenhum	Valores do Fuso Horário	"UTC"
recurrence	Objeto	Sim	Nenhum	Objeto de recorrência	"recurrence" : { "frequency" : "monthly", "interval" : 1 }
interval	Número	Não	1	1 a 1.000	"interval":10
endTime	String	Sim	Nenhum	Um valor de Data/Hora que representa uma hora no futuro.	fuso horário UTC"endTime" : "2013-02-09T09:30:00-08:00Z" outro fuso horário"endTime" : "2013-02-09T09:30:00-08:00"
schedule	Objeto	Não	Nenhum	Objeto Agendamento	"schedule" : { "minute" : [30], "hour" : [8,17] }

Preferência de fuso horário

Aqui são alguns dos fusos horários com suporte para gatilhos de agendamento:

Fuso horário	Deslocamento UTC (Sem - Horário de Verão)	Proposta de valor do fuso horário	Note o horário de verão	Formato do carimbo de data/hora
Tempo Universal Coordenado UTC	0	UTC	Não	'yyyy-MM-ddTHH:mm:ssZ'
Hora do Pacífico(PT)	-8	Pacific Standard Time	Sim	'yyyy-MM-ddTHH:mm:ss'
Hora Central (CT)	-6	Central Standard Time	Sim	'yyyy-MM-ddTHH:mm:ss'
Hora do Leste(ET)	-5	Eastern Standard Time	Sim	'yyyy-MM-ddTHH:mm:ss'
Horário de Greenwich (GMT)	0	GMT Standard Time	Sim	'yyyy-MM-ddTHH:mm:ss'
Hora Oficial da Europa Central	+1	W. Europe Standard Time	Sim	'yyyy-MM-ddTHH:mm:ss'
Hora Oficial da Índia(IST) (Sites do plano Standard)	+5:30	India Standard Time	Não	'yyyy-MM-ddTHH:mm:ss'
Hora Oficial da China	+8	China Standard Time	Não	'yyyy-MM-ddTHH:mm:ss'

Essa lista está incompleta. Para obter uma lista completa das opções de fuso horário,pesquise na página de criação de gatilho

Propriedade startTime

A seguinte tabela mostra como a propriedade startTime controla uma execução de gatilho:

Valor startTime	Recorrência sem agendamento	Recorrência com agendamento
Hora de início no passado	Calcula a primeira hora de execução futura após a hora de início e executa nessa hora. Executa as execuções seguintes com base no cálculo do tempo da última execução. Consulte o exemplo após esta tabela.	O gatilho é iniciado não antes da hora de início especificada. A primeira ocorrência baseia-se no agendamento calculado com base na hora de início. Executa as execuções seguintes com base no agendamento de recorrência.
Hora de início no futuro ou no momento	É executado uma vez na hora de início especificada. Executa as execuções seguintes com base no cálculo do tempo da última execução.	O gatilho é iniciado não antes da hora de início especificada. A primeira ocorrência baseia-se no agendamento calculado com base na hora de início. Executa as execuções seguintes com base no agendamento de recorrência.

Vejamos um exemplo do que acontece quando a hora de início está no passado, com uma recorrência, mas sem agendamento. Suponha que a hora atual seja 2017-04-08 13:00, a hora de início seja 2017-04-07 14:00 e a recorrência seja a cada dois dias. (O valor darecorrênciaé definido pela configuração da propriedadefrequênciacomo "Avaliação gratuita por 90 Dias" e da propriedadeintervalopara 2.) Observe que o valor startTimeestá no passado e ocorre antes da hora atual.

Sob essas condições,a primeira execução será2017-04-09em14:00. O mecanismo do Agendador calcula as ocorrências de execução desde a hora de início. As instâncias no passado serão descartadas. O mecanismo usa a próxima instância que ocorrer no futuro. Neste cenário,a hora de início está2017-04-07na2:00pm,a próxima instância ocorrerá dois dias depois dessa hora,que será 2017-04-09em2:00pm.

A primeira hora de execução é igual, mesmo que o valor de startTime seja 2017-04-05 14:00 ou 2017-04-01 14:00. Após a primeira execução, as execuções seguintes são calculadas com o uso do agendamento. Portanto, as execuções subsequentes estarão em2017-04-11em2:00pm,em seguida,2017-04-13em2:00pm, em seguida,2017-04-15em2:00pm e assim por diante.

Por fim, quando as horas ou os minutos não estiverem definidos no agendamento de um gatilho, as horas ou os minutos da primeira execução serão usados como padrões.

Propriedade schedule

Por um lado, o uso de um agendamento pode limitar o número de execuções de gatilho. Por exemplo, se um gatilho com uma frequência mensal é agendado para execução somente no dia 31, ele é executado apenas nos meses que têm o dia 31.

Enquanto que, um elemento schedule também pode expandir o número de execuções do gatilho. Por exemplo, um gatilho com uma frequência mensal agendado para execução nos dias 1 e 2 do mês é executado nos dias 1 e 2 do mês, em vez de uma vez por mês.

Se vários elementos schedule forem especificados, a ordem de avaliação será feita da maior configuração de agendamento para a menor. A avaliação começa com o número da semana e, em seguida, dia do mês, dia da semana, hora e, por fim, minuto.

A seguinte tabela descreve elementos schedule em detalhes:

Elemento JSON	Descrição	Valores válidos
minutos	Minutos da hora em que o gatilho será executado.	Integer Matriz de inteiros
horas	As horas do dia em que o gatilho será executado.	Integer Matriz de inteiros
Dias da semana	Dias da semana em que o gatilho é executado. O valor pode ser especificado apenas com uma frequência semanal.	Segunda-feira, Terça-feira, Quarta-feira, Quinta-feira, Sexta-feira, Sábado e Domingo Matriz de valores de dia (o tamanho máximo da matriz é 7) Os valores de dia não diferenciam maiúsculas de minúsculas
monthlyOccurrences	Dias do mês em que o gatilho é executado. O valor pode ser especificado apenas com uma frequência mensal.	Matriz de objetos monthlyOccurrence : { "day": day, "occurrence": occurrence }. O atributo day é o dia da semana no qual o gatilho é executado. Por exemplo, uma propriedade monthlyOccurrences com um valor de day igual a {Sunday} significa todo domingo do mês. O atributo day é obrigatório. O atributo occurrence é a ocorrência de day especificado durante o mês. Por exemplo, uma propriedade monthlyOccurrences com os valores de day e occurrence iguais a {Sunday, -1} significa o último domingo do mês. O atributo occurrence é opcional.
monthDays	Dia do mês em que o gatilho é executado. O valor pode ser especificado apenas com uma frequência mensal.	Qualquer valor <= -1 e >= -31 Qualquer valor >= 1 e <= 31 Matriz de valores

Exemplos de agendamentos de recorrência de gatilho

Esta seção fornece exemplos de agendamentos de recorrência e se concentra no objeto schedule e seus elementos.

Os exemplos pressupõem que o valor de interval seja 1 e que o valor de frequency esteja correto de acordo com a definição de agendamento. Por exemplo, não é possível ter um valor de frequency igual a "day" e também ter uma modificação de "monthDays" no objeto schedule. Restrições desse tipo são mencionadas na tabela na seção anterior.

Exemplo	Descrição
{"hours":[5]}	Executar às 5h todos os dias.
{"minutes":[15], "hours":[5]}	Executar às 5h15 todos os dias.
{"minutes":[15], "hours":[5,17]}	Executar às 5h15 e 17h15 todos os dias.
{"minutes":[15,45], "hours":[5,17]}	Executar às 5h15, 5h45, 17h15 e 17h45 todos os dias.
{"minutes":[0,15,30,45]}	Executar a cada 15 minutos.
{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]}	Executar a cada hora. Este gatilho é executado a cada hora. Os minutos são controlados pelo valor de startTime, quando um valor é especificado. Se um valor não for especificado, os minutos serão controlados pela hora de criação. Por exemplo, se a hora de início ou a hora de criação (o que for aplicável) for 12h25, o gatilho será executado às 24h25, 1h25, 2h25, … e 23h25. Esse agendamento é equivalente a ter um gatilho com um valor de frequency igual a “hour”, um valor de interval igual a 1 e nenhum schedule. Esse agendamento pode ser usado com valores diferentes de frequency e interval para criar outros gatilhos. Por exemplo, quando o valor de frequency é “month”, o agendamento é executado somente uma vez por mês, em vez de todos os dias, quando o valor de frequency é “day”.
{"minutes":[0]}	Executar a cada hora na hora. Esse gatilho é executado a cada hora na hora, começando às 24h, 1h, 2h e assim por diante. Esse agendamento é equivalente a um gatilho com um valor de frequência de "hora" e um valor de startTime de zero minutos, ou nenhum agendamento, mas um valor de frequência de "dia". Se o valor de frequência for "semana" ou "mês", o agendamento será executado apenas um dia por semana ou um dia por mês, respectivamente.
{"minutes":[15]}	Executa 15 minutos após cada hora. Esse gatilho é executado a cada hora em 15 minutos após a hora, começando às 24h15, 1h15, 2h15 e assim por diante, terminando em 23h15.
{"hours":[17], "weekDays":["saturday"]}	Executar às 17h aos sábados toda semana.
{"hours":[17], "weekDays":["monday", "wednesday", "friday"]}	Executar às 17h às segundas-feiras, quartas-feiras e sextas-feiras toda semana.
{"minutes":[15,45], "hours":[17], "weekDays":["monday", "wednesday", "friday"]}	Executar às 17h15 e às 17h45 às segundas-feiras, quartas-feiras e sextas-feiras toda semana.
{"minutes":[0,15,30,45], "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]}	Executar a cada 15 minutos em dias da semana.
{"minutes":[0,15,30,45], "hours": [9, 10, 11, 12, 13, 14, 15, 16] "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]}	Executar a cada 15 minutos em dias da semana entre 9h e 16h45.
{"weekDays":["tuesday", "thursday"]}	Executar às terças-feiras e quintas-feiras na hora de início especificada.
{"minutes":[0], "hours":[6], "monthDays":[28]}	Executar às 6h no 28º dia de cada mês (supondo um valor de frequency igual a “month”).
{"minutes":[0], "hours":[6], "monthDays":[-1]}	Executar às 6h no último dia do mês. Para executar um gatilho no último dia de um mês, use -1, em vez do dia 28, 29, 30 ou 31.
{"minutes":[0], "hours":[6], "monthDays":[1,-1]}	Executar às 6h no primeiro e último dia de cada mês.
{monthDays":[1,14]}	Executar no primeiro e no 14º dia de cada mês na hora de início especificada.
{"minutes":[0], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1}]}	Executar na primeira sexta-feira de cada mês às 5h.
{"monthlyOccurrences":[{"day":"friday", "occurrence":1}]}	Executar na primeira sexta-feira de cada mês na hora de início especificada.
{"monthlyOccurrences":[{"day":"friday", "occurrence":-3}]}	Executar na terceira sexta-feira do final do mês, todo mês, na hora de início especificada.
{"minutes":[15], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]}	Executar na primeira e última sexta-feira de cada mês às 5h15.
{"monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]}	Executar na primeira e última sexta-feira de cada mês na hora de início especificada.
{"monthlyOccurrences":[{"day":"friday", "occurrence":5}]}	Executar na quinta sexta-feira de cada mês na hora de início especificada. Quando não houver nenhuma quinta sexta-feira em um mês, o pipeline não será executado, uma vez que ele está agendado para ser executado apenas nas quintas sextas-feiras. Para executar o gatilho na última sexta-feira do mês, considere o uso de -1, em vez de 5 para o valor de occurrence.
{"minutes":[0,15,30,45], "monthlyOccurrences":[{"day":"friday", "occurrence":-1}]}	Executar a cada 15 minutos na última sexta-feira do mês.
{"minutes":[15,45], "hours":[5,17], "monthlyOccurrences":[{"day":"wednesday", "occurrence":3}]}	Executar às 5h15, 5h45, 17h15 e 17h45 na terceira quarta-feira de cada mês.

Conteúdo relacionado

• Para obter mais informações detalhadas sobre gatilhos, consulte Gatilhos e execução de pipeline.
• Saiba como referenciar os metadados de gatilho no pipeline, confiraReferenciar Metadados de Gatilho em Execuções de Pipeline