Criar um gatilho que execute um pipeline em uma janela em cascata

  • 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 etapas para criar, iniciar e monitorar um gatilho de janela em cascata. Para obter informações gerais sobre gatilhos e os tipos com suporte, consulte Gatilhos e execução de pipeline.

Os gatilhos de janela em cascata são um tipo de gatilho acionado em um intervalo de tempo periódico a partir de uma hora de início especificada, enquanto mantém o estado. As janelas em cascata são uma série de intervalos de tempo de tamanho fixo, não sobrepostos e contíguos. Um gatilho de janela em cascata tem uma relação de um para um com um pipeline, e só pode fazer referência a um único pipeline. O gatilho de janela em cascata é uma alternativa mais detalhada de gatilho de agendamento que oferece um conjunto de recursos para cenários complexos (dependência de outros gatilhos de janela em cascata, nova execução de um trabalho com falha e definição de repetição do usuário para pipelines). Para entender mais sobre a diferença entre o gatilho de agendamento e o gatilho de janela em cascata, consulte aqui.

Experiência do Azure Data Factory e do portal Synapse

  1. Para criar um gatilho periódico no portal do Azure, selecione a guia Gatilhos e selecione Novo.
  2. Depois que o painel de configuração do gatilho for aberto, selecione Janela em cascatae defina as propriedades do seu gatilho de janela em cascata.
  3. Quando terminar, selecione Salvar.

Propriedades do tipo de gatilho da janela em cascata

Uma janela em cascata tem as seguintes propriedades de tipo de gatilho:

{
    "name": "MyTriggerName",
    "properties": {
        "type": "TumblingWindowTrigger",
        "runtimeState": "<<Started/Stopped/Disabled - readonly>>",
        "typeProperties": {
            "frequency": <<Minute/Hour>>,
            "interval": <<int>>,
            "startTime": "<<datetime>>",
            "endTime": <<datetime - optional>>,
            "delay": <<timespan - optional>>,
            "maxConcurrency": <<int>> (required, max allowed: 50),
            "retryPolicy": {
                "count": <<int - optional, default: 0>>,
                "intervalInSeconds": <<int>>,
            },
            "dependsOn": [
                {
                    "type": "TumblingWindowTriggerDependencyReference",
                    "size": <<timespan - optional>>,
                    "offset": <<timespan - optional>>,
                    "referenceTrigger": {
                        "referenceName": "MyTumblingWindowDependency1",
                        "type": "TriggerReference"
                    }
                },
                {
                    "type": "SelfDependencyTumblingWindowTriggerReference",
                    "size": <<timespan - optional>>,
                    "offset": <<timespan>>
                }
            ]
        },
        "pipeline": {
            "pipelineReference": {
                "type": "PipelineReference",
                "referenceName": "MyPipelineName"
            },
            "parameters": {
                "parameter1": {
                    "type": "Expression",
                    "value": "@{concat('output',formatDateTime(trigger().outputs.windowStartTime,'-dd-MM-yyyy-HH-mm-ss-ffff'))}"
                },
                "parameter2": {
                    "type": "Expression",
                    "value": "@{concat('output',formatDateTime(trigger().outputs.windowEndTime,'-dd-MM-yyyy-HH-mm-ss-ffff'))}"
                },
                "parameter3": "https://mydemo.azurewebsites.net/api/demoapi"
            }
        }
    }
}

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

Elemento JSON Descrição Type Valores permitidos Obrigatório
tipo O tipo do gatilho. O tipo é o valor fixo "TumblingWindowTrigger". String "TumblingWindowTrigger" Yes
runtimeState O estado atual do tempo de execução do gatilho.
Observação: Este elemento é <readOnly>.		 String “Iniciado”, “Interrompido”, “Desabilitado” Yes
frequency Uma cadeia de caracteres que representa a unidade de frequência (minutos, horas ou meses) na qual o acionador é recorrente. Se os valores de dados startTime são mais granulares do que o valor de frequência, os dados startTime são consideradas quando os limites da janela são computados. Por exemplo, se o valor de frequência for de hora em hora e o valor startTime for 2017-09-01T10:10:10Z, a primeira janela será (2017-09-01T10:10:10Z, 2017-09-01T11:10:10Z). String "Minuto", "Hora", "Mês" Yes
interval Um inteiro positivo que indica o intervalo para o valor de frequência, que determina a frequência com a qual o gatilho é executado. Por exemplo, se intervalo for 3 e frequência é "hora", o gatilho é repetido a cada 3 horas.
Observação: o intervalo mínimo de janela é de 5 minutos.		 Integer Um número inteiro positivo. Yes
startTime A primeira ocorrência, que pode estar no passado. O primeiro intervalo do gatilho é (startTime, startTime + intervalo). Datetime Um valor Datetime. Yes
endTime A última ocorrência, que pode estar no passado. Datetime Um valor Datetime. Yes
delay A quantidade de tempo para atrasar o início do processamento de dados para a janela. A execução do pipeline é iniciada após o tempo de execução esperado mais a quantidade de atraso. O atraso define quanto tempo o gatilho espera antes de disparar uma nova execução. O atraso não altera a janela startTime. Por exemplo, um valor atraso igual a 00:10:00 indica um atraso de 10 minutos. Timespan
(hh:mm:ss)		 Um valor temporal em que o padrão é 00:00:00. No
maxConcurrency O número de execuções do gatilho simultâneas que são acionadas para janelas prontas. Por exemplo, para fazer o preenchimento por hora é executada para resultados de ontem em 24 janelas. Se maxConcurrency = 10, os eventos de gatilho serão disparados somente para as 10 primeiras janelas (00:00-01:00 - 09:00-10:00). Após a conclusão das primeiras 10 execuções de pipeline disparada, as execuções de gatilho serão disparadas para as próximas 10 janelas (10:00-11:00-19:00 às 20:00). Continuando com esse exemplo de maxConcurrency = 10, se houver 10 janelas prontas, há 10 execuções totais de pipeline. Se houver apenas 1 janela pronta, há apenas 1 execução do pipeline. Integer Um número inteiro entre 1 e 50. Yes
retryPolicy: Count O número de repetições antes da execução do pipeline ser marcada como "Failed." Integer Um inteiro, em que o padrão é 0 (sem repetições). No
retryPolicy: intervalInSeconds O intervalo entre tentativas de repetição especificado em segundos. Integer O número de segundos, em que o padrão é 30. O valor mínimo é 30. No
dependsOn: type Tipo de TumblingWindowTriggerReference. Necessário se uma dependência for definida. String "TumblingWindowTriggerDependencyReference", "SelfDependencyTumblingWindowTriggerReference" No
dependsOn: size Tamanho da janela em cascata de dependência. Timespan
(hh:mm:ss)		 Um valor de intervalo de tempo positivo em que o padrão é o tamanho da janela do gatilho filho No
dependsOn: offset Deslocamento do gatilho de dependência. Timespan
(hh:mm:ss)		 Um valor de intervalo de tempo que deve ser negativo em uma autodependência. Se nenhum valor for especificado, a janela será igual ao próprio gatilho. Self-Dependency: Yes
Other: No

Observação

Depois que um gatilho de janela em cascata é publicado, o intervalo e a frequência não podem ser editados.

Variáveis do sistema WindowStart e WindowEnd

Você pode usar as variáveis de sistema WindowStart e WindowEnd do gatilho de janela em cascata na sua definição de pipeline (ou seja, para a parte de uma consulta). Passar as variáveis de sistema como parâmetros para o pipeline na definição de gatilho. O exemplo a seguir mostra como passar essas variáveis como parâmetros:

{
    "name": "MyTriggerName",
    "properties": {
        "type": "TumblingWindowTrigger",
            ...
        "pipeline": {
            "pipelineReference": {
                "type": "PipelineReference",
                "referenceName": "MyPipelineName"
            },
            "parameters": {
                "MyWindowStart": {
                    "type": "Expression",
                    "value": "@{concat('output',formatDateTime(trigger().outputs.windowStartTime,'-dd-MM-yyyy-HH-mm-ss-ffff'))}"
                },
                "MyWindowEnd": {
                    "type": "Expression",
                    "value": "@{concat('output',formatDateTime(trigger().outputs.windowEndTime,'-dd-MM-yyyy-HH-mm-ss-ffff'))}"
                }
            }
        }
    }
}

Para usar os valores variáveis de sistema de WindowStart e WindowEnd na definição de pipeline, use adequadamente seus parâmetros de "MyWindowStart" e "MyWindowEnd".

Ordem de execução de janelas em um cenário de compensação

Se o StartTime do gatilho estiver no passado, então com base na fórmula M=(CurrentTime- TriggerStartTime)/TumblingWindowSize o gatilho gerará execuções de {M} backfill(past) em paralelo, respeitando a simultaneidade do gatilho antes de seguir para as execuções futuras. A ordem de execução das janelas é determinística, dos intervalos mais antigo aos mais recentes. Atualmente, esse comportamento não pode ser modificado.

Observação

Lembre-se de que, nesse cenário, todas as execuções do startTime selecionado serão executadas antes de executar execuções futuras. Se você precisar fazer backup de um longo período de tempo, é recomendável fazer uma carga histórica inicial.

Elementos TriggerResource existentes

Os pontos a seguir se aplicam à atualização dos elementos TriggerResource existentes:

  • O valor do elemento frequency (ou tamanho da janela) do gatilho em conjunto com o elemento Interval não podem ser alterado depois que o gatilho é criado. Isso é necessário para o funcionamento adequado de novas execuções do triggerRun e avaliações de dependência
  • Se o valor para o elemento endTime do gatilho altera (adicionado ou atualizado), o estado das janelas que já foram processadas não é redefinido. O gatilho respeita o novo valor endTime. Se o novo valor endTime estiver antes da janela que já foi executado, o gatilho é interrompido. Caso contrário, o gatilho interrompe quando o novo valor endTime for encontrado.

Novas tentativas de pipelines atribuídas pelo usuário

No caso de falhas de pipeline, o gatilho de janela em cascata pode repetir a execução do pipeline referenciado automaticamente usando os mesmos parâmetros de entrada, sem a intervenção do usuário. Isso pode ser especificado usando a propriedade "retryPolicy" na definição do gatilho.

Dependência de gatilho de janela em cascata

Se você quiser garantir que um gatilho de janela em cascata seja executado somente após a execução bem-sucedida de outro gatilho de janela em cascata na data factory, crie uma dependência de gatilho de janela em cascata.

Cancelar a execução da janela em cascata

Você pode cancelar execuções de um gatilho de janela em cascata se a janela específica estiver nos estados Aguardando, Aguardando dependênciaou Executando

  • Se a janela estiver no estado Executando, cancele a execução de pipelineassociada e em seguida a execução do gatilho será marcada como cancelada
  • Se a janela estiver nos estados Aguardando ou Aguardando dependência, você poderá cancelar a janela no Monitoramento:

Você também pode executar novamente uma janela cancelada. A nova execução incluirá as últimas definições publicadas do gatilho, e as dependências para a janela especificada serão reavaliadas após essa execução

Amostra do Azure PowerShell e da CLI do Azure

Esta seção mostra como usar o Azure PowerShell para criar, iniciar e monitorar um gatilho.

Observação

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

Pré-requisitos

Exemplo de código

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

    Importante

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

    {
  "name": "PerfTWTrigger",
  "properties": {
    "type": "TumblingWindowTrigger",
    "typeProperties": {
      "frequency": "Minute",
      "interval": "15",
      "startTime": "2017-09-08T05:30:00Z",
      "endTime" : "2017-09-08T06:30:00Z",
      "delay": "00:00:01",
      "retryPolicy": {
        "count": 2,
        "intervalInSeconds": 30
      },
      "maxConcurrency": 50
    },
    "pipeline": {
      "pipelineReference": {
        "type": "PipelineReference",
        "referenceName": "DynamicsToBlobPerfPipeline"
      },
      "parameters": {
        "windowStart": "@trigger().outputs.windowStartTime",
        "windowEnd": "@trigger().outputs.windowEndTime"
      }
    },
    "runtimeState": "Started"
  }
}

  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 no Azure PowerShell usando o cmdlet Get-AzDataFactoryV2TriggerRun. Para obter informações sobre as execuções do gatilho, execute o comando a seguir periodicamente. Atualize os valores de TriggerRunStartedAfter e TriggerRunStartedBefore para que correspondam aos valores na definição de gatilho:

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

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

Conteúdo relacionado