Criar um gatilho que executa um pipeline em resposta a um evento de armazenamento

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 descreve os gatilhos de eventos de armazenamento que você pode criar nos pipelines do Azure Data Factory ou do Azure Synapse Analytics.

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 disparem pipelines que são disparados a partir de eventos em uma conta do Armazenamento do Microsoft Azure, como a chegada ou a exclusão de um arquivo na conta do Armazenamento de Blobs do Azure. Os pipelines do Data Factory e do Azure Synapse Analytics integram-se nativamente à Grade de Eventos do Azure, que permite disparar pipelines em tais eventos.

Considerações sobre o gatilho de evento de armazenamento

Considere os seguintes pontos ao usar gatilhos de evento de armazenamento:

• 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 EventGrid EventSubscription Contributor.
• Se você estiver usando esse recurso no Azure Synapse Analytics, verifique se você também registrou sua assinatura no provedor de recursos do Data Factory. Caso contrário, você receberá uma mensagem informando que "a criação de uma assinatura de evento falhou".
• Se a conta do Armazenamento de Blobs residir atrás de um ponto de extremidade privado e bloquear o acesso à rede pública, você precisará configurar as regras de rede para permitir a comunicação do Armazenamento de Blobs com a Grade de Eventos. Você pode conceder acesso de armazenamento a serviços confiáveis do Azure, como a Grade de Eventos, seguindo a documentação do Armazenamento, ou configurar pontos de extremidade privados para a Grade de Eventos que mapeiam para um espaço de endereço de rede virtual, seguindo a documentação da Grade de Eventos.
• Atualmente, o gatilho de evento de armazenamento dá suporte apenas ao Azure Data Lake Storage Gen2 e a contas de armazenamento da versão 2 de uso geral. Se você estiver trabalhando com eventos de armazenamento do Secure File Transfer Protocol (SFTP), também será necessário especificar a API de Dados SFTP na seção de filtragem. Devido a uma limitação da Grade de Eventos, o Data Factory dá suporte apenas a um máximo de 500 gatilhos de eventos de armazenamento por conta de armazenamento.
• Para criar um novo gatilho de evento de armazenamento ou modificar um já existente, a conta do Azure usada para entrar no serviço e publicar o gatilho de evento de armazenamento deve ter a permissão apropriada de controle de acesso baseado em função (RBAC do Azure) na conta de armazenamento. Nenhuma outra permissão é necessária. A entidade de serviço para o Azure Data Factory e o Azure Synapse Analytics não precisa de permissão especial para a conta de armazenamento ou 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.
• Se você aplicou um bloqueio do Azure Resource Manager à sua conta de armazenamento, isso poderá afetar a capacidade do gatilho de blob de criar ou excluir blobs. Um bloqueio ReadOnly impede tanto a criação quanto a exclusão, enquanto um bloqueio DoNotDelete impede a exclusão. Certifique-se de levar em consideração essas restrições para evitar problemas com seus gatilhos.
• Não recomendamos gatilhos de chegada de arquivos como um mecanismo de gatilho de coletores de fluxo de dados. Os fluxos de dados executam várias tarefas de renomeação de arquivo e embaralhamento de arquivo de partição na pasta de destino que podem disparar inadvertidamente um evento de chegada de arquivo antes do processamento completo dos dados.

Criar um gatilho com a interface do usuário

Esta seção mostra como criar um gatilho de evento de armazenamento na interface de usuário (UI) do pipeline do Azure Data Factory e do Azure Synapse Analytics.

1. Alterne para a guia Editar no Data Factory ou para a guia Integrar no Azure Synapse Analytics.

2. No menu, selecione Gatilho e, em seguida, selecione Novo/Editar.

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

4. Selecione o tipo de gatilho Eventos de armazenamento.

   Fábrica de dados do Azure

   

   Azure Synapse Analytics

   

5. Selecione sua conta de armazenamento na lista suspensa de assinaturas do Azure ou manualmente usando sua ID do recurso da conta de armazenamento. Escolha o contêiner no qual deseja que os eventos ocorram. A seleção de contêineres é necessária, mas a seleção de todos os contêineres pode levar a um grande número de eventos.

6. As propriedades Blob path begins with e Blob path begins with permitem especificar os contêineres, pastas e nomes de blob para os quais você deseja receber eventos. Seu gatilho de evento de armazenamento requer que pelo menos uma dessas propriedades seja definida. Você pode usar vários padrões para ambas as propriedades Blob path begins with e Blob path begins with, conforme mostrado nos exemplos mais adiante neste artigo.

   • Blob path begins with: o caminho do blob deve começar com um caminho de pasta. Os valores válidos incluem 2018/ e 2018/april/shoes.csv. Este campo não poderá ser selecionado se um contêiner não estiver selecionado.
   • Blob path begins with: o caminho do blob deve terminar com uma extensão ou nome de arquivo. Os valores válidos incluem shoes.csv e .csv. Os nomes de contêineres e pastas, quando especificados, devem ser separados por um segmento de /blobs/. Por exemplo, um contêiner denominado orders pode ter um valor de /orders/blobs/2018/april/shoes.csv. Para especificar uma pasta em qualquer contêiner, omita o caractere / à esquerda. Por exemplo, april/shoes.csv dispara um evento em qualquer arquivo denominado shoes.csv em uma pasta chamada april em qualquer contêiner.

   Observe que Blob path begins with e Blob path ends with são os únicos padrões correspondentes permitidos em um gatilho de evento de armazenamento. Não há suporte para outros tipos de correspondência de curingas para o tipo de gatilho.

7. Selecione se o gatilho responde a um evento de Blob criado, Blob excluído ou ambos. No local de armazenamento especificado, cada evento dispara os pipelines do Data Factory e do Azure Synapse Analytics associados ao gatilho.

   

8. Selecione se o gatilho ignora ou não os blobs com zero byte.

9. Depois de configurar o gatilho, selecione Avançar: Visualização de dados. Esta tela mostra os blobs existentes que correspondem à sua configuração de gatilho de evento de armazenamento. Garanta que você tem filtros específicos. A configuração de filtros muito amplos pode corresponder a um grande número de arquivos criados ou excluídos e pode afetar significativamente o seu custo. Depois que as condições de filtro forem verificadas, selecione Concluir.

   

10. Para anexar um pipeline a esse gatilho, acesse a tela do pipeline e selecione Gatilho>Novo/Editar. Quando o painel lateral for exibido, selecione a lista suspensa Escolher gatilho e selecione o gatilho criado. Selecione Avançar: Visualização de dados para confirmar se a configuração está correta. Em seguida, selecione Avançar para validar se a visualização de dados está correta.

11. Se o pipeline tiver parâmetros, você poderá especificá-los no painel lateral Parâmetros de Execução de Gatilho. O gatilho de evento de armazenamento captura o nome de arquivo e o caminho de pasta do blob para as propriedades @triggerBody().folderPath e @triggerBody().fileName. Para usar os valores dessas propriedades em um pipeline, é necessário mapear as propriedades para parâmetros de pipeline. Depois de mapear as propriedades para parâmetros, acesse os valores capturados pelo gatilho por meio da expressão @pipeline().parameters.parameterName em todo o pipeline. Para obter uma explicação detalhada, confira Metadados do gatilho de referência em pipelines.

    

    No exemplo anterior, o gatilho é configurado para ser acionado quando um caminho de blob terminando em .csv for criado na pasta event-testing no contêiner sample-data. As propriedades folderPath e fileName capturam o local do novo blob. Por exemplo, quando MoviesDB.csv é adicionado ao caminho sample-data/event-testing, @triggerBody().folderPath tem um valor de sample-data/event-testing e @triggerBody().fileName tem um valor de moviesDB.csv. Esses valores são mapeados, no exemplo, para os parâmetros de pipeline sourceFolder e sourceFile, que podem ser usados em todo o pipeline como @pipeline().parameters.sourceFolder e @pipeline().parameters.sourceFile respectivamente.

12. Quando terminar, selecione Concluir.

JSON schema

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

Elemento JSON	Descrição	Type	Valores permitidos	Obrigatório
scope	A ID do recurso do Azure Resource Manager da conta de armazenamento.	String	ID do Azure Resource Manager	Sim.
events	O tipo de eventos que causam o acionamento desse gatilho.	Array	Microsoft.Storage.BlobCreated, Microsoft.Storage.BlobDeleted	Sim, qualquer combinação desses valores.
blobPathBeginsWith	O caminho do blob deve começar com o padrão fornecido para o gatilho ser acionado. Por exemplo, /records/blobs/december/ só aciona o gatilho para blobs na pasta december no contêiner records.	String		Forneça um valor para pelo menos uma dessas propriedades: blobPathBeginsWith ou blobPathEndsWith.
blobPathEndsWith	O caminho do blob deve terminar com o padrão fornecido para o gatilho ser acionado. Por exemplo, december/boxes.csv só aciona o gatilho de blobs denominado boxes em uma pasta december.	String		Forneça um valor para pelo menos uma dessas propriedades: blobPathBeginsWith ou blobPathEndsWith.
ignoreEmptyBlobs	Se os blobs de zero byte disparam ou não uma execução de pipeline. Por padrão, ele é definido como true.	Boolean	true ou false	Não.

Exemplos de gatilhos de eventos de armazenamento

Esta seção fornece exemplos de configurações de gatilho de evento de armazenamento.

Importante

Você precisa incluir o segmento /blobs/ do caminho, como mostrado nos exemplos a seguir, sempre que especificar contêiner e pasta, contêiner e arquivo ou contêiner, pasta e arquivo. Para blobPathBeginsWith, a interface do usuário adiciona /blobs/ automaticamente entre o nome da pasta e do contêiner no JSON do gatilho.

Propriedade	Exemplo	Descrição
Blob path begins with	/containername/	Recebe eventos para qualquer blob no contêiner.
Blob path begins with	/containername/blobs/foldername/	Recebe eventos para todos os blobs no contêiner containername e na pasta foldername.
Blob path begins with	/containername/blobs/foldername/subfoldername/	Você também pode fazer referência a uma subpasta.
Blob path begins with	/containername/blobs/foldername/file.txt	Recebe eventos para um blob denominado file.txt na pasta foldername no contêiner containername.
Blob path ends with	file.txt	Recebe eventos para um blob denominado file.txt em qualquer caminho.
Blob path ends with	/containername/blobs/file.txt	Recebe eventos para um blob denominado file.txt no contêiner containername.
Blob path ends with	foldername/file.txt	Recebe eventos para um blob denominado file.txt na pasta foldername em qualquer contêiner.

Controle de acesso baseado em função

Os pipelines do Data Factory e do Azure Synapse Analytics usam o controle de acesso baseado em função do Azure (RBAC do Azure) para garantir que seja estritamente proibido o acesso não autorizado para escutar, assinar atualizações e disparar pipelines vinculados a eventos de blob.

• Para criar com sucesso um novo gatilho de evento de armazenamento ou atualizar um já existente, a conta do Azure conectada ao serviço precisa ter acesso adequado à conta de armazenamento relevante. Caso contrário, a operação falhará com a mensagem "Acesso Negado".
• O Data Factory e o Azure Synapse Analytics não precisam de nenhuma permissão especial para a sua instância da Grade de Eventos, e você não precisa atribuir permissão de RBAC especial à entidade de serviço do Data Factory ou do Azure Synapse Analytics para a operação.

Qualquer uma das seguintes configurações do RBAC funciona para gatilhos de eventos de armazenamento:

• Função de proprietário para a conta de armazenamento
• Função de colaborador para a conta de armazenamento
• Permissão Microsoft.EventGrid/EventSubscriptions/Write para a conta de armazenamento /subscriptions/####/resourceGroups/####/providers/Microsoft.Storage/storageAccounts/storageAccountName

Especificamente:

• 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ê publica por meio de 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.

Para entender como o serviço cumpre as duas promessas, vamos voltar uma etapa e dar uma olhada nos bastidores. Aqui estão os fluxos de trabalho de alto nível para a integração entre o Data Factory/Azure Synapse Analytics, o Armazenamento e a Grade de Eventos.

Criar um novo gatilho de evento de armazenamento

Esse fluxo de trabalho de alto nível descreve como o Data Factory interage com a Grade de Eventos para criar um gatilho de evento de armazenamento. O fluxo de dados é o mesmo no Azure Synapse Analytics, com os pipelines do Azure Synapse Analytics assumindo a função do data factory no diagrama a seguir.

Dois destaques notáveis dos fluxos de trabalho:

• O Data Factory e o Azure Synapse Analytics não fazem contato direto com a conta de armazenamento. Em vez disso, a solicitação para criar uma assinatura é retransmitida e processada pela Grade de Eventos. O serviço não precisa de permissão para acessar a conta de armazenamento para essa etapa.
• O controle de acesso e a verificação de permissão acontecem dentro do serviço. Antes que o serviço envie uma solicitação para assinar um evento de armazenamento, ele verifica a permissão do usuário. Mais especificamente, ele verifica se a conta do Azure que está conectada e tentando criar o gatilho de evento de armazenamento tem acesso apropriado à conta de armazenamento relevante. Se a verificação de permissão falhar, a criação do gatilho também falhará.

Execução de pipeline do gatilho de evento de armazenamento

Esse fluxo de trabalho de alto nível descreve como os pipelines de gatilho de evento de armazenamento são executados pela Grade de Eventos. Para o Azure Synapse Analytics, o fluxo de dados é o mesmo, com os pipelines do Azure Synapse Analytics assumindo a função de Data Factory no diagrama a seguir.

Três destaques notáveis no fluxo de trabalho estão relacionados a pipelines de gatilho de evento no serviço:

• A Grade de Eventos usa um modelo de push que transmite a mensagem assim que possível quando o armazenamento entrega a mensagem no sistema. Essa abordagem é diferente de um sistema de mensagens, como o Kafka, em que é usado um sistema Pull.

• O gatilho de evento funciona como um ouvinte ativo da mensagem recebida e dispara corretamente o pipeline associado.

• O gatilho de evento de armazenamento em si não faz contato direto com a conta de armazenamento.

  • Se você tiver uma atividade Copy ou outra atividade dentro do pipeline para processar os dados na conta de armazenamento, o serviço fará contato direto com a conta de armazenamento usando as credenciais armazenadas no serviço vinculado. Certifique-se de que o serviço vinculado esteja configurado adequadamente.
  • Se você não fizer referência à conta de armazenamento no pipeline, não precisará conceder permissão ao serviço para acessar a conta de armazenamento.

Conteúdo relacionado

• Para obter mais informações sobre gatilhos, consulte Execução do pipeline e gatilhos.
• Para fazer referência a metadados de gatilhos em um pipeline, confira Referência a metadados de gatilhos em execuções de pipeline.