Partilhar via

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

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

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 Acionador no menu e selecione Novo/Editar.

    Captura de tela que mostra o menu Novo gatilho.

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

    Captura de tela que mostra o painel Adicionar gatilhos.

  3. Na página Novo gatilho:

    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 é criado. A configuração de fuso horário se aplica 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 altera automaticamente sua data de início. Verifique se a data de início está correta no fuso horário especificado. O tempo de execução agendada do gatilho é 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 ou então aciona o pipeline na próxima recorrência.)

      Nota

      Para fusos horários que observam o horário de verão, o tempo de gatilho se ajusta automaticamente para a alteração 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.

      O ajuste do horário de verão só acontece para um gatilho com a recorrência definida como Dias ou acima. Se o gatilho estiver definido como frequência de Horas ou Minutos , ele 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 ou 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. Em Recorrência, se escolher Dia(s), Semana(s) ou Mês(es) na lista pendente, pode ver Opções avançadas de recorrência.

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

    6. Para especificar uma hora de data de término, selecione Especificar uma data de término. Especifique as informações Ends On e selecione OK.

      Um custo está associado a cada execução de pipeline. 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 que o pipeline seja executado entre a hora de publicação e a hora de término. 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.

      Captura de tela que mostra as configurações do gatilho.

      Captura de tela que mostra 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. Você pode usar essa caixa de seleção para desativar o gatilho mais tarde.

    Captura de tela que mostra a opção Ativado.

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

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

  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.

    Captura de tela que mostra o botão Publicar tudo.

  7. Alterne para a guia Pipeline runs à esquerda e selecione Atualizar para atualizar a lista. Você vê que o pipeline é executado acionado 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 Trigger runs>Schedule.

Azure PowerShell

Nota

Recomendamos que utilize o módulo Azure Az do PowerShell para interagir com o Azure. Para começar, consulte Instalar o Azure PowerShell. 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 por 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 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 startTime valor do elemento para a hora UTC atual. Defina o endTime valor do elemento 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 type elemento do gatilho é definido como ScheduleTrigger.

    • O frequency elemento é definido como Minute e o interval elemento é definido como 15. Como tal, o gatilho executa o pipeline a cada 15 minutos entre os horários de início e fim.

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

    • O endTime elemento é uma hora após o valor do startTime elemento. 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 o fuso horário UTC, startTime e endTime precisa seguir o formato yyyy-MM-ddTHH:mm:ssZ. Para outros fusos horários, startTime e endTime siga o yyyy-MM-ddTHH:mm:ss formato.

      De acordo com a norma ISO 8601, o sufixo Z é usado para marcar a data/hora no fuso horário UTC e tornar o timeZone campo inútil. Se o sufixo Z para o fuso horário UTC estiver faltando, o resultado será um erro na ativação do gatilho.

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

    • O pipeline no início rápido usa dois parameters valores: inputPath e outputPath. 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 TriggerRunStartedAfter valores e TriggerRunStartedBefore para corresponder aos valores na 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"

    Nota

    A hora do gatilho dos gatilhos de agendamento é especificada no carimbo de data/hora UTC. TriggerRunStartedAfter e também espere TriggerRunStartedBefore o 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 por Guia de 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 é executado a cada 15 minutos. O gatilho está 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, 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 startTime valor do elemento para a hora UTC atual. Defina o endTime valor do elemento 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 type elemento do gatilho é definido como ScheduleTrigger.

    • O frequency elemento é definido como Minute e o interval elemento é definido como 15. Como tal, o gatilho executa o pipeline a cada 15 minutos entre os horários de início e fim.

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

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

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

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

    • O pipeline no início rápido usa dois parameters valores: inputPath e outputPath. 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 last-updated-after valores 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

    Os tempos de gatilho dos gatilhos de agendamento são especificados no carimbo de data/hora UTC. last-updated-after e last-updated-before também espera o 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 por 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 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, 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 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 por 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 monitor the pipeline run bloco de código 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 start_time variável para a hora UTC atual e a end_time variável 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 Azure Resource Manager.

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 SliceStartde sistema , , SliceEndWindowStarte 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 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 pipeline scheduledRunTime :

"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 parameters propriedade é uma propriedade obrigatória do pipelines elemento. Se o pipeline não usar nenhum parâmetro, você deverá incluir uma definição JSON vazia para a parameters propriedade.

Descriçã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 de JSON Description
startTime Um valor de data/hora. Para agendamentos simples, o valor da startTime propriedade se aplica à primeira ocorrência. Para agendas complexas, o gatilho não começa antes do valor especificado startTime .
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 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 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, endTimee schedule. Consulte uma lista de fusos horários suportados.
recurrence Um objeto de periodicidade que especifica as regras de periodicidade do acionador. O objeto de recorrência suporta os frequencyelementos , interval, endTime, count, e schedule . Quando um objeto de recorrência é definido, o frequency elemento é necessá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, weeke month.
interval Um inteiro positivo que denota o intervalo para o valor, que determina a frequência com que o gatilho frequency é executado. Por exemplo, se o interval é 3 e o frequency é week, o gatilho se repete a cada 3 semanas.
schedule A agenda de periodicidade do acionador. Um gatilho com um valor especificado frequency altera sua recorrência com base em um cronograma de recorrência. A schedule propriedade contém modificações para a recorrência baseadas em minutos, horas, dias úteis, dias do mês e número da semana.

Importante

Para o fuso horário UTC, startTime e endTime precisa seguir o formato yyyy-MM-ddTHH:mm:ssZ. Para outros fusos horários, startTime e endTime siga o yyyy-MM-ddTHH:mm:ss formato.

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

Predefinições, limites e exemplos do esquema

Propriedade de JSON Type Necessá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 outros fusos horários: "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 Valor Data-Hora que representa uma hora 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 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 agenda.

Time zone Deslocamento UTC (Horário de verão) 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, consulte a página Criação de gatilho no portal.

Propriedade startTime

A tabela a seguir mostra como a propriedade controla startTime uma execução de gatilho.

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 recurrence valor é definido definindo a frequency propriedade como day e a interval propriedade como 2.) Observe que o startTime valor está no passado e ocorre antes da hora atual.

Nestas condições, a primeira execução é em 2017-04-09 14: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á 2017-04-07 em 2:00pm, portanto, a próxima instância é de dois dias a partir dessa hora, que está 2017-04-09 em 2:00pm.

O primeiro tempo de execução é o mesmo, mesmo que o startTime valor 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 2017-04-11 , 2:00pmdepois 2017-04-13 em 2:00pm, depois 2017-04-15 em 2:00pm, e assim por diante.

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

Propriedade schedule

O uso de um cronograma pode limitar o número de execuções de gatilho. 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.

Uma agenda também pode expandir o número de execuções de gatilho. 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 no primeiro e segundo dias do mês, em vez de uma vez por mês.

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

A tabela a seguir descreve os schedule elementos em detalhes.

Elemento JSON Description Valores válidos
minutes Minutos da hora em que o acionador é executado.
  • Número inteiro
  • Matriz de números inteiros
hours Horas do dia em que o acionador é executado.
  • Número inteiro
  • 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.
  • Valores de matriz 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 acionador é executado. O valor pode ser especificado com uma frequência mensal apenas.
  • Matriz de monthlyOccurrences objetos: { "day": day, "occurrence": occurrence }.
  • O day atributo é o dia da semana em que o gatilho é executado. Por exemplo, um monthlyOccurrences imóvel com um day valor de {Sunday} meios todos os domingos do mês. O day atributo é obrigatório.
  • O occurrence atributo é a ocorrência do especificado day durante o mês. Por exemplo, um monthlyOccurrences imóvel com day e occurrence valores de {Sunday, -1} significa o último domingo do mês. O occurrence atributo é 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 seção fornece exemplos de agendas de recorrência e se concentra no schedule objeto e em seus elementos.

Os exemplos assumem que o interval valor é 1 e que o frequency valor está correto de acordo com a definição de agenda. Por exemplo, você não pode ter um frequency valor de day e também ter uma monthDays modificação no schedule objeto. 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 startTime valor, quando um valor é especificado. 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.

Esse cronograma é equivalente a ter um gatilho com um frequency valor de hour, um interval valor de 1, e não schedule. Esse agendamento pode ser usado com valores e interval diferentes frequency para criar outros gatilhos. Por exemplo, quando o frequency valor é month, a programação é executada apenas uma vez por mês, em vez de todos os dias, quando o frequency valor é 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.

Esse cronograma é equivalente a um gatilho com um frequency valor de e um startTime valor de hour zero minutos, ou nãoschedule, mas um frequency valor de day. Se o frequency valor for week ou month, o cronograma será executado um dia por semana ou apenas 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 da manhã no dia 28 de cada mês (assumindo um frequency valor de 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 não há quinta sexta-feira em um mês, o gasoduto não funciona porque está programado para funcionar apenas na quinta sexta-feira. Para executar o gatilho na última sexta-feira do mês, considere usar -1 em vez de 5 para o occurrence valor.
{"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