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 Data Factory ou do Synapse.
A EDA (arquitetura controlada por evento) é um padrão de integração de dados comum que envolve produção, detecção, consumo e reação a eventos. Normalmente, os cenários de integração de dados exigem que os clientes disparem pipelines com base em eventos que acontecem na conta de armazenamento, como a chegada ou a exclusão de um arquivo em sua conta do Armazenamento de Blobs do Azure. Pipelines do Data Factory e do Synapse são nativamente integrados à Grade de Eventos do Azure, que permite o acionamento de pipelines em um evento.
Observação
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 obter mais informações, confira 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 EventGrid e do EventSubscription.
Importante
Se estiver usando esse recurso no Azure Synapse Analytics, verifique se a sua assinatura também está registrada no provedor de recursos do Data Factory ou você receberá um erro indicando falha na criação de uma "assinatura de evento".
Observação
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 Grade de Eventos do Azure. Você pode conceder acesso de armazenamento a serviços confiáveis do Azure, como a Grade de Eventos, seguindo a documentação de Armazenamento ou configurar pontos de extremidade privados para a Grade de Eventos que são mapeados para o espaço de endereço da VNet, seguindo a documentação da Grade de Eventos
Como 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 de pipeline do Azure Data Factory ou do Synapse.
Alternar para a guia Editar Data Factory ou a guia Integrar no Azure Synapse.
Selecione Gatilho no menu e depois selecione Novo/Editar.
Na página Adicionar Gatilhos, selecione Escolher gatilho... e, em seguida, selecione +Novo.
Selecionar o tipo de gatilho Evento de Armazenamento
Selecione sua conta de armazenamento na lista suspensa de assinatura do Azure ou manualmente usando a ID do recurso da conta de armazenamento. Escolha em qual contêiner você deseja que os eventos ocorram. A seleção de contêiner é obrigatória, mas lembre-se de que a seleção de todos os contêineres pode levar a um grande número de eventos.
Observação
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 SFTP, também precisará especificar a API de Dados SFTP na seção de filtragem. Devido a uma limitação da Grade de Eventos do Azure, o Azure Data Factory dá suporte apenas a no máximo de 500 gatilhos de eventos de armazenamento por conta de armazenamento. Se você atingir o limite, entre em contato com o suporte para obter recomendações e aumente o limite após a avaliação da equipe de Grade de Eventos.
Observação
Para criar um novo Gatilho de Evento de Armazenamento ou modificar um existente, a conta do Azure usada para fazer logon no serviço e publicar o gatilho de evento de armazenamento deve ter a permissão de controle de acesso baseado em função (RBAC do Azure) na conta de armazenamento. Nenhuma permissão adicional é necessária: a entidade de serviço do Azure Data Factory e do Azure Synapse 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.
As propriedades Caminho do blob começa com e Caminho do blob termina com permitem especificar os contêineres, as pastas e os 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. É possível usar diversos padrões tanto para o caminho do Blob que começa com como para o caminho do Blob que termina com propriedades, conforme mostrado nos exemplos mais adiante neste artigo.
- O caminho do blob começa com: O caminho do blob deve começar com um caminho de pasta. Os valores válidos incluem
2018/e2018/april/shoes.csv. Este campo não poderá ser selecionado se um contêiner não estiver selecionado. - O caminho de blob termina com: O caminho do blob deve terminar com uma extensão ou nome de arquivo. Os valores válidos incluem
shoes.csve.csv. O nome do contêiner e da pasta, quando especificados, devem ser separados por um segmento de/blobs/. Por exemplo, um contêiner chamado 'ordens' 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.csvdisparará um evento em qualquer arquivo chamadoshoes.csvna pasta a chamada “abril” em qualquer contêiner. - Observe que o Caminho de blob começa com e termina com é o único padrão correspondente permitido no gatilho de evento de armazenamento. Não há suporte para outros tipos de correspondência de curingas para o tipo de gatilho.
- O caminho do blob começa com: O caminho do blob deve começar com um caminho de pasta. Os valores válidos incluem
Selecione se o gatilho responderá a um evento de Blob criado, Blob excluído ou ambos. No local de armazenamento especificado, cada evento vai disparar os pipelines do Data Factory ou do Synapse associados ao gatilho.
Selecione se o gatilho ignora ou não os blobs com zero byte.
Depois de configurar o gatilho, clique em 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/excluídos e pode impactar significativamente o seu custo. Depois que as condições de filtro tiverem sido verificadas, clique em Concluir.
Para anexar um pipeline a esse gatilho, acesse a tela do pipeline, clique em Gatilho e selecione Novo/Editar. Quando a navegação lateral aparecer, clique na lista suspensa Escolher gatilho... e selecione o gatilho criado. Clique em Avançar: Visualização de dados para confirmar se a configuração está correta. Em seguida, clique em Avançar para validar se a visualização de dados está correta.
Se o pipeline tiver parâmetros, você poderá especificá-los na navegação lateral do parâmetro de execução do gatilho. O gatilho de evento de armazenamento captura o nome de arquivo e o caminho de pasta do blob para as propriedades
@triggerBody().folderPathe@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.parameterNameem todo o pipeline. Para obter uma explicação detalhada, consulte 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 de sample-data/event-testing,
@triggerBody().folderPathtem um valor desample-data/event-testinge@triggerBody().fileNametem um valor demoviesDB.csv. Esses valores são mapeados, no exemplo, para os parâmetros de pipelinesourceFolderesourceFile, que podem ser usados em todo o pipeline como@pipeline().parameters.sourceFoldere@pipeline().parameters.sourceFilerespectivamente.Clique em Concluir quando terminar.
JSON schema
A seguinte tabela fornece uma visão geral dos elementos do esquema relacionados aos gatilhos de eventos de armazenamento:
| Elemento JSON | Descrição | Tipo | Valores permitidos | Necessário |
|---|---|---|---|---|
| escopo | 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 dispararão ou não uma execução de pipeline. Por padrão, isso é 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. Em blobPathBeginsWith, a interface do usuário adicionará automaticamente /blobs/ entre o nome da pasta e do contêiner no JSON de gatilho.
Observação
Os gatilhos de chegada de arquivo não são recomendados 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.
| Propriedade | Exemplo | Descrição |
|---|---|---|
| O caminho de blob começa com | /containername/ |
Recebe eventos para qualquer blob no contêiner. |
| O caminho de blob começa com | /containername/blobs/foldername/ |
Recebe eventos para todos os blobs no contêiner containername e na pasta foldername. |
| O caminho de blob começa com | /containername/blobs/foldername/subfoldername/ |
Você também pode fazer referência a uma subpasta. |
| O caminho de blob começa com | /containername/blobs/foldername/file.txt |
Recebe eventos para um blob denominado file.txt na pasta foldername no contêiner containername. |
| O caminho de blob termina com | file.txt |
Recebe eventos para um blob denominado file.txt em qualquer caminho. |
| O caminho de blob termina com | /containername/blobs/file.txt |
Recebe eventos para um blob denominado file.txt no contêiner containername. |
| O caminho de blob termina com | 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 Azure Data Factory e do Synapse 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 de e disparar pipelines vinculados para eventos de blob.
- Para criar um novo ou atualizar um gatilho de evento de armazenamento 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 Acesso Negado.
- O Azure Data Factory e o Azure Synapse não precisam de permissão especial para sua Grade de Eventos e você não precisa atribuir permissão especial de RBAC para a entidade de serviço do Data Factory ou do Azure Synapse para a operação.
Qualquer uma das seguintes configurações do RBAC funciona para o gatilho de evento 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 acima
- Na publicação por meio da CI/CD, a conta usada para publicar o modelo do ARM no alocador de teste ou de produção precisa ter a permissão acima.
Para entender como o serviço cumpre as duas promessas, vamos voltar uma etapa e observar por trás dos bastidores. Estes são os fluxos de trabalho de alto nível para integração entre Azure Data Factory/Azure Synapse, Armazenamento e Grade de Eventos.
Criar um novo Gatilho de Evento de Armazenamento
Este fluxo de trabalho de alto nível descreve como o Azure Data Factory interage com a Grade de Eventos para criar um Gatilho de Evento de Armazenamento. No Azure Synapse, o fluxo de dados é o mesmo, com pipelines do Synapse que levam a função do Data Factory no diagrama abaixo.
Dois tempos de chamada perceptíveis dos fluxos de trabalho:
O Azure Data Factory e o Azure Synapse não fazem contato direto com a conta de armazenamento. A solicitação para criar uma assinatura é, em vez disso, retransmitida e processada pela Grade de Eventos. Portanto, o serviço não precisa de permissão para a conta de armazenamento nesta 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 o evento de armazenamento, ele verifica a permissão do usuário. Mais especificamente, ele verifica se a conta do Azure que entrou e tentou 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
Esses fluxos de trabalho de alto nível descrevem como o Gatilho de evento de armazenamento dispara a execução de pipeline por meio da Grade de Eventos. No Azure Synapse, o fluxo de dados é o mesmo, com pipelines do Synapse que levam a função do Data Factory no diagrama abaixo.
Há três chamadas perceptíveis no fluxo de trabalho relacionadas aos pipelines de disparo de eventos dentro do 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. Isso é diferente do sistema de mensagens, como Kafka, em que um sistema de pull é usado.
O gatilho de evento serve como um ouvinte ativo para a mensagem de entrada e aciona corretamente o pipeline associado.
O Gatilho de Evento de Armazenamento não faz contato direto com a Conta de armazenamento
- Dito isso, se você tiver uma cópia ou outra atividade no pipeline para processar os dados na Conta de armazenamento, o serviço fará contato direto com o Armazenamento, usando as credenciais armazenadas no Serviço Vinculado. Verifique se o serviço vinculado está configurado adequadamente
- No entanto, se você não fizer nenhuma referência à Conta de armazenamento no pipeline, não será necessário conceder permissão ao serviço para acessar a Conta de armazenamento
Conteúdo relacionado
- Para obter mais informações detalhadas sobre gatilhos, consulte Gatilhos e execução de pipeline.
- Saiba como referenciar os metadados de gatilho no pipeline, confiraReferenciar Metadados de Gatilho em Execuções de Pipeline