Criar um gatilho de evento personalizado para executar um pipeline no Azure Data Factory

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!

Os gatilhos de evento no Azure Data Factory permitem automatizar a execução de pipelines com base em eventos específicos que ocorrem em suas fontes de dados. Esse é um recurso fundamental da arquitetura orientada a eventos, permitindo a integração e o processamento de dados em tempo real.

A arquitetura controlada por eventos é um padrão comum de integração de dados que envolve produção, detecção, consumo e reação a eventos. Os cenários de integração de dados geralmente exigem que os clientes do Azure Data Factory disparem pipelines quando determinados eventos ocorrem. A integração nativa do Data Factory com a Grade de Eventos do Azure agora aborda tópicos personalizados. Você envia eventos para um tópico da Grade de Eventos. O Data Factory assina o tópico, escuta e dispara pipelines de acordo.

A integração descrita neste artigo depende na Grade de Eventos do Azure. Verifique se a assinatura está registrada no provedor de recursos da Grade de Eventos. Para saber mais, veja Provedores e tipos de recursos. Você deve conseguir fazer a ação Microsoft.EventGrid/eventSubscriptions/. Essa ação faz parte da função interna de Colaborador do EventSubscription de EventGrid.

Importante

Se você estiver usando esse recurso no Azure Synapse Analytics, verifique se a sua assinatura também está registrada em um provedor de recursos do Data Factory. Caso contrário, você receberá uma mensagem informando que houve uma “falha na criação de uma assinatura de evento”.

Se você combinar parâmetros de pipeline e um gatilho de evento personalizado, poderá analisar e referenciar conteúdos personalizados de data em execuções de pipeline. Como o campo data de uma carga do evento personalizado é uma estrutura de chave-valor JSON de forma livre, você pode controlar as execuções de pipeline controladas por eventos.

Importante

Se uma chave referenciada na parametrização estiver ausente na carga do evento personalizado, ocorrerá uma falha em trigger run. Você recebe uma mensagem informando que a expressão não pode ser avaliada porque a propriedade keyName não existe. Nesse caso, nenhum pipeline run é disparado pelo evento.

Casos de uso de evento e gatilho

Os gatilhos podem ser disparados por vários eventos, incluindo:

Blob Criado: quando um novo arquivo é carregado em um contêiner especificado. Blob Excluído: quando um arquivo é removido do contêiner. Blob Modificado: quando um arquivo existente é atualizado.

Você pode usar eventos para controlar dinamicamente suas execuções de pipeline. Por exemplo, quando um novo arquivo de dados é carregado na pasta "entrada" no Armazenamento de Blobs do Azure, um gatilho pode iniciar automaticamente um pipeline para processar os dados, garantindo a integração de dados em tempo hábil.

Configurar um tópico personalizado na Grade de Eventos

Para usar o gatilho de evento personalizado no Data Factory, primeiro você precisa configurar um tópico personalizado na Grade de Eventos.

Acesse a Grade de Eventos e crie o tópico por conta própria. Para obter mais informações sobre como criar o tópico personalizado, confira os tutoriais do portal e os Tutoriais da CLI do Azure da Grade de Eventos.

Observação

O fluxo de trabalho é diferente do gatilho de evento de armazenamento. Aqui, o Data Factory não configura o tópico para você.

O Data Factory espera que os eventos sigam o esquema de evento da Grade de Eventos. Verifique se as cargas do evento têm os seguintes campos:

[
  {
    "topic": string,
    "subject": string,
    "id": string,
    "eventType": string,
    "eventTime": string,
    "data":{
      object-unique-to-each-publisher
    },
    "dataVersion": string,
    "metadataVersion": string
  }
]

Usar o Data Factory para criar um gatilho de evento personalizado

1. Acesse o Data Factory e conecte-se.

2. Alterne para a guia Editar. Procure o ícone de lápis.

3. Selecione Gatilho no menu e Novo/Editar.

4. Na página Adicionar Gatilhos, selecione Escolher gatilho e, em seguida, + Novo.

5. Em Tipo, escolha Eventos personalizados.

   

6. Selecione o tópico personalizado na lista suspensa da assinatura do Azure ou insira manualmente o escopo do tópico de evento.

   Observação

   Para criar ou modificar um gatilho de evento personalizado no Data Factory, você precisa usar uma conta do Azure com o RBAC (controle de acesso baseado em função) do Azure apropriado. Nenhuma outra permissão é necessária. A entidade de serviço do Data Factory não requer permissão especial para a Grade de Eventos. Para mais informações sobre o controle de acesso, confira a seção Controle de acesso baseado em função.

7. As propriedades Subject begins with e Subject ends with permitem que você filtre eventos de gatilho. As duas propriedades são opcionais.

8. Use + Novo para adicionar os Tipos de eventos que deseja filtrar. A lista de gatilhos de eventos personalizados usa uma relação OR. Quando um evento personalizado com uma propriedade eventType corresponde a um na lista, uma execução de pipeline é disparada. O tipo de evento não diferencia as letras maiúsculas e minúsculas. Por exemplo, na captura de tela a seguir, o gatilho corresponde a todos os eventos copycompleted ou copysucceeded que têm um assunto que começa com factories.

   

9. O gatilho de evento personalizado pode analisar e enviar um conteúdo de data personalizado para o pipeline. Você cria os parâmetros de pipeline e depois preenche os valores na página Parâmetros. Use o formato @triggerBody().event.data._keyName_ para analisar o conteúdo de dados e passar valores para os parâmetros de pipeline.

   Para ver uma explicação detalhada, confira:

   • Metadados de gatilho de referência nos pipelines
   • Variáveis do sistema no gatilho de evento personalizado

   

   

10. Depois de inserir os parâmetros, selecione OK.

Filtragem avançada

Os gatilhos de evento personalizado dão suporte a funcionalidades avançadas de filtragem, semelhantes à filtragem avançada da Grade de Eventos. Esses filtros condicionais permitem que os pipelines sejam disparados com base nos valores da carga do evento. Por exemplo, você pode ter um campo na carga do evento chamado Departamento, e o pipeline será disparado apenas se Departamento for igual a Finanças. Você também pode especificar uma lógica complexa, por exemplo, o campo de data na lista [1, 2, 3, 4, 5], o campo de mês não contido na lista [11, 12] e se o campo de marca contém [Ano Fiscal 2021, FiscalYear2021 ou FY2021].

A partir de hoje, os gatilhos de evento personalizado dá suporte a um subconjunto de operações de filtragem avançada na Grade de Eventos. Há suporte para as seguintes condições de filtro:

• NumberIn
• NumberNotIn
• NumberLessThan
• NumberGreaterThan
• NumberLessThanOrEquals
• NumberGreaterThanOrEquals
• BoolEquals
• StringContains
• StringBeginsWith
• StringEndsWith
• StringIn
• StringNotIn

Selecione +Novo para adicionar novas condições de filtro.

Os gatilhos de evento personalizados também obedecem às mesmas limitações da Grade de Eventos, como:

• Cinco filtros avançados e 25 valores de filtro em todos os filtros por gatilho de evento personalizado.
• 512 caracteres por valor de cadeia de caracteres.
• 5 valores para operadores in e not in.
• As chaves não podem conter o caractere . (de ponto), por exemplo, john.doe@contoso.com. No momento, não há suporte para caracteres de escape em chaves.
• A mesma chave pode ser usada em mais de um filtro.

O Data Factory depende da última versão GA (disponibilidade geral) da API da Grade de Eventos. À medida que novas versões da API chegarem à fase GA, o Data Factory expandirá o suporte para operadores de filtragem mais avançados.

JSON schema

A tabela a seguir mostra uma visão geral dos elementos do esquema relacionados aos gatilhos de eventos personalizados.

Elemento JSON	Descrição	Type	Valores permitidos	Obrigatório
scope	A ID do recurso do Azure Resource Manager do tópico da Grade de Eventos.	String	ID do Azure Resource Manager	Sim.
events	O tipo de eventos que causam o acionamento desse gatilho.	Matriz de cadeia de caracteres		Sim, pelo menos um valor é esperado.
subjectBeginsWith	O campo subject deve começar com o padrão fornecido para disparar o gatilho. Por exemplo, factories só acionam o gatilho para objetos de evento que começam com factories.	String		Não.
subjectEndsWith	O campo subject deve começar com o padrão fornecido para disparar o gatilho.	String		Não.
advancedFilters	Lista de blobs JSON, cada um especificando uma condição de filtro. Cada blob especifica key, operatorType e values.	Lista de blobs JSON		Não.

Controle de acesso baseado em função

O Data Factory usa o RBAC do Azure para proibir o acesso não autorizado. Para funcionar corretamente, o Data Factory requer acesso para:

• Escutar eventos.
• Assinar atualizações de eventos.
• Disparar pipelines vinculados a eventos personalizados.

Para criar ou atualizar um gatilho de evento personalizado com êxito, você precisa entrar no Data Factory com uma conta do Azure que tenha acesso apropriado. Caso contrário, a operação falhará com a mensagem “Acesso Negado”.

O Data Factory não exige uma permissão especial na sua instância da Grade de Eventos. Você também não precisa atribuir permissão especial do Azure RBAC à entidade de serviço do Data Factory para a operação.

Especificamente, você precisa da permissão Microsoft.EventGrid/EventSubscriptions/Write em /subscriptions/####/resourceGroups//####/providers/Microsoft.EventGrid/topics/someTopics.

• Durante a criação no data factory (no ambiente de desenvolvimento, por exemplo), a conta do Azure conectada precisa ter a permissão anterior.
• Quando você faz a publicação por meio da integração contínua e entrega contínua, a conta usada para publicar o modelo do Azure Resource Manager na fábrica de teste ou produção precisa ter a permissão anterior.

Conteúdo relacionado

• Obtenha informações detalhadas sobre a execução de gatilho.
• Saiba como referenciar metadados de gatilho nas execuções de pipeline.