Compartilhar via

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

  • Artigo

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, você especifica uma programação como data de início, recorrência ou data de término para o gatilho e o associa 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 portal do Azure Data Factory e do Azure Synapse

Você pode criar um gatilho de agendamento para agendar um pipeline para ser executado periodicamente, como por hora ou diariamente.

Observação

Para obter um passo a passo completo sobre a criação de um pipeline e um gatilho de agendamento, que associa o gatilho ao pipeline e executa e monitora o pipeline, consulte Início Rápido: Criar um data factory usando a interface do usuário do Data Factory.

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

  1. Selecione Gatilho no menu e, em seguida, selecione Novo/Editar.

    Captura de tela mostrando o menu Novo gatilho.

  2. Na página Adicionar gatilhos, selecione Escolher gatilho e, em seguida, Novo.

    Captura de tela mostrando o painel Adicionar gatilhos.

  3. Na página Novo gatilho:

    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. Especifique o fuso horário em que o gatilho será criado. A configuração do fuso horário se aplica a Data de Início, Data de Término e Horários de Execução do Agendamento em Opções Avançadas de Recorrência. A alteração da configuração Fuso horário não altera automaticamente a data de início. Certifique-se de que a data de início esteja correta no fuso horário especificado. A hora da Execução Agendada do Gatilho é considerada após a data de início. (Certifique-se de que a data de início seja pelo menos 1 minuto menor do que a hora de execução, caso contrário, o pipeline será disparado na próxima recorrência.)

      Observação

      Para fusos horários que observam o horário de verão, o tempo de disparo se ajusta automaticamente para a alteração duas vezes por ano, se a recorrência for definida como DIAS ou superior. Para optar por não participar da mudança de horário de verão, selecione um fuso horário que não observe o horário de verão, por exemplo, UTC.

      O ajuste do horário de verão só ocorre para um gatilho com a recorrência definida como Dias ou acima. Se o gatilho estiver definido para a frequência Horas ou Minutos, ele continuará a disparar em intervalos regulares.

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

    5. Em Recorrência, se você escolher Dia(s), Semana(s) ou Mês(s) na lista suspensa, poderá ver Opções avançadas de recorrência.

      Captura de tela mostrando as opções avançadas de recorrência de Dia(s), Semana(s) e Mês(es).

    6. Para especificar uma data de término, selecione Especificar uma data de término. Especifique a informação Termina em e selecione OK.

      Um custo é associado a cada execução do pipeline. Se estiver testando, talvez queira garantir que o pipeline seja 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.

      Captura de tela mostrando as configurações do gatilho.

      Captura de tela mostrando as configurações de gatilho para a data e hora de término.

  4. Na janela Novo gatilho, selecione Sim na opção Ativado e, em seguida, selecione OK. Use essa caixa de seleção para desativar o gatilho mais tarde.

    Captura de tela mostrando a opção Ativado.

  5. Na janela Novo Gatilho, examine a mensagem de advertência e selecione OK.

    Captura de tela mostrando a seleção do botão OK.

  6. 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.

    Captura de tela mostrando o botão Publicar tudo.

  7. Passe para a guia Execuções de pipeline à esquerda e selecione Atualizar para atualizar a lista. As execuções do pipeline disparadas pelo gatilho agendado são exibidas. Observe os valores na coluna Disparado Por. Se você usar a opção Disparar Agora, verá a execução do gatilho manual na lista.

  1. Alterne para a exibição Executar gatilhos>Agendar.

Azure PowerShell

Observação

Recomendamos que você use o módulo Az PowerShell do Azure para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. 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 esse exemplo funcionando, primeiro passe pelo Início Rápido: Criar uma 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 está associado a um pipeline chamado Adfv2QuickStartPipeline que você criou como parte do início rápido.

Pré-requisitos

Código de exemplo

  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 como a hora UTC atual. Defina o valor do elemento endTime para 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 elemento type do gatilho está definido como ScheduleTrigger.

    • O elemento frequency é definido como Minute 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 elemento timeZone especifica o fuso horário em que o gatilho é criado. Essa configuração afeta tanto startTime quanto endTime.

    • 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 yyyy-MM-ddTHH:mm:ssZ. Para outros fusos horários, startTime e endTime seguem o formato yyyy-MM-ddTHH:mm:ss.

      De acordo com o padrão ISO 8601, o sufixo Z é usado para marcar o carimbo de data/hora do fuso horário UTC e tornar o campo timeZone inútil. Se o sufixo Z do fuso horário UTC estiver ausente, o resultado será um erro na ativação do 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 recebe dois valores parameters: inputPath e outputPath. Você passa valores para esses parâmetros a partir do gatilho.

  2. Crie 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 TriggerRunStartedAfter e TriggerRunStartedBefore para que correspondam aos valores em sua 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 horário do disparo dos gatilhos de programação é especificado no carimbo de data/hora UTC. TriggerRunStartedAfter e TriggerRunStartedBefore também esperam o 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 esse exemplo funcionando, primeiro passe por Início Rápido: Criar um Azure Data Factory usando a CLI do Azure. Em seguida, siga as etapas para criar e iniciar um gatilho de agendamento que será executado a cada 15 minutos. O gatilho está associado a um pipeline chamado Adfv2QuickStartPipeline que você criou como parte do início rápido.

Pré-requisitos

Código de exemplo

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

    Importante

    Antes de salvar o arquivo JSON, defina o valor do elemento startTime como a hora UTC atual. Defina o valor do elemento endTime para 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 elemento type do gatilho está definido como ScheduleTrigger.

    • O elemento frequency é definido como Minute 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 elemento timeZone especifica o fuso horário em que o gatilho é criado. Essa configuração afeta tanto startTime quanto endTime.

    • 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, o startTime e o endTime precisam seguir o formato yyyy-MM-ddTHH:mm:ssZ. Para outros fusos horários, startTime e endTime seguem o formato yyyy-MM-ddTHH:mm:ss.

      De acordo com o padrão ISO 8601, o sufixo Z é usado para marcar o carimbo de data/hora com o fuso horário UTC e tornar o campo timeZone inútil. Se o sufixo Z estiver ausente para o fuso horário UTC, o resultado será um erro o disparar a ativação.

    • 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 recebe dois valores parameters: inputPath e outputPath. Você passa valores para esses parâmetros a partir 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 as execuções do 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 last-updated-after e last-updated-before para que correspondam aos valores em sua 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

    Os horários de disparo dos gatilhos de agendamento são especificados no carimbo de data/hora UTC. last-updated-after e last-updated-before também esperam o 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 esse exemplo funcionando, primeiro passe pelo Início Rápido: Criar uma 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 está associado a um pipeline chamado Adfv2QuickStartPipeline que você criou 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 do UTC, são necessárias as seguintes configurações:

<<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 esse exemplo funcionando, primeiro passe pelo Início Rápido: Criar uma data factory usando o SDK do Python. Em seguida, adicione o seguinte bloco de código após o bloco de código monitor the pipeline run no script 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 uma data factory do Azure usando um modelo do Azure Resource Manager.

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

A versão 1 do Azure Data Factory dá suporte à leitura ou gravação de dados particionados usando as variáveis de sistema SliceStart, SliceEnd, WindowStart e WindowEnd. Na versão atual dos pipelines do Data Factory e do Azure Synapse, você pode 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 exemplo a seguir, a hora agendada para o gatilho é passada 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 seu pipeline não receber nenhum parâmetro, você deverá incluir uma definição JSON vazia para a propriedade parameters.

Visão geral do esquema

A tabela a seguir fornece uma visão geral de alto nível dos principais elementos do 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 se aplica à primeira ocorrência. Para agendamentos complexos, o gatilho não começa antes do valor startTime especificado.
Para o fuso horário UTC, o formato é 'yyyy-MM-ddTHH:mm:ssZ'. Para outros fusos horários, 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 outros fusos horários, o formato é yyyy-MM-ddTHH:mm:ss.
timeZone O fuso horário no qual o gatilho é criado. Essa configuração afeta startTime, endTime e schedule. Consulte a lista de fusos horários com suporte.
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, interval, 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 número inteiro positivo que denota o intervalo do valor frequency, que determina a frequência de execução do gatilho. Por exemplo, se interval for 3 e frequency for week, o gatilho será executado a cada 3 semanas.
schedule O agendamento de recorrência do gatilho. Um gatilho com um valor frequency especificado altera sua recorrência com base em um cronograma de recorrência. A propriedade schedule contém modificações para a recorrência que são baseadas 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 yyyy-MM-ddTHH:mm:ssZ. Para outros fusos horários, startTime e endTime seguem o formato yyyy-MM-ddTHH:mm:ss.

De acordo com o padrão ISO 8601, o sufixo Z é usado para marcar o carimbo de data/hora com o fuso horário UTC e tornar o campo timeZone inútil. Se o sufixo Z estiver ausente para o fuso horário UTC, o resultado será um erro o disparar a ativação.

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 o fuso horário UTC: "startTime" : "2013-01-09T09:30:00-08:00Z"
Para outros fusos horários: "2013-01-09T09:30:00-08:00"
timeZone String Sim Nenhum Valores de 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 Valor de data/hora que representa um momento no futuro Para o fuso horário UTC: "endTime" : "2013-02-09T09:30:00-08:00Z"
Para outros fusos horários: "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 estão alguns dos fusos horários com suporte para gatilhos de agendamento.

Fuso horário Diferença UTC (sem horário de verão) Valor de timeZone Observar 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, consulte a página Criação de gatilho no portal.

Propriedade startTime

A tabela a seguir mostra como a propriedade startTime controla a execução de um 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 recurrence é definido pela configuração da propriedade frequency como day e da propriedade interval como 2.) Observe que o valor startTime está 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.

O primeiro tempo de execução é o mesmo, mesmo que o valor 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.

Finalmente, quando as horas ou os minutos não são definidos no agendamento de um gatilho, as horas ou os minutos da primeira execução são usados como padrão.

Propriedade schedule

O uso de uma programação pode limitar o número de execuções de gatilhos. 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.

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

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

A tabela a seguir descreve os elementos schedule em detalhes.

Elemento JSON Descrição Valores válidos
minutes Minutos da hora em que o gatilho será executado.
  • Integer
  • Matriz de inteiros
hours As horas do dia em que o gatilho será executado.
  • Integer
  • Matriz de inteiros
weekDays 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, domingo.
  • Matriz de valores de dias (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 monthlyOccurrences: { "day": day, "occurrence": occurrence }.
  • O atributo day é o dia da semana em que o gatilho é executado. Por exemplo, uma propriedade monthlyOccurrences com um valor day de {Sunday} significa todo domingo do mês. O atributo day é necessário.
  • O atributo occurrence é a ocorrência do day especificado durante o mês. Por exemplo, uma propriedade monthlyOccurrences com valores day e occurrence de {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 interval é 1 e que o valor frequency está correto de acordo com a definição do agendamento. Por exemplo, não é possível ter um valor frequency de day e também ter uma modificação 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 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.

Essa programação é equivalente a ter um gatilho com um valor frequency de hour, um valor interval de 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 frequency é month, o agendamento é executado apenas uma vez por mês, em vez de todos os dias, quando o valor 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 valor frequency de hour e valor startTime de zero minutos, ou sem schedule, mas com valor frequency de day. Se o valor frequency for week ou month, a programação será executada somente 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 6h00 no 28º dia de cada mês (assumindo um valor frequency de 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 há uma quinta sexta-feira em um mês, o pipeline não é executado porque está agendado para ser executado somente 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 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