Execução de pipeline e gatilhos no Azure Data Factory ou Azure Synapse Analytics

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Uma execução de pipeline no Azure Data Factory e no Azure Synapse define uma instância de execução de pipeline. Por exemplo, digamos que você tenha um pipeline que é executado às 8h, 9h e 10h. Nesse caso, há três execuções de pipeline separadas. Cada execução de pipeline tem um ID de execução de pipeline exclusivo. Um ID de execução é um GUID que define exclusivamente aquela execução de pipeline específica.

As execuções de pipeline geralmente são instanciadas passando argumentos para parâmetros que você define no pipeline. Você pode executar um pipeline manualmente ou usando um gatilho. Esse artigo fornece detalhes sobre ambas as maneiras de executar um pipeline.

Criar gatilhos com interface do usuário

Para acionar manualmente um pipeline ou configurar uma nova janela agendada, evento de armazenamento ou acionador de evento personalizado, selecione Adicionar acionador na parte superior do editor de pipeline.

Se você optar por acionar manualmente o pipeline, ele será executado imediatamente. Caso contrário, se você escolher Novo/Editar, será exibida a janela Adicionar gatilhos para escolher um gatilho existente para editar ou criar um novo gatilho.

Você verá a janela de configuração do gatilho, permitindo que você escolha o tipo de gatilho.

Leia mais sobre gatilhos agendados, janela contínua, evento de armazenamento e evento personalizado abaixo.

Execução manual

A execução manual de um pipeline também é chamada de execução sob demanda.

Por exemplo, digamos que você tenha um pipeline básico chamado copyPipeline que você deseja executar. O pipeline tem uma única atividade que copia de uma pasta de origem do armazenamento de Blobs do Azure para uma pasta de destino no mesmo armazenamento. A seguinte definição JSON mostra esse pipeline de exemplo:

{
    "name": "copyPipeline",
    "properties": {
        "activities": [
            {
                "type": "Copy",
                "typeProperties": {
                    "source": {
                        "type": "BlobSource"
                    },
                    "sink": {
                        "type": "BlobSink"
                    }
                },
                "name": "CopyBlobtoBlob",
                "inputs": [
                    {
                        "referenceName": "sourceBlobDataset",
                        "type": "DatasetReference"
                    }
                ],
                "outputs": [
                    {
                        "referenceName": "sinkBlobDataset",
                        "type": "DatasetReference"
                    }
                ]
            }
        ],
        "parameters": {
            "sourceBlobContainer": {
                "type": "String"
            },
            "sinkBlobContainer": {
                "type": "String"
            }
        }
    }
}

Na definição JSON, o pipeline recebe dois parâmetros: sourceBlobContainer e sinkBlobContainer. Você passa valores para esses parâmetros em tempo de execução.

Execução manual com outras APIs/SDKs

Você pode executar seu pipeline manualmente usando um dos seguintes métodos:

• SDK .NET
• Módulo do Azure PowerShell
• API REST
• SDK do Python

SDK .NET

A chamada de exemplo abaixo mostra como executar manualmente o pipeline usando o SDK do .NET:

client.Pipelines.CreateRunWithHttpMessagesAsync(resourceGroup, dataFactoryName, pipelineName, parameters)

Para obter um exemplo completo, veja Início Rápido: Criar uma fábrica de dados usando o .NET SDK.

Azure PowerShell

O comando de exemplo a seguir mostra como executar manualmente seu pipeline usando o Azure PowerShell:

Invoke-AzDataFactoryV2Pipeline -DataFactory $df -PipelineName "Adfv2QuickStartPipeline" -ParameterFile .\PipelineParameters.json -ResourceGroupName "myResourceGroup"

Você passa parâmetros no corpo da carga útil da solicitação. No .NET SDK, no Azure PowerShell e no Python SDK, você passa valores em um dicionário que é passado como um argumento para a chamada:

{
  "sourceBlobContainer": "MySourceFolder",
  "sinkBlobContainer": "MySinkFolder"
}

A carga útil da resposta é um ID exclusivo da execução do pipeline:

{
  "runId": "0448d45a-a0bd-23f3-90a5-bfeea9264aed"
}

Para um exemplo completo, veja Início Rápido: Criar um data factory usando o Azure PowerShell.

SDK do Python

Para um exemplo completo, veja Início Rápido: Criar uma fábrica de dados e um pipeline usando Python

API REST

O comando de exemplo abaixo mostra como executar manualmente o pipeline usando a API REST:

POST
https://management.azure.com/subscriptions/mySubId/resourceGroups/myResourceGroup/providers/Microsoft.DataFactory/factories/myDataFactory/pipelines/copyPipeline/createRun?api-version=2017-03-01-preview

Para um exemplo completo, veja Início Rápido: Criar uma fábrica de dados usando a API REST.

Tipos de gatilho

Os gatilhos são outra maneira de executar uma execução de pipeline. Os gatilhos representam uma unidade de processamento que determina quando a execução de um pipeline precisa ser iniciada. Atualmente, o serviço dá suporte a três tipos de gatilhos:

• Gatilho de programação: um gatilho que invoca um pipeline em um cronograma fixo.

• Gatilho de janela em cascata: um gatilho que opera em um intervalo periódico, ao mesmo tempo em que retém o estado.

• Gatilho baseado em evento: um gatilho que responde a um evento.

Pipelines e gatilhos têm um relacionamento de muitos para muitos (exceto pelo gatilho de janela em cascata). Vários gatilhos podem iniciar um único pipeline, ou um único gatilho pode iniciar vários pipelines. Na definição de gatilho a seguir, a propriedade pipelines se refere a uma lista de pipelines que são acionados pelo gatilho específico. A definição da propriedade inclui valores para os parâmetros do pipeline.

Definição básica do gatilho

{
    "properties": {
        "name": "MyTrigger",
        "type": "<type of trigger>",
        "typeProperties": {...},
        "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>"
                }
            }
        ]
    }
}

Gatilho de agendamento

Um gatilho de agendamento executa pipelines em um cronograma fixo. Esse gatilho suporta opções de calendário periódicas e avançadas. Por exemplo, o gatilho suporta intervalos como "semanal" ou "segunda-feira às 17h e quinta-feira às 21h." O gatilho de agendamento é flexível porque o padrão do conjunto de dados é agnóstico, e o gatilho não distingue entre dados de séries temporais e não séries temporais.

Para saber mais sobre os gatilhos de agenda e obter exemplos, confira Criar um gatilho que dispare um pipeline em uma agenda.

Definição do gatilho de agenda

Ao criar um gatilho de agendamento, você especifica o agendamento e a recorrência usando uma definição JSON.

Para que seu gatilho de agendamento inicie uma execução de pipeline, inclua uma referência de pipeline do pipeline específico na definição do gatilho. Pipelines e gatilhos têm um relacionamento de muitos para muitos. Vários gatilhos podem disparar um único pipeline. Um único gatilho pode disparar vários pipelines.

{
  "properties": {
    "type": "ScheduleTrigger",
    "typeProperties": {
      "recurrence": {
        "frequency": <<Minute, Hour, Day, Week>>,
        "interval": <<int>>, // How often to fire
        "startTime": <<datetime>>,
        "endTime": <<datetime>>,
        "timeZone": "UTC",
        "schedule": { // Optional (advanced scheduling specifics)
          "hours": [<<0-24>>],
          "weekDays": [<<Monday-Sunday>>],
          "minutes": [<<0-60>>],
          "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>"
      }
    }
  ]}
}

Visão geral do esquema

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

Exemplo de gatilho de agendamento

{
  "properties": {
    "name": "MyTrigger",
    "type": "ScheduleTrigger",
    "typeProperties": {
      "recurrence": {
        "frequency": "Hour",
        "interval": 1,
        "startTime": "2017-11-01T09:00:00-08:00",
        "endTime": "2017-11-02T22:00:00-08:00"
      }
    },
    "pipelines": [{
        "pipelineReference": {
          "type": "PipelineReference",
          "referenceName": "SQLServerToBlobPipeline"
        },
        "parameters": {}
      },
      {
        "pipelineReference": {
          "type": "PipelineReference",
          "referenceName": "SQLServerToAzureSQLPipeline"
        },
        "parameters": {}
      }
    ]
  }
}

Padrões de esquema, limites e exemplos

Propriedade startTime

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

Vejamos um exemplo do que acontece quando o horário de início está no passado, com uma recorrência, mas sem programação. Suponha que a hora atual seja 2017-04-08 13:00, a hora de início seja 2017-04-07 14:00 e a recorrência seja a cada dois dias. (O valor de recorrência é definido definindo a propriedade de frequência como "dia" e a propriedade de intervalo como 2.) Observe que o valor startTime está no passado e ocorre antes da hora atual.

Nessas condições, a primeira execução será em 09/04/2017 às 14:00. O mecanismo do Scheduler calcula as ocorrências de execução a partir do horário de início. Quaisquer instâncias no passado são descartadas. O mecanismo usa a próxima instância que ocorre no futuro. Nesse cenário, o horário de início é 07/04/2017 às 14:00. A próxima ocorrência será dois dias depois, em 09/04/2017, às 14h.

O primeiro horário de execução é o mesmo, mesmo que 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 usando o cronograma. Portanto, as execuções subsequentes serão em 11/04/2017 às 14:00, depois em 13/04/2017 às 14:00, depois em 15/04/2017 às 14:00, e assim por diante.

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

Propriedade schedule

Você pode usar schedule para limitar o número de execuções de gatilhos. Por exemplo, se um gatilho com frequência mensal estiver programado para ser executado somente no dia 31, o gatilho será executado somente nos meses que tiverem o trigésimo primeiro dia.

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

Se forem especificados vários elementos schedule, a ordem de avaliação é do maior para o menor: número da semana, dia do mês, dia da semana, hora e minuto.

A tabela a seguir descreve os elementos do cronograma em detalhes:

Gatilho de janela em cascata

Os gatilhos de janela em cascata são um tipo de gatilho que dispara em um intervalo de tempo periódico a partir de um horário de início especificado, mantendo o estado. Janelas em cascata são uma série de intervalos de tempo de tamanho fixo, não sobrepostos e contíguos.

Para saber mais sobre gatilhos periódicos e para obter exemplos, confira Criar um gatilho periódico.

Exemplos de programações de recorrência de gatilhos

Essa seção fornece exemplos de programações de recorrência. Ele se concentra no objeto agenda e seus elementos.

Os exemplos pressupõem que o valor de interval seja 1 e que o valor de frequency esteja correto de acordo com a definição de agenda. Por exemplo, você não pode ter um valor de frequência de "dia" e também ter uma modificação monthDays no objeto agenda. Esses tipos de restrições são descritos na tabela da seção anterior.

Gatilho baseado em eventos

Um gatilho baseado em eventos executa pipelines em resposta a um evento. Do ponto de vista comportamental, se você parar e reiniciar um gatilho acionado por evento, ele retomará o padrão anterior, o que pode resultar na ativação indesejada do pipeline. Nesse caso, você deve excluir e criar um novo gatilho baseado em evento. O novo gatilho é começa do zero, sem histórico. Há dois tipos de gatilhos de eventos.

• O gatilho de evento de armazenamento executa um pipeline em relação a eventos que acontecem em uma conta de armazenamento, como a chegada de um arquivo ou a exclusão de um arquivo na conta de Armazenamento de Blobs do Azure.
• O gatilho de evento personalizado processa e manipula artigos personalizados na Grade de Eventos

Para obter mais informações sobre gatilhos baseados em eventos, veja Gatilho de evento de armazenamento e Gatilho de evento personalizado.

Comparação de tipo de gatilho

Tanto o gatilho da janela giratória quanto o gatilho programado operam em pulsações temporais. Como eles são diferentes?

A tabela a seguir fornece uma comparação entre o gatilho da janela giratória e o gatilho programado:

Conteúdo relacionado

Veja os seguintes tutoriais:

• Início Rápido: Criar um data factory usando o SDK do .NET
• Criar um gatilho de agenda
• Criar um gatilho de janela em cascata