Gerenciar locais externos

2025-06-26

Este artigo descreve como listar, exibir, atualizar, conceder permissões, habilitar eventos de arquivo e excluir locais externos.

Observação

O Databricks recomenda reger o acesso aos arquivos usando volumes. Veja O que são volumes do Catálogo do Unity?.

Descrever um local externo

Para ver as propriedades de um local externo, incluindo permissões e acesso ao espaço de trabalho, você pode usar o Explorador de Catálogos ou um comando SQL.

Explorador do Catálogo

Na barra lateral, clique no Catálogo.
Na página Acesso rápido, clique no botão >Dados externos para ir para a guia Locais externos.
Clique no nome de um local externo para visualizar suas propriedades.

SQL

Execute o comando a seguir em um bloco de anotações ou no editor de SQL do Databricks. Substitua <location-name> pelo nome do local externo.

DESCRIBE EXTERNAL LOCATION <location-name>;

Mostrar as permissões concedidas em um local externo

Para mostrar concessões em um local externo, use um comando como o seguinte. Opcionalmente, você pode filtrar os resultados para mostrar apenas as concessões da entidade de segurança especificada.

SHOW GRANTS [<principal>] ON EXTERNAL LOCATION <location-name>;

Substitua os valores de espaço reservado:

<location-name>: o nome do local externo que autoriza a leitura e a gravação no contêiner de armazenamento ou bucket no seu locatário de nuvem.
<principal>: o endereço de email de um usuário de nível de conta ou o nome de um grupo de nível de conta.

Observação

Se um grupo ou nome de usuário contiver um espaço ou o símbolo @, use crases (` `) ao redor, e não apóstrofos.

Conceder permissões em um local externo

Esta seção descreve como conceder e revogar permissões em um local externo usando o Explorador de Catálogos e comandos SQL em um notebook ou consulta SQL. Para obter informações sobre como, alternativamente, usar a CLI ou o Terraform do Databricks, confira a Documentação do Terraform no Databricks e O que é a CLI do Databricks?

Você pode conceder as seguintes permissões em um local externo:

CREATE EXTERNAL TABLE
CREATE EXTERNAL VOLUME
CREATE MANAGED STORAGE

Permissões necessárias: o privilégio CREATE EXTERNAL LOCATION no metastore e na credencial de armazenamento referenciada no local externo ou o privilégio MANAGE no local externo. Por padrão, os administradores do metastore têm CREATE EXTERNAL LOCATION no metastore.

Para conceder permissão para usar um local externo:

Explorador do Catálogo

Na barra lateral, clique no Catálogo.
Na página Acesso rápido, clique no botão >Dados externos para ir para a guia Locais externos.
Clique no nome de um local externo para abrir suas propriedades.
Clique em Permissões.
Para conceder permissões a usuários ou grupos, selecione cada identidade e clique em Conceder.
Para revogar permissões de usuários ou grupos, selecione cada identidade e clique em Revogar.

SQL

Execute o comando SQL a seguir em um notebook ou editor de consultas SQL. Esse exemplo concede a capacidade de criar uma tabela externa que faça referência ao local externo:

GRANT CREATE EXTERNAL TABLE ON EXTERNAL LOCATION <location-name> TO <principal>;

Substitua os valores de espaço reservado:

<location-name>: o nome do local externo que autoriza a leitura e a gravação no contêiner de armazenamento ou bucket no seu locatário de nuvem.
<principal>: o endereço de email de um usuário de nível de conta ou o nome de um grupo de nível de conta.

Observação

Se um grupo ou nome de usuário contiver um espaço ou o símbolo @, use crases ao redor (e não apóstrofos). Por exemplo, equipe financeira .

Alterar o proprietário de um local externo

O criador de um local externo é seu proprietário inicial. Para alterar o proprietário para um usuário ou grupo de nível de conta diferente, execute o seguinte comando em um notebook ou no editor de SQL do Databricks ou use o Explorador do Catálogo.

Permissões necessárias: proprietário de local externo ou um usuário com o privilégio MANAGE.

Substitua os valores de espaço reservado:

<location-name>: o nome da credencial.
<principal>: o endereço de email de um usuário de nível de conta ou o nome de um grupo de nível de conta.

ALTER EXTERNAL LOCATION <location-name> OWNER TO <principal>

Marcar um local externo como somente leitura

Se você quiser que os usuários tenham acesso somente leitura a um local externo, use o Explorador do Catálogo para marcar o local externo como somente leitura.

Como tornar os locais externos somente leitura:

Impede que os usuários gravem em arquivos nesses locais externos, independentemente de quaisquer permissões de gravação concedidas pela identidade gerenciada do Azure subjacentes à credencial de armazenamento e independentemente das permissões do Catálogo do Unity concedidas nesse local externo.
Impede que os usuários criem tabelas ou volumes gerenciados nesses locais externos.
Permite que o sistema valide o local externo corretamente no momento da criação.

Você pode marcar locais externos como somente leitura quando criá-los.

Você também pode usar o Catalog Explorer para alterar o status somente leitura depois de criar um local externo:

Na barra lateral, clique no Catálogo.
Na página Acesso rápido, clique no botão >Dados externos para ir para a guia Locais externos.
Selecione o local externo, clique no menu ao lado do botão Testar conexão e selecione Editar.
Na caixa de diálogo de edição, clique em Opções Avançadas e selecione a opção Limitar ao uso somente para leitura.
Clique em Atualizar.

Configurar um algoritmo de criptografia em um local externo (somente AWS S3)

O AWS dá suporte à SSE (criptografia do servidor) com chaves gerenciadas do Amazon S3 (SSE-S3) ou chaves KMS do AWS (SSE-KMS) para proteger dados no S3. Se o bucket S3 exigir criptografia SSE, você poderá configurar um algoritmo de criptografia em seu local externo para permitir que tabelas e volumes externos no Catálogo do Unity acessem dados em seu bucket S3. Não há suporte para SSE com tabelas externas compartilhadas usando o Delta Sharing. Para obter mais informações, consulte Configurar criptografia para S3 com KMS.

Na barra lateral, clique no Catálogo.
Na parte superior do painel Catálogo , clique no Ícone de engrenagem e selecione Locais Externos.
Selecione o local externo. O local externo deve usar uma função do IAM para uma credencial de armazenamento.
Clique no Menu kebab ao lado do botão Testar conexão e selecione Editar.
Na caixa de diálogo editar, clique em Opções Avançadas.
Em Algoritmo de Criptografia , selecione SSE-SE ou SSE-KMS , dependendo da chave de criptografia.

Para SSE-KMS, em ARN da chave KMS de criptografia, cole o ARN da chave KMS referenciada pelos clientes ao acessar o destino S3.
Clique em Atualizar.

(Recomendado) Habilitar eventos de arquivo para um local externo

Se você quiser ingerir notificações de alteração enviadas por push pelo provedor de nuvem, habilitar eventos de arquivo para o local externo terá as seguintes vantagens:

Facilita a configuração de notificações de arquivo para o Carregador Automático. Especificamente, ele permite a descoberta incremental de arquivos com desempenho semelhante a notificações no Auto Loader, configurando cloudFiles.useManagedFileEvents para true. Consulte Configurar fluxos do Carregador Automático no modo de notificação de arquivo.
Melhora a eficiência e a capacidade dos gatilhos de chegada de arquivos para trabalhos. Confira Disparar trabalhos quando novos arquivos chegarem.

Antes de começar

Se você quiser que o Azure Databricks configure filas do Azure Data Lake Storage ou filas do SQS em seu nome, sua localização externa deverá referenciar uma credencial de armazenamento que conceda permissões adequadas para isso. Consulte a próxima etapa para obter instruções.

Se você quiser criar sua própria fila de armazenamento do Azure Data Lake, a identidade representada pela credencial de armazenamento deverá ter a seguinte permissão nessas filas de armazenamento do Azure Data Lake:

Colaborador de Dados da Fila de Armazenamento

Se você quiser criar suas próprias filas do SQS, a identidade representada pela credencial de armazenamento deverá ter as seguintes permissões nessas filas do SQS:

sqs:ReceiveMessage
sqs:DeleteMessage
sqs:PurgeQueue

Etapa 1: confirmar se o Azure Databricks tem acesso a eventos de arquivo no Azure Data Lake Storage ou no AWS S3

Antes de habilitar eventos de arquivo para o objeto protegível de localização externa, você deve garantir que sua conta do Azure Data Lake Storage ou do AWS S3 esteja configurada para dar ao Azure Databricks acesso aos eventos de arquivo que ele emite. Se você quiser que o Azure Databricks configure eventos de arquivo no Azure Data Lake Storage ou no AWS S3 para você, também deve garantir que o Azure Databricks tenha o acesso adequado.

Atribuir esse acesso é uma etapa recomendada ao configurar credenciais de armazenamento.

Para contêineres do Azure Data Lake Storage

Para confirmar se a identidade gerenciada que fornece acesso ao local externo está configurada corretamente:

Obtenha a ID de identidade gerenciada do Azure.
1. Na barra lateral, clique no Catálogo.
2. Na página Acesso rápido, clique no botão >Dados externos para ir para a guia Locais externos.
3. Selecione o local externo.
4. Na guia Visão geral, clique no nome da Credencial.
5. Na guia Visão geral da credencial de armazenamento, copie a ID do Conector ou a ID de Identidade Gerenciada Atribuída pelo Usuário.
  
  Você usará isso na próxima etapa.
Faça logon em sua conta do Azure Data Lake Storage.
Acesse o Controle de Acesso (IAM) e clique no botão Verificar acesso .
Na identidade gerenciada, selecione a identidade gerenciada atribuída pelo usuário ou o Conector de Acesso para Azure Databricks, dependendo do tipo de identidade gerenciada.
Pesquise a identidade gerenciada copiada na etapa 1.
Confirme se a identidade gerenciada tem as seguintes funções:
- Colaborador de Dados de Armazenamento de Blobs
- Colaborador de EventGrid EventSubscription
- Colaborador de Dados de Fila de Armazenamento: necessário apenas se você quiser que o Azure Databricks crie uma assinatura e eventos no Azure Data Lake Storage para você. Se você não habilitar essa função, deverá criar a fila de armazenamento do Azure por conta própria).
Se alguma dessas funções estiver ausente, vá para a guia Atribuições qualificadas e adicione-as.

Para obter mais informações sobre como atribuir essas funções, consulte a Etapa 3: Conceder acesso de identidade gerenciada a eventos de arquivo e Etapa 4: Conceder acesso ao Azure Databricks para configurar eventos de arquivo em seu nome.

Para buckets do S3

Para verificar se o Databricks pode configurar e assinar as notificações de evento do bucket:

Obtenha a função do IAM.
1. Na barra lateral, clique no Catálogo.
2. Na página Acesso rápido, clique no botão >Dados externos para ir para a guia Locais externos.
3. Selecione o local externo.
4. Na guia Visão geral, clique no nome da Credencial.
5. Na guia Visão geral da credencial de armazenamento, copie a função do IAM (ARN).
  
  Você usará isso na próxima etapa.
Faça logon em sua conta do AWS.
Vá para o IAM e pesquise a função copiada na etapa 1.
Em Políticas de permissões, localize as políticas do IAM associadas à função do IAM e abra.

Abra a política ou as políticas e confirme se há uma que inclui as propriedades a seguir.

Essa política permite que sua conta do Azure Databricks atualize a configuração de notificação de eventos do bucket, crie um tópico SNS, crie uma fila do SQS e assine a fila do SQS no tópico SNS.

Substitua <BUCKET> pelo nome do bucket de S3.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ManagedFileEventsSetupStatement",
      "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>", "arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    },
    {
      "Sid": "ManagedFileEventsListStatement",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": ["arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    },
    {
      "Sid": "ManagedFileEventsTeardownStatement",
      "Effect": "Allow",
      "Action": ["sns:Unsubscribe", "sns:DeleteTopic", "sqs:DeleteQueue"],
      "Resource": ["arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    }
  ]
}

Veja também a Etapa 1: Criar uma função IAM.

Se essa política estiver ausente, adicione-a à função do IAM.

Etapa 2: Habilitar eventos de arquivo para o local externo usando o Gerenciador de Catálogos

Para habilitar eventos de arquivo:

Na barra lateral, clique no Catálogo.
Na página Acesso rápido, clique no botão >Dados externos para ir para a guia Locais externos.
Selecione o local externo.
Clique no Menu kebab ao lado do botão Testar conexão e selecione Editar.
Na caixa de diálogo editar, clique em Opções Avançadas.
Selecione Habilitar eventos de arquivo.
Selecione o Tipo de evento de arquivo:

Automático: (Recomendado) selecione isso se você quiser que o Azure Databricks configure assinaturas e eventos para você.

Fornecido: selecione isso se você já tiver configurado uma fila de armazenamento do Azure ou uma fila do SQS por conta própria.
Se você selecionou o tipo de evento de arquivo Fornecido, insira o URL da Fila da fila de armazenamento existente.
- Fila de armazenamento do Azure: https://<storage account>.queue.core.windows.net/<queue>
- Fila SQS da AWS: https://sqs.<region>.amazonaws.com/<account-ID>/<queue-name>
Clique em Atualizar.
Aguarde alguns segundos e clique em Testar conexão na página de edição de local externo principal para confirmar se os eventos de arquivo foram habilitados com êxito.

Limitações de eventos do arquivo

Os eventos de arquivo em locais externos têm as seguintes limitações:

A taxa de processamento de eventos é limitada a 2.000 arquivos ingeridos por segundo.
Você não pode marcar recursos de nuvem usando a opção resourceTags . Em vez disso, marque recursos usando o console da nuvem depois que o serviço Carregador Automático criar seus recursos de fila e de assinatura.
Não é possível configurar eventos de arquivo para o armazenamento raiz do metastore do Unity Catalog se nenhum local externo for definido para esse armazenamento.

Não é possível configurar eventos de arquivo em locais de armazenamento que não tenham nenhum objeto de localização externo definido no Catálogo do Unity. Algumas implementações do Catálogo do Unity incluem um local de armazenamento raiz do metastore que não está associado a um local externo. Para determinar se esse é o caso do local de armazenamento raiz do metastore:
1. Como administrador de conta, faça logon no console da conta.
2. Clique no Catálogo.
3. Clique no nome do metastore.
4. Vá para a guia Configuração .
5. Se houver um valor de caminho do ADLS Gen 2, a raiz do metastore não terá nenhum objeto de local externo definido nela.
  
  Para atualizar o armazenamento raiz do metastore para usar um local externo, clique no botão Remover . Um local externo será criado para você. Para obter detalhes, consulte Remover armazenamento no nível do metastore.

Não há suporte para o Armazenamento de Blobs do Azure.

Modificar um local externo

O proprietário de um local externo ou um usuário com o MANAGE privilégio podem renomear, alterar o URI e alterar a credencial de armazenamento do local externo.

Para renomear um local externo, faça o seguinte:

Execute o comando a seguir em um bloco de anotações ou no editor de SQL do Databricks. Substitua os valores de espaço reservado:

<location-name>: o nome do local.
<new-location-name>: um novo nome para o local.

ALTER EXTERNAL LOCATION <location-name> RENAME TO <new-location-name>;

Para alterar o URI para o qual um local externo aponta em seu locatário de nuvem, faça o seguinte:

Execute o comando a seguir em um bloco de anotações ou no editor de SQL do Databricks. Substitua os valores de espaço reservado:

<location-name>: o nome do local externo.
<url>: a nova URL de armazenamento para a qual o local deve autorizar o acesso no seu locatário de nuvem.

ALTER EXTERNAL LOCATION location_name SET URL '<url>' [FORCE];

A opção FORCE altera a URL mesmo que as tabelas externas dependam do local externo.

Para alterar a credencial de armazenamento usada por um local externo, faça o seguinte:

Execute o comando a seguir em um bloco de anotações ou no editor de SQL do Databricks. Substitua os valores de espaço reservado:

<location-name>: o nome do local externo.
<credential-name>: o nome da credencial de armazenamento que concede acesso à URL do local em seu locatário de nuvem.

ALTER EXTERNAL LOCATION <location-name> SET STORAGE CREDENTIAL <credential-name>;

Excluir um local externo

Para excluir (remover) um local externo, você deve ser seu proprietário ou ter o privilégio MANAGE no local externo. Para excluir um local externo, faça o seguinte:

Execute o comando a seguir em um bloco de anotações ou no editor de SQL do Databricks. Os itens entre colchetes são opcionais. Substitua <location-name> pelo nome do local externo.

DROP EXTERNAL LOCATION [IF EXISTS] <location-name>;

Compartilhar via

Gerenciar locais externos

Descrever um local externo

Explorador do Catálogo

SQL

Mostrar as permissões concedidas em um local externo

Conceder permissões em um local externo

Explorador do Catálogo

SQL

Alterar o proprietário de um local externo

Marcar um local externo como somente leitura

Configurar um algoritmo de criptografia em um local externo (somente AWS S3)

(Recomendado) Habilitar eventos de arquivo para um local externo

Antes de começar

Etapa 1: confirmar se o Azure Databricks tem acesso a eventos de arquivo no Azure Data Lake Storage ou no AWS S3

Para contêineres do Azure Data Lake Storage

Para buckets do S3

Etapa 2: Habilitar eventos de arquivo para o local externo usando o Gerenciador de Catálogos

Limitações de eventos do arquivo

Modificar um local externo

Excluir um local externo

Comentários

Recursos adicionais