Disparar trabalhos quando novos arquivos chegarem

2025-06-18

Você pode usar gatilhos de chegada de arquivo para iniciar uma execução do seu trabalho quando novos arquivos são recebidos em um local externo, como Amazon S3, Armazenamento do Azure ou Google Cloud Storage. Esse recurso é útil quando a eficiência de um trabalho agendado é comprometida por novos dados irregulares.

Como funcionam os gatilhos para chegada de arquivos?

Os gatilhos de chegada de arquivo fazem um melhor esforço para verificar novos arquivos a cada minuto, embora isso possa ser afetado pelo desempenho do armazenamento em nuvem subjacente. Os gatilhos de chegada de arquivos não incorrem em custos adicionais além dos custos do provedor de nuvem associados à listagem de arquivos no local de armazenamento.

Um gatilho de chegada de arquivo pode ser configurado para monitorar a raiz de um local ou volume externo do Catálogo do Unity ou um subcaminho de um local ou volume externo. Por exemplo, para o volume /Volumes/mycatalog/myschema/myvolume/ do Catálogo do Unity, os seguintes são caminhos válidos para um gatilho de chegada de arquivo:

/Volumes/mycatalog/myschema/myvolume/
/Volumes/mycatalog/myschema/myvolume/mydirectory/

Um gatilho de chegada de arquivo verifica recursivamente se há novos arquivos em todos os subdiretórios do local configurado. Por exemplo, você cria um gatilho de chegada de arquivo para o local /Volumes/mycatalog/myschema/myvolume/mydirectory/ e esse local tem os seguintes subdiretórios:

/Volumes/mycatalog/myschema/myvolume/mydirectory/subdirA
/Volumes/mycatalog/myschema/myvolume/mydirectory/subdirB
/Volumes/mycatalog/myschema/myvolume/mydirectory/subdirC/subdirD

O gatilho verifica se há novos arquivos em mydirectory, subdirA, subdirB, subdirC e subdirC/subdirD.

Gatilhos acionados por eventos de chegada de arquivo

Para um desempenho ideal, o local externo deve ser habilitado para eventos de arquivo. Quando os eventos de arquivo são habilitados para um local externo, o Azure Databricks usa um serviço interno para controlar metadados de ingestão processando notificações de alteração de provedores de nuvem. Esse serviço retém os metadados dos arquivos mais recentes criados ou atualizados durante um período de retenção sem interrupção determinado pelo serviço, aumentando a eficiência do processamento de arquivos.

Minutos depois de habilitar eventos de arquivo em um local externo, os gatilhos de chegada de arquivo existentes que monitoram caminhos cobertos por esse local externo começam a se beneficiar da habilitação de eventos de arquivo e os novos gatilhos se beneficiam em segundos.

Para obter mais informações sobre as vantagens de desempenho e capacidade de eventos de arquivo em locais externos, consulte Limitações.

Antes de começar

Para usar os gatilhos de chegada de arquivos, é necessário ter os seguintes requisitos:

O espaço de trabalho deve ter o Catálogo do Unity habilitado.
Você deve usar um local de armazenamento que seja um volume ou um local externo configurado no Catálogo do Unity. Consulte O que são volumes do Catálogo do Unity? e Criar um local externo para conectar o armazenamento em nuvem ao Azure Databricks.

O Databricks recomenda que você habilite o local externo para eventos de arquivo gerenciado. Os volumes nesses locais externos obtêm suporte para eventos de arquivo por padrão. Para habilitar eventos de arquivo, você deve ser o proprietário do local externo ou ter o MANAGE privilégio no local externo. Para obter informações sobre as vantagens dos eventos de arquivo, consulte Gatilhos de chegada de arquivo com eventos de arquivo.
Você deve ter as permissões READ no local de armazenamento e CAN MANAGE no trabalho. Para obter mais informações sobre permissões de trabalho, confira ACLs de trabalhos.

Adicionar um gatilho de chegada de arquivo

Para adicionar um gatilho de chegada de arquivo para um trabalho:

Na barra lateral do workspace do Azure Databricks, clique em Jobs & Pipelines.
Opcionalmente, selecione os filtros Trabalhos e Propriedade minha .
Clique no link Nome do seu trabalho.
No painel Detalhes do trabalho à direita, clique em Adicionar gatilho.
Em Tipo de gatilho, selecione Chegada do arquivo.
Em local de armazenamento, insira a URL da raiz ou um subcaminho de um local externo do Catálogo do Unity ou a raiz ou um subcaminho de um volume do Catálogo do Unity a ser monitorado.
(Opcional) Configurar as opções avançadas:
- Tempo mínimo entre acionamentos em segundos: o tempo mínimo de espera para disparar uma execução após a conclusão de uma execução anterior. Os arquivos que chegam nesse período disparam uma execução somente após a expiração do tempo de espera. Use essa configuração para controlar a frequência da criação de execuções.
- Aguardar após a última alteração em segundos: o tempo de espera para disparar uma execução após a chegada do arquivo. A chegada de outro arquivo dentro desse período redefine o temporizador. Essa configuração pode ser usada quando os arquivos chegam em lotes e o lote inteiro precisa ser processado após a chegada de todos os arquivos.
Para validar a configuração, clique em Testar conexão.
Clique em Salvar.

Receber notificações de gatilhos de chegada de arquivo com falha

Para ser notificado se um gatilho de chegada de arquivo não for avaliado, configure notificações de destino do sistema ou email em caso de falha no trabalho. Confira Adicionar notificações sobre um trabalho.

Limitações

O caminho usado para um gatilho de chegada de arquivo não deve conter tabelas externas ou locais gerenciados de catálogos e esquemas.
O caminho usado para um gatilho de chegada de arquivo não pode conter caracteres curinga, por exemplo, * ou ?.
Se o local de armazenamento estiver configurado como um local externo no Catálogo do Unity e esse local externo estiver habilitado para eventos de arquivo:
- Um máximo de 1.000 trabalhos pode ser configurado com um gatilho de chegada de arquivo em um workspace do Azure Databricks.
- Não há limites no número de arquivos no local de armazenamento.
- Quando os gatilhos monitoram um subcaminho de um local, se um volume de local externo, o número de alterações no local raiz pode fazer com que o gatilho exceda o tempo permitido para processar as alterações. Se isso acontecer, o gatilho é colocado em um estado de erro. Você pode impedir isso configurando o gatilho para monitorar a raiz de um local. Por exemplo, você pode criar um volume do Catálogo do Unity no subcaminho, mas configurar o gatilho na raiz do volume.
- Se um arquivo existente for modificado e seus metadados ficarem fora do período de retenção contínuo, essa modificação será tratada como uma nova chegada de arquivo, disparando uma execução de trabalho. Você pode evitar isso ingerindo apenas arquivos imutáveis ou pode usar gatilhos de chegada de arquivo com o Carregador Automático para acompanhar o progresso da ingestão.
Se o local de armazenamento não estiver habilitado para eventos de arquivo:
- Somente novas execuções de gatilho de arquivos. Substituir um arquivo existente por um arquivo com o mesmo nome não dispara uma execução.
- Um máximo de 50 trabalhos pode ser configurado com um gatilho de chegada de arquivo nesses locais em um workspace do Azure Databricks.
- O local de armazenamento pode conter até 10.000 arquivos. Se o local de armazenamento configurado for um subcaminho de um local ou volume externo do Catálogo do Unity, o limite de 10 mil arquivos se aplicará ao subcaminho e não à raiz do local de armazenamento. Por exemplo, a raiz do local de armazenamento pode conter mais de 10 mil arquivos em seus subdiretórios, mas o subdiretório configurado não pode exceder o limite de 10 mil arquivos.

Consulte também Limitações de eventos de arquivo.