Criar um acionador que execute um pipeline com base num agendamento

  • Artigo

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

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

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 e gatilhos de pipeline.

Ao criar um gatilho de agenda, você especifica um cronograma (data de início, recorrência, data de término, etc.) para o gatilho e associa a um pipeline. Os pipelines e os acionadores têm uma relação muitos para muitos. Múltiplos acionadores podem arrancar um pipeline individual. Um acionador único pode arrancar vários pipelines.

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

Experiência do Azure Data Factory e do portal Synapse

Você pode criar um gatilho de agendamento para agendar um pipeline para ser executado periodicamente (por hora, diariamente, etc.).

Nota

Para obter um passo a passo completo sobre como criar um pipeline e um gatilho de agendamento, que associa o gatilho ao pipeline e executa e monitora o pipeline, consulte Guia de início rápido: criar uma fábrica de dados usando a interface do usuário do Data Factory.

  1. Mude para o separador Editar no Data Factory ou para o separador Integrar no Azure Synapse.

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

    New trigger menu

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

    Add triggers - new trigger

  3. Na página Novo gatilho, execute as seguintes etapas:

    1. Confirme se a opção Agenda está selecionada para Tipo.

    2. Especifique a data/hora de início do gatilho para Data de início. É definido como a datetime atual em Tempo Universal Coordenado (UTC) por padrão.

    3. Especifique o fuso horário no qual o gatilho será criado. A configuração de fuso horário será aplicada a Data de Início, Data de Término e Horários de Execução de Agendamento nas opções de recorrência Avançadas. Alterar a configuração de Fuso horário não alterará automaticamente sua data de início. Verifique se a Data de Início está correta no fuso horário especificado. Observe que o tempo de execução programada do gatilho será considerado após a data de início (certifique-se de que a data de início seja pelo menos 1 minuto menor do que o tempo de execução, caso contrário, acionará o pipeline na próxima recorrência).

      Nota

      Para fusos horários que observam o horário de verão, o tempo de gatilho será ajustado automaticamente para a mudança duas vezes por ano, se a recorrência estiver definida como Dias ou acima. Para desativar 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 do horário de verão só acontece para gatilho com recorrência definida como Dias ou acima. Se o gatilho estiver definido para a frequência de Horas ou Minutos , continuará a disparar em intervalos regulares.

    4. Especifique Recorrência para o gatilho. Selecione um dos valores na lista suspensa (Cada minuto, Horária, Diária, Semanal e Mensal). Insira o multiplicador na caixa de texto. Por exemplo, se quiser que o gatilho seja executado uma vez a cada 15 minutos, selecione Cada minuto e digite 15 na caixa de texto.

    5. Na lista suspensa Recorrência, se você escolher "Dia(s), Semana(s) ou Mês(es)" na lista suspensa, poderá encontrar "Opções avançadas de recorrência". Advanced recurrence options of Day(s), Week(s) or Month(s)

    6. Para especificar uma hora de data de término, selecione Especificar uma data de término, especifique Termina em e, em seguida, selecione OK. Nenhuma execução de pipeline tem custos associados. Se você estiver testando, convém garantir que o pipeline seja acionado apenas algumas vezes. No entanto, certifique-se de que há tempo suficiente para o pipeline ser executado entre a hora de publicação e a hora de fim. O gatilho entra em vigor somente depois que você publica a solução, não quando você salva o gatilho na interface do usuário.

      Trigger settings

      Trigger settings for End Date

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

    Trigger settings - Next button

  5. Na janela Novo gatilho, reveja a mensagem de aviso e, em seguida, selecione OK.

    Trigger settings - Finish button

  6. Selecione Publicar tudo para publicar as alterações. Até que você publique as alterações, o gatilho não começa a acionar as execuções do pipeline.

    Publish button

  7. Alterne para a guia Pipeline runs à esquerda e selecione Atualizar para atualizar a lista. Você verá as execuções de pipeline acionadas pelo gatilho agendado. Repare nos valores na coluna Acionado Por. Se você usar a opção Trigger Now, verá a execução manual do gatilho na lista.

  1. Alterne para o modo de exibição Agenda de Execuções de Gatilho \ .

Azure PowerShell

Nota

Recomendamos que utilize o módulo do Azure Az PowerShell para interagir com o Azure. Veja Instalar o Azure PowerShell para começar. Para saber como migrar para o módulo do Az PowerShell, veja 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 este exemplo funcionando, primeiro passe pelo Guia de início rápido: criar uma fábrica de dados usando o Azure PowerShell. Em seguida, adicione o seguinte código ao método principal, que cria e inicia um gatilho de agendamento que é executado a cada 15 minutos. O gatilho está associado a um pipeline chamado Adfv2QuickStartPipeline que você cria como parte do Guia de 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 para 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 trecho JSON:

    • O elemento type do gatilho é definido como "ScheduleTrigger".

    • O elemento de frequência é definido como "Minuto" e o elemento de intervalo é definido como 15. Como tal, o gatilho executa o pipeline a cada 15 minutos entre os horários de início e fim.

    • O elemento timeZone especifica o fuso horário no qual o gatilho é criado. Essa configuração afeta startTime e endTime.

    • O elemento endTime é uma hora após o valor do elemento startTime. Como tal, 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 fuso horário UTC, startTime e endTime precisam seguir o formato 'yyyy-MM-ddTHH:mm:ss Z', enquanto para outros fusos horários, startTime e endTime seguem 'yyyy-MM-ddTHH:mm:ss'.

      De acordo com o padrão ISO 8601, o sufixo Z para carimbo de data/hora marca o datetime para fuso horário UTC e torna o campo timeZone inútil. Enquanto estiver faltando o sufixo Z para o fuso horário UTC resultará em 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 Guia de início rápido usa dois valores de parâmetro: inputPath e outputPath. E você passa valores para esses parâmetros do gatilho.

  2. Crie um gatilho usando o cmdlet Set-AzDataFactoryV2Trigger :

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

  3. Confirme se o status do gatilho é Interrompido usando o cmdlet Get-AzDataFactoryV2Trigger:

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

  4. Inicie o gatilho usando o cmdlet Start-AzDataFactoryV2Trigger :

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

  5. Confirme se o status do gatilho é Iniciado usando o cmdlet Get-AzDataFactoryV2Trigger:

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

  6. Obtenha o gatilho executado no Azure PowerShell usando o cmdlet Get-AzDataFactoryV2TriggerRun . Para obter as informações sobre as execuções do gatilho, execute o seguinte comando periodicamente. Atualize os valores TriggerRunStartedAfter e TriggerRunStartedBefore para corresponder 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"

    Nota

    A hora do gatilho dos gatilhos de programação é especificada no carimbo de data/hora UTC. TriggerRunStartedAfter e TriggerRunStartedBefore também esperam um carimbo de data/hora UTC

    Para monitorar as execuções de gatilho e 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 este exemplo funcionando, primeiro passe pelo Guia de 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 está associado a um pipeline chamado Adfv2QuickStartPipeline que você cria como parte do Guia de início rápido.

Pré-requisitos

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

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 para 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 trecho JSON:

    • O elemento type do gatilho é definido como "ScheduleTrigger".

    • O elemento de frequência é definido como "Minuto" e o elemento de intervalo é definido como 15. Como tal, o gatilho executa o pipeline a cada 15 minutos entre os horários de início e fim.

    • O elemento timeZone especifica o fuso horário no qual o gatilho é criado. Essa configuração afeta startTime e endTime.

    • O elemento endTime é uma hora após o valor do elemento startTime. Como tal, 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 fuso horário UTC, startTime e endTime precisam seguir o formato 'yyyy-MM-ddTHH:mm:ss Z', enquanto para outros fusos horários, startTime e endTime seguem 'yyyy-MM-ddTHH:mm:ss'.

      De acordo com o padrão ISO 8601, o sufixo Z para carimbo de data/hora marca o datetime para fuso horário UTC e torna o campo timeZone inútil. Enquanto estiver faltando o sufixo Z para o fuso horário UTC resultará em 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 Guia de início rápido usa dois valores de parâmetro: inputPath e outputPath. E você passa valores para esses parâmetros 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 é Interrompido usando o comando az datafactory trigger show:

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

  4. Inicie o 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 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 seguinte comando periodicamente. Atualize os valores last-updated-after e last-updated-before para corresponder aos valores na 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"

    Nota

    A hora do gatilho dos gatilhos de programação é especificada no carimbo de data/hora UTC. last-updated-after e last-updated-before também espera um carimbo de data/hora UTC

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

SDK do .NET

Esta seção mostra como usar o SDK do .NET para criar, iniciar e monitorar um gatilho. Para ver este exemplo funcionando, primeiro passe pelo Guia de início rápido: criar uma fábrica de dados usando o SDK do .NET. Em seguida, adicione o seguinte código ao método principal, que cria e inicia um gatilho de agendamento que é executado a cada 15 minutos. O gatilho está associado a um pipeline chamado Adfv2QuickStartPipeline que você cria como parte do Guia de 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, 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 Console.WriteLine instrução no exemplo:

            // 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 pipeline no portal do Azure, consulte Monitorar execuções de pipeline.

Python SDK

Esta seção mostra como usar o SDK do Python para criar, iniciar e monitorar um gatilho. Para ver este exemplo funcionando, primeiro passe pelo Guia de início rápido: criar uma fábrica de dados usando o Python SDK. 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 agendamento que é executado a cada 15 minutos entre as horas de início e término especificadas. 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 pipeline no portal do Azure, consulte Monitorar execuções de pipeline.

Modelo 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 fábrica de dados do Azure usando um modelo do Gerenciador de Recursos.

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

O Azure Data Factory versão 1 dá suporte à leitura ou gravação de dados particionados usando as variáveis do sistema: SliceStart, SliceEnd, WindowStart e WindowEnd. Na versão atual dos pipelines do Azure Data Factory e Synapse, você pode obter esse comportamento usando um parâmetro de pipeline. A hora de início e a hora agendada para o gatilho são definidas como o valor para o parâmetro 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"
}

Esquema do JSON

A definição JSON a seguir mostra como criar um gatilho de agendamento com agendamento e 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 utiliza parâmetros, deve incluir uma definição JSON vazia para a propriedade parameters.

Descrição geral do esquema

A tabela que se segue fornece uma descrição geral de alto nível dos principais elementos do esquema relacionados com a periodicidade e o agendamento de um acionador:

Propriedade de JSON Description
startTime Um valor de data/hora. Para agendamentos simples, o valor da propriedade startTime aplica-se à primeira ocorrência. Para agendamentos complexos, o acionador é iniciado imediatamente a seguir ao valor especificado em startTime.
Para fuso horário UTC, formato é , para outro fuso horário, formato é 'yyyy-MM-ddTHH:mm:ssZ''yyyy-MM-ddTHH:mm:ss'.
endTime A data e hora de fim do acionador. O acionador não é executado após a data e hora de fim especificadas. O valor da propriedade não pode situar-se no passado. Esta propriedade é opcional.
Para fuso horário UTC, formato é , para outro fuso horário, formato é 'yyyy-MM-ddTHH:mm:ssZ''yyyy-MM-ddTHH:mm:ss'.
timeZone O fuso horário em que o gatilho é criado. Essa configuração afeta startTime, endTime e schedule. Consulte a lista de fusos horários suportados
recurrence Um objeto de periodicidade que especifica as regras de periodicidade do acionador. O objeto de periodicidade suporta os elementos frequency, interval, endTime, count e schedule. Quando um objeto de periodicidade é definido, o elemento frequency é obrigatório. Os outros elementos do objeto de periodicidade são opcionais.
frequency A unidade que se refere à frequência com que o acionador voltar a ocorrer. Os valores suportados incluem "minute", "hour", "day", "week" e "month".
interval Um valor inteiro positivo que indica o intervalo do valor frequency, que determina o número de vezes que o acionador é executado. Por exemplo, se o valor de interval for 3 e o de frequency for "week", o acionador repete-se de três em três semanas.
schedule A agenda de periodicidade do acionador. Um acionador que tenha um valor frequency especificado modifica a respetiva periodicidade com base numa agenda de periodicidade. A propriedade schedule contém modificações da periodicidade baseadas em minutos, horas, dias de semana, dias do mês e número da semana.

Importante

Para fuso horário UTC, startTime e endTime precisam seguir o formato 'yyyy-MM-ddTHH:mm:ss Z', enquanto para outros fusos horários, startTime e endTime seguem 'yyyy-MM-ddTHH:mm:ss'.

De acordo com o padrão ISO 8601, o sufixo Z para carimbo de data/hora marca o datetime para fuso horário UTC e torna o campo timeZone inútil. Enquanto estiver faltando o sufixo Z para o fuso horário UTC resultará em um erro na ativação do gatilho.

Predefinições, limites e exemplos do esquema

Propriedade de JSON Tipo Obrigatório Default value Valores válidos Exemplo
startTime Cadeia (de carateres) Sim Nenhuma Datas-Horas ISO 8601 para o 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 Cadeia (de carateres) Sim Nenhuma Valores de fuso horário "UTC"
recurrence Object Sim Nenhuma Objeto de periodicidade "recurrence" : { "frequency" : "monthly", "interval" : 1 }
interval Número Não 1 1 a 1000 "interval":10
endTime Cadeia (de carateres) Sim Nenhuma Um valor de data/hora que representa uma hora no futuro. para o fuso horário UTC "endTime" : "2013-02-09T09:30:00-08:00Z"
para outro fuso horário "endTime" : "2013-02-09T09:30:00-08:00"
schedule Object Não Nenhuma Objeto da agenda "schedule" : { "minute" : [30], "hour" : [8,17] }

Opção de fuso horário

Aqui estão alguns dos fusos horários suportados para gatilhos de agendamento:

Fuso Horário UTC Offset (Horário de verão Diferente) Valor de fuso horário Observe o horário de verão Formato de carimbo de data/hora
Tempo Universal Coordenado 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'
Tempo Médio de Greenwich (GMT) 0 GMT Standard Time Sim 'yyyy-MM-ddTHH:mm:ss'
Hora Padrão da Europa Central 1+ W. Europe Standard Time Sim 'yyyy-MM-ddTHH:mm:ss'
Hora Padrão da Índia (IST) +5:30 India Standard Time Não 'yyyy-MM-ddTHH:mm:ss'
Hora Padrão da China +8 China Standard Time Não 'yyyy-MM-ddTHH:mm:ss'

Esta lista está incompleta. Para obter uma lista completa de opções de fuso horário, explore na página de criação do gatilho do portal

Propriedade startTime

A tabela que se segue mostra o modo como a propriedade startTime controla a execução de um acionador:

valor de startTime Periodicidade sem agenda Periodicidade com agenda
Hora de início no passado Calcula a primeira hora de execução no futuro após a hora de início e é executada nessa hora.

Executa as execuções subsequentes com base no cálculo da última hora de execução.

Veja o exemplo a seguir à tabela.		 O acionador é iniciado imediatamente a seguir à hora de início especificada. A primeira ocorrência tem por base a agenda calculada a partir da hora de início.

Executa as execuções subsequentes com base na agenda de periodicidade.
Hora de início no futuro ou no presente É executada uma vez na hora de início especificada.

Executa as execuções subsequentes com base no cálculo da última hora de execução.		 O acionador é iniciado imediatamente a seguir à hora de início especificada. A primeira ocorrência tem por base a agenda calculada a partir da hora de início.

Executa as execuções subsequentes com base na agenda de periodicidade.

Vejamos um exemplo do que acontece quando a hora de início (startTime) se situa no passado, com periodicidade, mas sem agenda. Parta do princípio de que a hora atual é 2017-04-08 13:00, a hora de início é 2017-04-07 14:00 e a periodicidade é de dois em dois dias. (O valor de recorrência é definido definindo a propriedade frequency como "day" e a propriedade interval como 2.) Observe que o valor startTime está no passado e ocorre antes da hora atual.

Nestas condições, a primeira execução é em 2017-04-0914:00. O motor do Scheduler calcula as ocorrências de execução a partir da hora de início. Quaisquer instâncias no passado são eliminadas. O motor utiliza a instância seguinte que ocorre no futuro. Nesse cenário, a hora de início está em , portanto, a próxima instância é de dois dias a partir dessa hora, que está 2017-04-072017-04-09 em 2:00pm2: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 subsequentes são calculadas com base na agenda. Portanto, as execuções subsequentes estão em , 2:00pmdepois em , depois 2017-04-152017-04-13 em 2:00pm2017-04-112:00pm, e assim por diante.

Por último, quando as horas ou os minutos não se encontram definidos na agenda para um acionador, as horas ou minutos da primeira execução são utilizados como as predefinições.

Propriedade schedule

Por um lado, a utilização de agendas pode limitar o número de execuções de acionadores. Por exemplo, se um acionador com uma frequência mensal estiver agendado de modo a ser executado apenas no dia 31, o acionador só é executado nos meses que têm 31 dias.

Por outro lado, as agendas também podem expandir o número de execuções de acionadores. Por exemplo, um acionador com uma frequência mensal que esteja agendado de maneira a ser executado nos dias 1 e 2 do mês, é executado nos 1º e 2º dias do mês, em vez de uma vez por mês.

Se forem especificados vários elementos schedule, a ordem de avaliação é feita da definição de agenda maior para a mais pequena. A avaliação começa pelo número da semana, seguindo-se o dia do mês, o dia da semana, a hora e, por último, o minuto.

A tabela seguinte descreve os elementos de schedule de forma detalhada:

Elemento JSON Description Valores válidos
minutes Minutos da hora em que o acionador é executado.
  • Integer
  • Matriz de números inteiros
hours Horas do dia em que o acionador é executado.
  • Integer
  • Matriz de números inteiros
weekDays Dias da semana em que o acionador é executado. O valor pode ser especificado com uma frequência semanal apenas.
  • Segunda-feira, terça-feira, quarta-feira, quinta-feira, sexta-feira, sábado, domingo
  • Matriz de valores de dia (o tamanho máximo da matriz é 7)
  • Os valores de dia não são sensíveis às maiúsculas e minúsculas
monthlyOccurrences Dias do mês em que o acionador é executado. O valor pode ser especificado com uma frequência mensal apenas.
  • Matriz de objetos monthlyOccurrence : { "day": day, "occurrence": occurrence }.
  • O atributo day é o dia da semana em que o acionador é executado. Por exemplo, uma propriedade monthlyOccurrences com um valor day igual a {Sunday} significa todos os domingos do mês. O atributo day é obrigatório.
  • O atributo occurrence é a ocorrência do valor day especificado durante o mês. Por exemplo, uma propriedade monthlyOccurrences com os valores 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 acionador é executado. O valor pode ser especificado com uma frequência mensal apenas.
  • Qualquer valor <= -1 e >= -31
  • Qualquer valor >= 1 e <= 31
  • Matriz de valores

Exemplos de agendas de periodicidade do acionador

Esta secção mostra exemplos de agendas de periodicidade e centra-se no objeto schedule e respetivos elementos.

Os exemplos partem do princípio de que o valor interval é igual a 1 e que o valor frequency está correto de acordo com a definição da agenda. Por exemplo, não pode ter um valor frequency igual a "day" e ter simultaneamente uma modificação "monthDays" no objeto schedule. Este género de restrições é mencionado na tabela da secção anterior.

Exemplo Description
{"hours":[5]} Executar todos os dias às 5:00.
{"minutes":[15], "hours":[5]} Executar todos os dias às 5:15.
{"minutes":[15], "hours":[5,17]} Executar todos os dias às 5:15 e 17:15.
{"minutes":[15,45], "hours":[5,17]} Executar todos os dias às 5:15, 5:45, 17:15 e 17:45.
{"minutes":[0,15,30,45]} Executar de 15 em 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 hora a hora. Este acionador é executado de hora em hora. Os minutos são controlados pelo valor de startTime, quando é especificado um valor. Se não for especificado qualquer valor, os minutos são controlados pela hora de criação. Por exemplo, se a hora de início ou a hora de criação (a que se aplicar) for 12:25, o acionador é executado às 00:25, 01:25, 02:25 e assim sucessivamente até às 23:25.

Esta agenda equivale a ter um acionador com um valor frequency igual a "hour", um valor interval igual a 1 e zero propriedades schedule. Esta agenda pode ser utilizada com valores frequency e interval diferentes para criar outros acionadores. Por exemplo, quando o valor frequency é igual a "month", a agenda é executada apenas uma vez por mês, em vez de todos os dias, como acontece quando o valor frequency é igual a "day".
{"minutes":[0]} Executar de hora a hora, à hora certa. Este acionador é executado de hora a hora, à hora certa, começando às 00:00, 1:00, 2:00 e assim sucessivamente.

Este horário é equivalente a um gatilho com um valor de frequência de "hora" e um valor startTime de zero minutos, ou nenhum horário, mas um valor de frequência de "dia". Se o valor de frequência for "semana" ou "mês", a programação será executada apenas um dia por semana ou um dia por mês, respectivamente.
{"minutes":[15]} Executar de hora a hora, 15 minutos após a hora. Este acionador é executado de hora a hora, 15 minutos após a hora, começando às 00:15, 1:15, 2:15 e assim sucessivamente até terminar às 23:15.
{"hours":[17], "weekDays":["saturday"]} Executar às 17:00 de sábado todas as semanas.
{"hours":[17], "weekDays":["monday", "wednesday", "friday"]} Executar às 17:00 de segunda-feira, quarta-feira e sexta-feira todas as semanas.
{"minutes":[15,45], "hours":[17], "weekDays":["monday", "wednesday", "friday"]} Executar às 17:15 e 17:45 de segunda-feira, quarta-feira e sexta-feira todas as semanas.
{"minutes":[0,15,30,45], "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]} Executar de 15 em 15 minutos nos dias de semana.
{"minutes":[0,15,30,45], "hours": [9, 10, 11, 12, 13, 14, 15, 16] "weekDays":["monday", "tuesday", "wednesday", "thursday", "friday"]} Executar de 15 em 15 minutos nos dias de semana, entre as 9:00 e as 16:45.
{"weekDays":["tuesday", "thursday"]} Executar às terças-feiras e quintas-feiras à hora de início especificada.
{"minutes":[0], "hours":[6], "monthDays":[28]} Executar às 6:00 do dia 28 de cada mês (pressupondo um valor frequency igual a "month").
{"minutes":[0], "hours":[6], "monthDays":[-1]} Executar às 6:00 no último dia do mês. Para executar um acionador no último dia de um mês, utilize -1 em vez de dia 28, 29, 30 ou 31.
{"minutes":[0], "hours":[6], "monthDays":[1,-1]} Executar às 6:00 no primeiro e último dias de cada mês.
{monthDays":[1,14]} Executar no primeiro e 14.º dias de cada mês à hora de início especificada.
{"minutes":[0], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1}]} Executar na primeira sexta-feira de cada mês às 5:00.
{"monthlyOccurrences":[{"day":"friday", "occurrence":1}]} Executar na primeira sexta-feira de cada mês à hora de início especificada.
{"monthlyOccurrences":[{"day":"friday", "occurrence":-3}]} Executar na terceira sexta-feira do fim do mês, todos os meses, à hora de início especificada.
{"minutes":[15], "hours":[5], "monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]} Executar na primeira e última sextas-feiras de cada mês às 5:15.
{"monthlyOccurrences":[{"day":"friday", "occurrence":1},{"day":"friday", "occurrence":-1}]} Executar na primeira e última sextas-feiras de cada mês à hora de início especificada.
{"monthlyOccurrences":[{"day":"friday", "occurrence":5}]} Executar na quinta sexta-feira de cada mês à hora de início especificada. Quando um mês não tiver cinco sextas-feiras, o pipeline não é executado, uma vez que está agendado para ser executado apenas à quinta sexta-feira. Para executar o acionador na última sexta-feira do mês, considere utilizar -1 em vez de 5 para o valor occurrence.
{"minutes":[0,15,30,45], "monthlyOccurrences":[{"day":"friday", "occurrence":-1}]} Executar de 15 em 15 minutos na última sexta-feira do mês.
{"minutes":[15,45], "hours":[5,17], "monthlyOccurrences":[{"day":"wednesday", "occurrence":3}]} Executar às 5:15, 5:45, 17:15 e 17:45 na terceira quarta-feira de cada mês.

Conteúdos relacionados