Execução de pipeline e gatilhos no Azure Data Factory ou no 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 uma execução de pipeline. Por exemplo, digamos que você tem um pipeline que é executado às 8h, 9h e 10h. Nesse caso, há três execuções de pipeline separadas. Cada execução de pipeline possui uma ID de execução de pipeline exclusiva. A ID de execução é um GUID que define exclusivamente essa execução de pipeline específica.

As execuções de pipeline normalmente são instanciadas por meio da passagem de argumentos para parâmetros definidos no pipeline. Você pode executar um pipeline manualmente ou usando um gatilho. Este artigo fornece detalhes sobre as duas maneiras de executar um pipeline.

Criar gatilhos com interface do usuário

Para disparar manualmente um pipeline ou configurar um novo gatilho agendado, janela em cascata, evento de armazenamento ou um evento personalizado, selecione Adicionar gatilho na parte superior do editor de pipeline.

Se você optar por disparar manualmente o pipeline, ele será executado imediatamente. Caso contrário, se você escolher Novo/Editar, será solicitado através da janela adicionar gatilhos que você escolha 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 em cascata, evento de armazenamento, e eventos personalizados abaixo.

Execução manual com o JSON

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

Por exemplo, digamos que você tenha um pipeline básico denominado copyPipeline que você deseja executar. O pipeline tem uma única atividade que copia de uma pasta de origem em um armazenamento de Blobs do Azure para uma pasta de destino no mesmo armazenamento. A definição de JSON a seguir 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 usa dois parâmetros: sourceBlobContainer e sinkBlobContainer. Você passa valores para esses parâmetros em runtime.

Execução manual com outras APIs/SDKs

Você pode executar o 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, confira o Início Rápido: criar um data factory usando o SDK do .NET.

Azure PowerShell

O comando de exemplo abaixo mostra como executar o pipeline manualmente usando o Azure PowerShell:

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

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

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

O conteúdo da resposta é uma ID exclusiva do pipeline de execução:

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

Para obter um exemplo completo, confira o Início Rápido: criar um data factory usando o Azure PowerShell.

SDK do Python

Para obter um exemplo completo, consulte Início Rápido: criar um data factory e um pipeline usando o 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 obter um exemplo completo, confira o Início Rápido: criar um data factory usando a API REST.

Disparar execução com JSON

Os gatilhos são outra forma de realizar uma execução do pipeline. Os gatilhos representam uma unidade de processamento que determina quando uma execução de pipeline precisa ser inicializada. Atualmente, o serviço dá suporte a três tipos de gatilhos:

• Gatilho de agenda: um gatilho que invoca um pipeline em um agendamento de relógio.

• Gatilho de janela em cascata: um gatilho que opera em um intervalo periódico enquanto também mantém o estado.

• Gatilho baseado em eventos: um disparador que responde a um evento.

Pipelines e gatilhos têm uma relação muitos para muitos (exceto para o gatilho de janela em cascata). Vários gatilhos podem disparar um único pipeline, ou um único gatilho pode disparar vários pipelines. Na definição de gatilho a seguir, a propriedade pipelines se refere a uma lista de canais que são disparados pelo gatilho específico. A definição da propriedade inclui valores para os parâmetros de 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>"
                }
            }
        ]
    }
}

Agendar gatilho com JSON

Um gatilho de agendamento executa pipelines em um agendamento de hora de relógio. Esse gatilho dá suporte às opções de calendário periódicas e avançadas. Por exemplo, o gatilho dá suporte a intervalos como "semanalmente" ou "segunda-feira às 5:00 PM e quinta-feira às 9:00 PM". O gatilho de agendamento é flexível porque o padrão de conjunto de dados é independente e o gatilho não diferencia os dados de série temporal e não 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

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

Para que o gatilho de agendamento dispare 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 uma relação 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 elemento schedule

{
  "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, limites e exemplos de esquema

Propriedade startTime

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

Vejamos um exemplo do que acontece quando a hora de início está no passado, com uma recorrência, mas sem agendamento. Suponha que a hora atual seja 8/4/2017 às 13h, a hora de início seja 7/4/2017 às 14h e a recorrência seja a cada dois dias. (O valor de recurrence é definido pela configuração da propriedade frequency como "day" e da propriedade interval como 2.) Observe que o valor startTime está no passado e ocorre antes da hora atual.

Sob essas condições, a primeira execução será em 9/4/2017 às 14h. O mecanismo do Agendador calcula as ocorrências de execução desde a hora de início. As instâncias no passado serão descartadas. O mecanismo usa a próxima instância que ocorrer no futuro. Neste cenário, a hora de início é 7/4/2017 às 14h. A próxima instância é dois dias a partir dessa hora, que é 9/4/2017 às 14h.

A primeira hora de execução é igual, mesmo que startTime seja 5/4/2017 às 14h ou 1/4/2017 às 14h. Após a primeira execução, as execuções seguintes são calculadas com o uso do agendamento. Portanto, as execuções subsequentes serão em 11/4/2017 às 14h, em 13/4/2017 às 14h, em 15/4/2017 às 14h 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 gatilho. Por exemplo, se um gatilho com uma frequência mensal é agendado para execução somente no dia 31, ele é executado apenas nos meses que têm o 31º dia.

Também é possível usar schedule para expandir o número de execuções de gatilho. Por exemplo, um gatilho com uma frequência mensal agendado para execução nos dias 1 e 2 do mês é executado no primeiro e no segundo dias do mês, em vez de uma vez por mês.

Se 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 seguinte tabela descreve elementos schedule em detalhes:

Gatilho de janela em cascata

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.

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

Exemplos de agendamentos de recorrência de gatilho

Esta seção fornece exemplos de agendamentos de recorrência. Ela tem como foco o objeto schedule 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, não é possível ter um valor de frequency igual a "day" e também ter uma modificação de monthDays no objeto schedule. Esses tipos de restrições estão descritos na tabela da seção anterior.

Comparação de tipo de gatilho

Tanto o gatilho de janela em cascata quanto o gatilho de agendamento operam sobre pulsações de tempo. Como eles são diferentes?

A tabela a seguir fornece uma comparação entre o gatilho de janela em cascata e o gatilho de agenda:

Gatilho baseado em eventos

Um gatilho baseado em eventos executa pipelines em resposta a um evento. Há dois tipos de gatilhos de eventos.

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

Para obter mais informações sobre gatilhos baseados em evento, confira Gatilho de Evento de Armazenamento e Gatilho de Evento Personalizado.

Conteúdo relacionado

Consulte 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