Pular para o conteúdo principal
Última atualização em

Configurar a transmissão do Auto Loader no modo de notificação de arquivo

Esta página descreve como configurar a transmissão Auto Loader para usar o modo de notificação de arquivo para descobrir e ingerir dados na nuvem de forma incremental.

No modo de notificação de arquivos, o Auto Loader configura automaticamente um serviço de notificação e um serviço de fila que se inscreve em eventos de arquivos do diretório de entrada. Você pode usar notificações de arquivos para aumentar a capacidade Auto Loader de processar milhões de arquivos por hora. Em comparação com o modo de listagem de diretórios, o modo de notificação de arquivos é mais rápido e escalável. Além disso, você pode alternar entre notificações de arquivos e listagem de diretórios a qualquer momento, mantendo as garantias de processamento de dados exatamente uma vez.

Para obter uma referência completa de todas as configurações Auto Loader , incluindo opções de notificação de arquivos e opções de autenticação específicas cloud , consulte OpçõesAuto Loader.

nota

Embora o modo de notificação de arquivos com eventos de arquivo melhore o custo e a escalabilidade, ele não garante a ordem em que os arquivos são descobertos ou processados. Projete seu pipeline para lidar com a chegada de arquivos fora de ordem. Para obter orientações, consulte Lidar com dados fora de ordem.

Modo de notificação de arquivo com e sem eventos de arquivo habilitados em locais externos​

Há duas maneiras de configurar o Auto Loader para usar o modo de notificação de arquivo:

  • (Recomendado) Eventos de arquivo: Você usa uma única fila de notificação de arquivo para todas as transmissões que processam arquivos de um determinado local externo. Essa abordagem apresenta as seguintes vantagens em relação ao modo clássico de notificação de arquivos:

    • Databricks pode configurar eventos de inscrição e de arquivo em sua account de armazenamento cloud para você, sem exigir que você forneça credenciais adicionais ao Auto Loader usando uma credencial de serviço ou outras opções de autenticação específicas cloud . Consulte Configurar eventos de arquivo para um local externo.
    • O senhor tem menos políticas de serviço account para criar em seu armazenamento em nuvem account.
    • Como não é mais necessário criar uma fila para cada transmissão Auto Loader , fica mais fácil evitar atingir os limites de notificação do provedor cloud listados no recurso de nuvem usado no modo clássico de notificação de arquivos Auto Loader.
    • Databricks Gerenciar automaticamente o ajuste dos requisitos de recurso, para que o senhor não precise ajustar parâmetros como cloudFiles.fetchParallelism.
    • A funcionalidade de limpeza significa que o senhor não precisa se preocupar tanto com o ciclo de vida das notificações que são criadas na nuvem, como quando uma transmissão é excluída ou totalmente atualizada.

  • Modo clássico de notificação de arquivos: Você gerencia filas de notificação de arquivos para cada transmissão Auto Loader separadamente. O Auto Loader configura automaticamente um serviço de notificação e um serviço de fila que se inscreve em eventos de arquivo do diretório de entrada. Essa é a abordagem clássica.

Se você utiliza o Auto Loader no modo de listagem de diretórios, a Databricks recomenda migrar para o modo de notificação de arquivos com eventos de arquivo. O Auto Loader com eventos de arquivo oferece melhorias significativas de desempenho. Comece por ativar os eventos de arquivo para o seu local externo e, em seguida, defina cloudFiles.useManagedFileEvents na configuração de transmissão do seu Auto Loader .

Use o modo de notificação de arquivo com eventos de arquivo​

Esta seção descreve como criar e atualizar transmissões Auto Loader para usar eventos de arquivo. A Databricks recomenda enfaticamente o seguinte ao usar o modo de notificação de arquivos:

  • Utilizar volumes Unity Catalog : Crie um volume externo separado para cada caminho ou subdiretório do qual Auto Loader carrega dados. Forneça caminhos de volume (por exemplo, /Volumes/catalog/schema/volume) para o Auto Loader em vez de URLs de armazenamento cloud (por exemplo, s3://bucket/path). Isso melhora o desempenho da descoberta de arquivos, pois o serviço de eventos de arquivos pode restringir a descoberta apenas aos objetos relevantes, em vez de iterar sobre todos os objetos no local externo.
  • Utilize um volume separado para cada subcaminho: Se você tiver várias transmissões Auto Loader lendo de diferentes subcaminhos no mesmo local externo, crie um volume dedicado para cada subcaminho em vez de compartilhar um único volume. Isso evita a sobrecarga desnecessária de descoberta de arquivos e ajuda a prevenir a limitação de taxa.

Antes de começar​

A configuração de eventos de arquivo requer:

  • Um Databricks workspace que está habilitado para Unity Catalog.
  • Permissão para criar credenciais de armazenamento e objetos de localização externa no Unity Catalog.

Auto Loader transmissão com eventos de arquivos requeridos:

  • Computar em Databricks Runtime 14.3 LTS ou acima.

Instruções de configuração​

As instruções a seguir se aplicam se o senhor estiver criando uma nova transmissão Auto Loader ou migrando a transmissão existente para usar o modo de notificação de arquivo atualizado com eventos de arquivo:

  1. Crie uma credencial de armazenamento e um local externo em Unity Catalog que conceda acesso ao local de origem no armazenamento cloud para sua transmissão Auto Loader.
  2. Ative os eventos de arquivo para o local externo. Consulte Configurar eventos de arquivo para um local externo.
  3. Quando o senhor cria uma nova transmissão Auto Loader ou edita uma já existente para trabalhar com o local externo:
    • Se o senhor tiver notificações baseadas em Auto Loader transmissão que consomem dados do local externo, desative-as e exclua o recurso de notificação associado.
    • Certifique-se de que pathRewrites não esteja definido (essa não é uma opção comum).
    • Analise a lista de configurações que o site Auto Loader ignora ao gerenciar notificações de arquivo usando eventos de arquivo. Evite-os na nova transmissão Auto Loader e remova-os da transmissão existente que o senhor está migrando para esse modo.
    • Defina a opção cloudFiles.useManagedFileEvents como true em seu código do Auto Loader.

Por exemplo:

Python
autoLoaderStream = (spark.readStream
  .format("cloudFiles")
  ...
  .options("cloudFiles.useManagedFileEvents", True)
  ...)

Se você estiver usando o pipeline declarativo LakeFlow Spark e já tiver um pipeline com uma tabela de transmissão, atualize-o para incluir a opção useManagedFileEvents :

SQL
CREATE OR REFRESH STREAMING LIVE TABLE <table-name>
AS SELECT <select clause expressions>
  FROM STREAM read_files('abfss://path/to/external/location/or/volume',
                   format => '<format>',
                   useManagedFileEvents => 'True'
                   ...
                   );

Configurações não suportadas do Auto Loader​

As seguintes configurações do site Auto Loader não são compatíveis quando a transmissão usa eventos de arquivo:

Contexto

Alterar

useIncremental

Você não precisa mais decidir entre a eficiência das notificações de arquivos e a simplicidade da listagem de diretórios. O Auto Loader com eventos de arquivo vem em um modo.

useNotifications

Há apenas uma inscrição de evento de fila e armazenamento por local externo.

cloudFiles.fetchParallelism

O Auto Loader com eventos de arquivo não oferece uma otimização de paralelismo manual.

cloudFiles.backfillInterval

O Databricks lida com o backfill automaticamente para locais externos que estão habilitados para eventos de arquivo.

cloudFiles.pathRewrites

Essa opção se aplica somente quando o senhor monta locais de dados externos no DBFS, que está obsoleto.

resourceTags

O senhor deve definir as tags de recurso usando o console de nuvem.

Para obter as melhores práticas de gerenciamento de eventos de arquivo, consulte Melhores práticas para Auto Loader com eventos de arquivo.

Limitações do Auto Loader com eventos de arquivo​

O serviço de eventos de arquivos otimiza a descoberta de arquivos armazenando em cache os arquivos criados mais recentemente. Se o Auto Loader for executado com pouca frequência, esse cache poderá expirar e o Auto Loader voltará a usar a listagem de diretórios para descobrir arquivos e atualizar o cache. Para evitar esse cenário, invoque o Auto Loader pelo menos uma vez a cada sete dias.

Para obter uma lista geral de limitações em eventos de arquivo, consulte Limitações de eventos de arquivo.

gerenciar filas de notificação de arquivos para cada transmissão Auto Loader separadamente (clássico)​

No modo clássico de notificação de arquivos, Auto Loader configura automaticamente um serviço de notificação e uma fila dedicados para cada transmissão. Essa abordagem exige que você gerencie filas de notificação por transmissão e forneça credenciais de autenticação para a criação de recursos cloud . A Databricks recomenda o modo de notificação de arquivos para novas cargas de trabalho.

importante

Você precisa de permissões elevadas para configurar automaticamente a infraestrutura em nuvem para o modo de notificação de arquivos. Entre em contato com o administrador da nuvem ou com o administrador do site workspace. Veja:

No modo clássico de notificação de arquivos, Auto Loader configura automaticamente um serviço de notificação e um serviço de fila para cada transmissão que se inscreve para receber eventos de arquivos do diretório de entrada. Você gerencia as filas de notificação de cada transmissão Auto Loader separadamente.

atenção

O Auto Loader não suporta a alteração do caminho de origem no modo clássico de notificação de arquivos. Se você alterar o caminho, poderá não conseguir importar arquivos que já estejam presentes no novo local no momento da atualização do caminho.

recurso de nuvem usado no modo clássico de notificação de arquivos Auto Loader​

Auto Loader pode configurar automaticamente as notificações de arquivos para o senhor quando definir a opção cloudFiles.useNotifications como true e fornecer as permissões necessárias para criar recursos na nuvem. Além disso, talvez o senhor precise fornecer opções adicionais para conceder autorização ao Auto Loader para criar esses recursos.

A tabela a seguir lista os recursos que Auto Loader cria para cada provedor cloud .

Armazenamento em nuvem

inscrição serviço

Fila de serviço

Prefixo *

Limite **

Amazon S3

SNS DA AWS

AWS SQS

ingestão automática de databricks

100 por bucket S3

ADLS

Grade de eventos do Azure

Armazenamento de filas do Azure

Databricks

500 por armazenamento account

GCS

Google Pub/Sub

Google Pub/Sub

ingestão automática de databricks

100 por balde de GCS

Armazenamento de Blobs do Azure

Grade de eventos do Azure

Armazenamento de filas do Azure

Databricks

500 por armazenamento account

* O site Auto Loader nomeia o recurso com esse prefixo.

** Quantos pipelines de notificação de arquivos concorrente podem ser iniciados

Auto Loader Se precisar executar mais transmissões baseadas em notificações de arquivos do que o permitido por esses limites, o senhor pode usar eventos de arquivos ou um serviço como AWS Lambda, Azure Functions ou Google Cloud Functions para distribuir as notificações de uma única fila que escuta um contêiner ou bucket inteiro em filas específicas de diretório.

Eventos clássicos de notificação de arquivos​

Amazon S3 Fornece um evento ObjectCreated quando um arquivo é carregado em um bucket S3, independentemente de ter sido carregado por um put ou por várias partes upload.

Azure O Data Lake Storage fornece diferentes notificações de eventos para arquivos que aparecem no contêiner de armazenamento.

  • O Auto Loader escuta o evento FlushWithClose para processar um arquivo.
  • Auto Loader A transmissão suporta a ação RenameFile para descobrir arquivos. RenameFile exigem uma solicitação de API ao sistema de armazenamento para obter o tamanho do arquivo renomeado.
  • Auto Loader A transmissão criada com o site Databricks Runtime 9.0 e posterior suporta a ação RenameDirectory para descobrir arquivos. RenameDirectory exigem solicitações de API ao sistema de armazenamento para listar o conteúdo do diretório renomeado.

Google Cloud Storage fornece um evento OBJECT_FINALIZE quando um arquivo é carregado, o que inclui sobrescritos e cópias de arquivos. O upload com falha não gera esse evento.

nota

Os provedores de nuvem não garantem a entrega de 100% de todos os eventos de arquivo em condições muito raras e não fornecem SLAs rígidos sobre a latência dos eventos de arquivo. A Databricks recomenda que o senhor acione backfills regulares com o Auto Loader usando a opção cloudFiles.backfillInterval para garantir que todos os arquivos sejam descobertos dentro de um determinado SLA se a integridade dos dados for um requisito. Ativar preenchimentos regulares não causa duplicatas.

Permissões necessárias para configurar a notificação de arquivo para Azure data lake Storage e Azure Blob Storage​

Você deve ter permissões de leitura para o diretório de entrada. Consulte Azure Blob Storage.

Para usar o modo de notificação de arquivos, você precisa fornecer credenciais de autenticação para configurar e acessar o serviço de notificação de eventos. Você pode autenticar-se usando um dos seguintes métodos:

Após obter as credenciais de autenticação, atribua as permissões necessárias usando uma das seguintes abordagens:

  • Funções integradas Azure :

    • Atribua ao conector de acesso as seguintes funções para a account de armazenamento onde reside o caminho de entrada:

      • Colaborador: Esta função é responsável por configurar recursos em sua account de armazenamento, como filas e inscrição de eventos.
      • Colaborador de Dados da Fila de Armazenamento: Esta função consiste em executar operações na fila, como recuperar e excluir mensagens das filas. Essa função é necessária apenas quando você fornece uma entidade de serviço sem strings de conexão.

    • Atribua ao conector de acesso a seguinte função ao grupo de recursos relacionado:

  • Função personalizada: Se você estiver preocupado em conceder as permissões necessárias para as funções anteriores, poderá criar uma função personalizada com as seguintes permissões. Após criar a função, atribua-a ao seu conector de acesso. Para obter mais informações, consulte Atribuir funções Azure usando o portal Azure.

    JSON
    "permissions": [
      {
        "actions": [
          "Microsoft.EventGrid/eventSubscriptions/write",
          "Microsoft.EventGrid/eventSubscriptions/read",
          "Microsoft.EventGrid/eventSubscriptions/delete",
          "Microsoft.EventGrid/locations/eventSubscriptions/read",
          "Microsoft.Storage/storageAccounts/read",
          "Microsoft.Storage/storageAccounts/write",
          "Microsoft.Storage/storageAccounts/queueServices/read",
          "Microsoft.Storage/storageAccounts/queueServices/write",
          "Microsoft.Storage/storageAccounts/queueServices/queues/write",
          "Microsoft.Storage/storageAccounts/queueServices/queues/read",
          "Microsoft.Storage/storageAccounts/queueServices/queues/delete"
      ],
        "notActions": [],
        "dataActions": [
          "Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete",
          "Microsoft.Storage/storageAccounts/queueServices/queues/messages/read",
          "Microsoft.Storage/storageAccounts/queueServices/queues/messages/write",
          "Microsoft.Storage/storageAccounts/queueServices/queues/messages/process/action"
        ],
        "notDataActions": []
      }
    ]

    Configurações de permissões do Auto Loader

Permissões necessárias para configurar a notificação de arquivos para o Amazon S3​

Você deve ter permissões de leitura para o diretório de entrada. Consulte os detalhes da conexão S3 para obter mais detalhes.

Para usar o modo de notificação de arquivo, anexe o seguinte documento de política JSON ao seu usuário ou função IAM. Este IAM role é necessário para criar uma credencial de serviço para que o Auto Loader possa se autenticar.

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DatabricksAutoLoaderSetup",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketNotification",
        "s3:PutBucketNotification",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes",
        "sns:SetTopicAttributes",
        "sns:CreateTopic",
        "sns:TagResource",
        "sns:Publish",
        "sns:Subscribe",
        "sqs:CreateQueue",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:SetQueueAttributes",
        "sqs:TagQueue",
        "sqs:ChangeMessageVisibility",
        "sqs:PurgeQueue"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket-name>",
        "arn:aws:sqs:<region>:<account-number>:databricks-auto-ingest-*",
        "arn:aws:sns:<region>:<account-number>:databricks-auto-ingest-*"
      ]
    },
    {
      "Sid": "DatabricksAutoLoaderList",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": "*"
    },
    {
      "Sid": "DatabricksAutoLoaderTeardown",
      "Effect": "Allow",
      "Action": ["sns:Unsubscribe", "sns:DeleteTopic", "sqs:DeleteQueue"],
      "Resource": [
        "arn:aws:sqs:<region>:<account-number>:databricks-auto-ingest-*",
        "arn:aws:sns:<region>:<account-number>:databricks-auto-ingest-*"
      ]
    }
  ]
}

Substitua os seguintes espaços reservados pelos valores do seu ambiente:

  • <bucket-name>: O nome do bucket S3 onde a transmissão lerá os arquivos, por exemplo, auto-logs. Você pode usar * como curinga, por exemplo, databricks-*-logs. Para descobrir o bucket S3 subjacente ao seu caminho DBFS, o senhor pode listar todos os pontos de montagem DBFS em um Notebook executando %fs mounts.
  • <region>: A região do AWS em que o bucket do S3 reside, por exemplo, us-west-2. Se você não quiser especificar a região, use *.
  • <account-number>: O número account AWS que possui o bucket S3 , por exemplo, 123456789012. Se você não quiser especificar o número account , use *.

As strings databricks-auto-ingest-* na especificação ARN do SQS e SNS são o prefixo de nome que a fonte cloudFiles usa ao criar o serviço SQS e SNS. Como Databricks configura o serviço de notificação na execução inicial da transmissão, você pode utilizar uma política com permissões reduzidas após a execução inicial (por exemplo, para interromper a transmissão e depois reiniciá-la).

nota

A política anterior diz respeito apenas às permissões necessárias para configurar o serviço de notificação de arquivos, ou seja, notificação de bucket S3 , SNS e serviço SQS, e pressupõe que você já tenha acesso de leitura ao bucket S3 . Se você precisar adicionar permissões somente leitura ao S3, adicione o seguinte à lista Action na declaração DatabricksAutoLoaderSetup no documento JSON:

  • s3:ListBucket
  • s3:GetObject

Permissões reduzidas após a configuração inicial​

Você só precisa das permissões de configuração do recurso descritas acima durante a execução inicial da transmissão. Após a primeira execução, você pode alternar para a seguinte política do IAM com permissões reduzidas. No entanto, com permissões reduzidas, você não poderá iniciar novas consultas de transmissão, recriar recursos após falhas, como a exclusão acidental de uma fila SQS, ou usar a API de gerenciamento de recursos cloud para listar ou remover recursos.

JSON
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DatabricksAutoLoaderUse",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketNotification",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes",
        "sns:TagResource",
        "sns:Publish",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:TagQueue",
        "sqs:ChangeMessageVisibility",
        "sqs:PurgeQueue"
      ],
      "Resource": [
        "arn:aws:sqs:<region>:<account-number>:<queue-name>",
        "arn:aws:sns:<region>:<account-number>:<topic-name>",
        "arn:aws:s3:::<bucket-name>"
      ]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetBucketLocation", "s3:ListBucket"],
      "Resource": ["arn:aws:s3:::<bucket-name>"]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:PutObjectAcl", "s3:GetObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::<bucket-name>/*"]
    },
    {
      "Sid": "DatabricksAutoLoaderListTopics",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": "arn:aws:sns:<region>:<account-number>:*"
    }
  ]
}

Permissões necessárias para configurar a notificação de arquivo para o GCS​

Para usar o modo de notificação de arquivos, você precisa configurar as permissões:

  • Certifique-se de ter permissões list e get no seu bucket do GCS e em todos os objetos. Para obter detalhes, consulte a documentação do Google sobre permissões do IAM.

  • Adicione a função Pub/Sub Publisher ao serviço GCS account. Isso permite que o site account publique mensagens de notificação de eventos dos seus buckets GCS no Google Cloud Pub/Sub.

  • Adicione as seguintes permissões à account de serviço usada para o recurso do Google Cloud Pub/Sub. Você pode criar uma função personalizada do IAM com essas permissões ou atribuir funções preexistentes do GCP para cobri-las. Databricks cria automaticamente essa account de serviço quando você cria uma credencial de serviço. O suporte a credenciais de serviço está disponível no Databricks Runtime 16.1 e versões superiores.

    pubsub.subscriptions.consume
    pubsub.subscriptions.create
    pubsub.subscriptions.delete
    pubsub.subscriptions.get
    pubsub.subscriptions.list
    pubsub.subscriptions.update
    pubsub.topics.attachSubscription
    pubsub.topics.detachSubscription
    pubsub.topics.create
    pubsub.topics.delete
    pubsub.topics.get
    pubsub.topics.list
    pubsub.topics.update

Localizar a conta do serviço GCS​

Acesse Armazenamento em nuvem > Configurações no Console do Google Cloud para o projeto correspondente. A seção da conta do serviço de armazenamento em nuvem contém o email da account do serviço GCS .

GCS conta de serviços

Criação de uma função personalizada do Google Cloud IAM para notificação de arquivos Mode​

Acesse IAM e administração > Funções no console do Google Cloud para o projeto correspondente. Em seguida, crie uma função ou atualize uma função existente. Na página Criar função , selecione Adicionar permissões . No menu, adicione as permissões desejadas à função.

Funções personalizadas do GCP IAM

Configurar ou gerenciar manualmente o recurso de notificação de arquivo​

Usuários com privilégios podem configurar ou gerenciar manualmente o recurso de notificação de arquivos. Para configurar o serviço de notificação de arquivos por meio do provedor cloud e especificar o identificador da fila, consulte Opções de notificação de arquivos. Para usar APIs Scala para criar ou gerenciar o serviço de notificações e filas:

nota

Você deve ter as permissões apropriadas para configurar ou modificar a infraestrutura em nuvem. Consulte a documentação de permissões do Azure, S3 ou GCS.

Passo 1: Crie um ResourceManager na AWS, Azure ou Google Cloud.​

Python

# Create a ResourceManager in AWS

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesAWSResourceManager \
  .newManager() \
  .option("cloudFiles.region", <region>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .create()

# Using an AWS access key and secret key
manager = spark._jvm.com.databricks.sql.CloudFilesAWSResourceManager \
  .newManager() \
  .option("cloudFiles.region", <region>) \
  .option("cloudFiles.awsAccessKey", <aws-access-key>) \
  .option("cloudFiles.awsSecretKey", <aws-secret-key>) \
  .option("cloudFiles.roleArn", <role-arn>) \
  .option("cloudFiles.roleExternalId", <role-external-id>) \
  .option("cloudFiles.roleSessionName", <role-session-name>) \
  .option("cloudFiles.stsEndpoint", <sts-endpoint>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

Python

# Create a ResourceManager in Azure

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesAzureResourceManager \
  .newManager() \
  .option("cloudFiles.resourceGroup", <resource-group>) \
  .option("cloudFiles.subscriptionId", <subscription-id>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .option("path", <path-to-specific-container-and-folder>) \
  .create()

# Using an Azure service principal
manager = spark._jvm.com.databricks.sql.CloudFilesAzureResourceManager \
  .newManager() \
  .option("cloudFiles.connectionString", <connection-string>) \
  .option("cloudFiles.resourceGroup", <resource-group>) \
  .option("cloudFiles.subscriptionId", <subscription-id>) \
  .option("cloudFiles.tenantId", <tenant-id>) \
  .option("cloudFiles.clientId", <service-principal-client-id>) \
  .option("cloudFiles.clientSecret", <service-principal-client-secret>) \
  .option("path", <path-to-specific-container-and-folder>) \
  .create()

Python

# Create a ResourceManager in GCP

# Using a Databricks service credential
manager = spark._jvm.com.databricks.sql.CloudFilesGCPResourceManager \
  .newManager() \
  .option("cloudFiles.projectId", <project-id>) \
  .option("databricks.serviceCredential", <service-credential-name>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

# Using a Google service account
manager = spark._jvm.com.databricks.sql.CloudFilesGCPResourceManager \
  .newManager() \
  .option("cloudFiles.projectId", <project-id>) \
  .option("cloudFiles.client", <client-id>) \
  .option("cloudFiles.clientEmail", <client-email>) \
  .option("cloudFiles.privateKey", <private-key>) \
  .option("cloudFiles.privateKeyId", <private-key-id>) \
  .option("path", <path-to-specific-bucket-and-folder>) \
  .create()

Passo 2: Use o gerenciador de recursos para configurar, view e encerrar o serviço de notificação de arquivos.​

Python

# Set up a queue and a topic subscribed to the path provided in the manager.
manager.setUpNotificationServices(<resource-suffix>)

# List notification services created by <AL>.
from pyspark.sql import DataFrame
df = DataFrame(manager.listNotificationServices(), spark)

# Tear down the notification services created for a specific stream ID.
# Stream ID is a GUID string that you can find in the list result above.
manager.tearDownNotificationServices(<stream-id>)

Use setUpNotificationServices(<resource-suffix>) para criar uma fila e uma inscrição com o nome <prefix>-<resource-suffix> (o prefixo depende do sistema de armazenamento resumido no recurso de nuvem usado no modo clássico de notificação de arquivo Auto Loader ). Se já existir um recurso com o mesmo nome, o Databricks reutiliza o recurso existente em vez de criar um novo. Esta função retorna um identificador de fila que você pode passar para a fonte cloudFiles usando o identificador em Opções de notificação de arquivo. Isso permite que o usuário de origem cloudFiles tenha menos permissões do que o usuário que cria o recurso.

Forneça a opção "path" para newManager somente se estiver chamando setUpNotificationServices. Não é necessário para listNotificationServices ou tearDownNotificationServices. Este é o mesmo path que você usa ao executar uma consulta de transmissão.

A matriz a seguir indica quais métodos de API são suportados em qual Databricks Runtime para cada tipo de armazenamento:

Armazenamento em nuvem

API de configuração

Lista API

Desmontar a API

Amazon S3

Todas as versões

Todas as versões

Todas as versões

ADLS

Todas as versões

Todas as versões

Todas as versões

GCS

Databricks Runtime 9.1e acima

Databricks Runtime 9.1e acima

Databricks Runtime 9.1e acima

Armazenamento de Blobs do Azure

Todas as versões

Todas as versões

Todas as versões

Limpar o recurso de notificação de eventos criado pelo Auto Loader​

Auto Loader não elimina automaticamente o recurso de notificação de arquivo. Para desativar o recurso de notificação de arquivo, o senhor deve usar o gerenciador de recurso na nuvem, conforme mostrado na seção anterior. O senhor também pode excluir esses recursos manualmente usando a UI do provedor de nuvem ou APIs.

Solucionar erros comuns​

Esta seção descreve erros comuns ao usar o Auto Loader com o modo de notificação de arquivo e como resolvê-los.

Falha ao criar a inscrição na grade de eventos​

Se você vir a seguinte mensagem de erro ao executar Auto Loader pela primeira vez, significa que você não registrou o Event Grid como um provedor de recursos na assinatura Azure .

java.lang.RuntimeException: Failed to create event grid subscription.

Para registrar o Event Grid como um provedor de recursos, faça o seguinte:

  1. No portal Azure, acesse sua inscrição.
  2. Selecione os provedores de recursos na seção Configurações.
  3. registro do provedor Microsoft.EventGrid.

Autorização necessária para realizar operações de inscrição no Event Grid​

Se o senhor vir a seguinte mensagem de erro ao executar Auto Loader pela primeira vez, confirme se a função Contributor está atribuída à entidade de serviço do Event Grid e ao storage account.

403 Forbidden ... does not have authorization to perform action 'Microsoft.EventGrid/eventSubscriptions/[read|write]' over scope ...

O cliente Event Grid ignora o proxy​

Em Databricks Runtime 15.2 e acima, as conexões do Event Grid em Auto Loader usam as configurações de proxy das propriedades do sistema em default. No Databricks Runtime 13.3 LTS, 14.3 LTS e 15.0 a 15.2, o senhor pode configurar manualmente as conexões do Event Grid para usar um proxy, definindo a propriedade Spark Config spark.databricks.cloudFiles.eventGridClient.useSystemProperties true. Consulte Definir propriedades de configuração do Spark em Databricks.

Muitos pedidos​

Se você vir a seguinte mensagem de erro nos seus logs de transmissão Auto Loader , isso indica que suas transmissões estão excedendo o limite de taxa do serviço de eventos de arquivo Databricks :

com.databricks.sql.util.UnexpectedHttpStatus: Too many requests. Please wait a moment and try again.

Isso normalmente ocorre quando várias transmissões Auto Loader leem de subcaminhos diferentes no mesmo local externo sem usar volumes Unity Catalog . O serviço de eventos de arquivos precisa iterar sobre todos os objetos no local externo para encontrar os arquivos relevantes para cada transmissão, resultando em um número excessivo de chamadas API . Para resolver esse problema, siga as recomendações descritas em Usar o modo de notificação de arquivo com eventos de arquivo.

Recursos adicionais​