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

APLICA-SE A: Azure Data Factory Azure Synapse Analytics

Gorjeta

Experimente o Data Factory no Microsoft Fabric, uma solução de análise tudo-em-um para empresas. O Microsoft Fabric abrange tudo, desde a movimentação de dados até ciência de dados, análises em tempo real, business intelligence e relatórios. Saiba como iniciar uma nova avaliação gratuitamente!

Este artigo descreve os gatilhos de eventos de armazenamento que você pode criar em seus pipelines do Azure Data Factory ou do Azure Synapse Analytics.

A arquitetura orientada a eventos é um padrão comum de integração de dados que envolve produção, deteção, consumo e reação a eventos. Os cenários de integração de dados geralmente exigem que os clientes acionem pipelines acionados a partir de eventos em uma conta de Armazenamento do Azure, como a chegada ou a exclusão de um arquivo na conta de Armazenamento de Blob do Azure. Os pipelines do Data Factory e do Azure Synapse Analytics integram-se nativamente com a Grade de Eventos do Azure, o que permite acionar pipelines nesses eventos.

Considerações sobre o gatilho de eventos de armazenamento

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

• A integração descrita neste artigo depende da Grade de Eventos do Azure. Certifique-se de que a sua subscrição está registada no fornecedor de recursos da Grelha de Eventos. Para obter mais informações, veja Resource providers and types (Tipos e fornecedores de recursos). Você deve ser capaz de fazer a Microsoft.EventGrid/eventSubscriptions/ ação. Esta ação faz parte da EventGrid EventSubscription Contributor função interna.
• Se estiver a utilizar esta funcionalidade no Azure Synapse Analytics, certifique-se de que também regista a sua subscrição junto do fornecedor 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 de Armazenamento de Blob residir atrás de um ponto de extremidade privado e bloquear o acesso à rede pública, você precisará configurar regras de rede para permitir comunicações do Armazenamento de Blob para a Grade de Eventos. Você pode conceder acesso de armazenamento a serviços confiáveis do Azure, como Grade de Eventos, seguindo a documentação de Armazenamento, ou configurar pontos de extremidade privados para Grade de Eventos mapeados para um espaço de endereçamento de rede virtual, seguindo a documentação da Grade de Eventos.
• Atualmente, o gatilho de evento de armazenamento suporta apenas contas de armazenamento do Azure Data Lake Storage Gen2 e de uso geral versão 2. Se você estiver trabalhando com eventos de armazenamento SFTP (Secure File Transfer Protocol), também precisará especificar a API de dados SFTP na seção de filtragem. Devido a uma limitação de Grade de Eventos, o Data Factory oferece 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 existente, a conta do Azure que você usa para entrar no serviço e publicar o gatilho de evento de armazenamento deve ter permissão apropriada de controle de acesso baseado em função (Azure RBAC) 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 obter mais informações sobre controle de acesso, consulte 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 ReadOnly bloqueio impede a criação e a exclusão, enquanto um bloqueio impede a DoNotDelete exclusão. Certifique-se de levar em conta essas restrições para evitar problemas com seus gatilhos.
• Não recomendamos gatilhos de chegada de arquivo como um mecanismo de acionamento de coletores de fluxo de dados. Os fluxos de dados executam várias tarefas de renomeação e baralhamento de arquivos de partição na pasta de destino que podem inadvertidamente acionar um evento de chegada de arquivo antes do processamento completo de seus dados.

Criar um gatilho com a interface do usuário

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

1. Mude para o separador Editar no Data Factory ou para o separador 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, selecione + 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 assinatura do Azure ou manualmente usando sua ID de recurso da conta de armazenamento. Escolha o contêiner no qual você 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 Blob path begins with propriedades e Blob path ends with permitem especificar os contêineres, pastas e nomes de blob para os quais você deseja receber eventos. O gatilho de evento de armazenamento requer que pelo menos uma dessas propriedades seja definida. Você pode usar vários padrões para ambas as Blob path begins with propriedades e Blob path ends with propriedades, conforme mostrado nos exemplos mais adiante neste artigo.

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

   Observe que Blob path begins with e Blob path ends with são a única correspondência de padrão permitida em um gatilho de evento de armazenamento. Não há suporte para outros tipos de correspondência curinga para o tipo de gatilho.

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

   

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

9. Depois de configurar o gatilho, selecione Avançar: visualização de dados. Esta tela mostra os blobs existentes correspondentes à configuração do gatilho de eventos de armazenamento. Certifique-se de que tem filtros específicos. Configurar filtros muito amplos pode corresponder a um grande número de arquivos criados ou excluídos e pode afetar significativamente seu custo. Depois que as condições do filtro forem verificadas, selecione Concluir.

   

10. Para anexar um pipeline a esse gatilho, vá para a tela do pipeline e selecione Acionar>Novo/Editar. Quando o painel lateral aparecer, selecione a lista suspensa Escolher gatilho e selecione o gatilho que você criou. Selecione Next: Data preview 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 do gatilho. O gatilho de evento de armazenamento captura o caminho da pasta e o nome do arquivo do blob nas propriedades @triggerBody().folderPath e @triggerBody().fileName. Para usar os valores dessas propriedades em um pipeline, você deve mapear as propriedades para parâmetros de pipeline. Depois de mapear as propriedades para parâmetros, você pode acessar os valores capturados pelo gatilho por meio da @pipeline().parameters.parameterName expressão em todo o pipeline. Para obter uma explicação detalhada, consulte Metadados de gatilho de referência em pipelines.

    

    No exemplo anterior, o gatilho é configurado para ser acionado quando um caminho de blob que termina em .csv é criado na pasta de teste de eventos nos dados de amostra do contêiner. As folderPath propriedades e fileName capturam a localização 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 sourceFolder do pipeline e sourceFile, que podem ser usados em todo o pipeline como @pipeline().parameters.sourceFolder e @pipeline().parameters.sourceFile, respectivamente.

12. Depois de terminar, selecione Concluir.

Esquema do JSON

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

Elemento JSON	Description	Type	Valores permitidos	Necessário
âmbito	A ID de recurso do Azure Resource Manager da conta de armazenamento.	String	Azure Resource Manager ID	Sim.
eventos	O tipo de eventos que fazem com que esse gatilho seja acionado.	Matriz	Microsoft.Storage.BlobCreated, Microsoft.Storage.BlobDeleted	Sim, qualquer combinação destes valores.
blobPathBeginsWith	O caminho do blob deve começar com o padrão fornecido para o gatilho disparar. Por exemplo, /records/blobs/december/ só dispara o gatilho para blobs na december pasta sob o records contêiner.	String		Forneça um valor para pelo menos uma destas propriedades: blobPathBeginsWith ou blobPathEndsWith.
blobPathEndsWith	O caminho do blob deve terminar com o padrão fornecido para o gatilho disparar. Por exemplo, december/boxes.csv só dispara o gatilho para blobs nomeados boxes em uma december pasta.	String		Forneça um valor para pelo menos uma destas propriedades: blobPathBeginsWith ou blobPathEndsWith.
ignoreEmptyBlobs	Se os blobs de zero byte acionam ou não uma execução de pipeline. Por padrão, isso é definido como true.	Boolean	verdadeiro ou falso	N.º

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 /blobs/ segmento do caminho, conforme 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 a pasta e o nome do contêiner no JSON de gatilho.

Property	Exemplo	Description
Blob path begins with	/containername/	Recebe eventos para qualquer blob no contêiner.
Blob path begins with	/containername/blobs/foldername/	Recebe eventos para quaisquer blobs no contêiner e foldername na containername pasta.
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 nomeado file.txt na foldername pasta sob o containername contêiner.
Blob path ends with	file.txt	Recebe eventos para um blob nomeado file.txt em qualquer caminho.
Blob path ends with	/containername/blobs/file.txt	Recebe eventos para um blob nomeado file.txt sob o contêiner containername.
Blob path ends with	foldername/file.txt	Recebe eventos para um blob nomeado file.txt na foldername pasta em qualquer contêiner.

Controlo de acesso baseado em funções

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

• Para criar com êxito um novo gatilho de evento de armazenamento ou atualizar um existente, a conta do Azure conectada ao serviço precisa ter acesso apropriado à 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 permissão especial para sua instância de Grade de Eventos e você não precisa atribuir permissão RBAC especial ao Data Factory ou à entidade de serviço do Azure Synapse Analytics para a operação.

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

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

Especificamente:

• Quando você cria 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 da integração contínua e da 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 dar um passo atrás e espreitar os bastidores. Aqui estão os fluxos de trabalho de alto nível para integração entre Data Factory/Azure Synapse Analytics, Storage e Event Grid.

Criar um novo gatilho de evento de armazenamento

Este 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 textos explicativos percetí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 esta etapa.
• O controle de acesso e a verificação de permissão acontecem dentro do serviço. Antes de enviar uma solicitação para se inscrever em um evento de armazenamento, o serviço verifica a permissão para o 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 do pipeline de gatilho de evento de armazenamento

Este fluxo de trabalho de alto nível descreve como os pipelines de gatilho de eventos de armazenamento são executados através da 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 textos explicativos percetíveis no fluxo de trabalho estão relacionados a pipelines de disparo de eventos dentro do serviço:

• A Grade de Eventos usa um modelo Push que retransmite a mensagem o mais rápido possível quando o armazenamento solta a mensagem no sistema. Essa abordagem é diferente de um sistema de mensagens, como o Kafka, onde um sistema Pull é usado.

• O gatilho de evento serve como um ouvinte ativo para a mensagem de entrada e aciona corretamente o pipeline associado.

• O próprio gatilho de evento de armazenamento não faz contato direto com a conta de armazenamento.

  • Se você tiver uma atividade de cópia ou outra atividade dentro do pipeline para processar os dados na conta de armazenamento, o serviço entrará em contato direto com a conta de armazenamento usando as credenciais armazenadas no serviço vinculado. Certifique-se de que o serviço vinculado está 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údos relacionados

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