Habilitar federação de catálogo do OneLake

Importante

Esse recurso está em Visualização Pública.

Este artigo mostra como ler dados no OneLake usando a federação de catálogo. Isso permite que as consultas do Catálogo do Unity são executadas diretamente no armazenamento do OneLake.

A federação do OneLake permite que você analise os dados armazenados em seu Lakehouse ou Warehouse sem copiá-los, trazendo análises avançadas e recursos de IA/BI no Azure Databricks diretamente para seus dados do OneLake. O acesso a dados é somente leitura.

Antes de começar

Você deve atender aos seguintes requisitos para executar consultas federadas no OneLake usando a federação de catálogo:

Requisitos de área de trabalho:

  • Espaço de trabalho habilitado para o Unity Catalog.

Requisitos de computação:

  • Conectividade de rede do recurso de computação para os sistemas de banco de dados de destino. Confira Recomendações de rede para a Federação de Lakehouse.
  • A computação do Azure Databricks deve usar o Databricks Runtime 18.0 ou superior e o modo de acesso padrão.
  • Os sql warehouses devem usar 2025.40 ou superior.

Permissões necessárias:

  • Para criar uma conexão, você deve ser um administrador do metastore ou um usuário com os privilégios CREATE CONNECTION e CREATE STORAGE CREDENTIAL no metastore do Unity Catalog vinculado ao espaço de trabalho.
  • Para criar um catálogo estrangeiro, você deve ter a permissão CREATE CATALOG no metastore e ser o proprietário da conexão ou ter o privilégio CREATE FOREIGN CATALOG na conexão.

Requisitos de permissão adicionais são especificados em cada seção baseada em tarefas a seguir.

  • Você deve ter permissões para criar recursos no Azure, configurar o acesso no Fabric e gerenciar o Catálogo do Unity no Azure Databricks.
  • Métodos de autenticação com suporte:
    • Identidade Gerenciada do Azure por meio de um Conector de Acesso para Azure Databricks
    • Azure principal de serviço

Configurações de locatário e de espaço de trabalho do Fabric:

  • Um administrador do Fabric deve habilitar as entidades de serviço que podem usar a configuração de locatário de APIs do Fabric. Isso permite que identidades gerenciadas e entidades de serviço se autentiquem com o Fabric. Para obter mais informações, consulte a configuração do arrendatário do principal de serviço.
  • Um administrador do Fabric deve habilitar a configuração de tenant Permitir que aplicativos em execução fora do Fabric acessem dados pelo OneLake. Isso permite que o Azure Databricks se conecte ao armazenamento do OneLake. Para obter mais informações, consulte Permitir que aplicativos em execução fora do Fabric acessem dados por meio do OneLake.
  • Um administrador de Fabric deve habilitar o Use tokens SAS delegados pelo usuário de curta duração configuração de locatário. Essa configuração permite que o OneLake emita os tokens SAS de curta duração apoiados por Entra que Azure Databricks usa para ler dados do OneLake. Para obter mais informações, consulte as assinaturas de acesso compartilhado do OneLake.
  • No workspace do Fabric que contém seus dados, a autenticação com tokens SAS delegados pelo usuário do OneLake deve ser habilitado. Navegue até configurações de workspace>configurações delegadas>configurações do OneLake para habilitar essa configuração.

Há suporte para os seguintes itens de dados do Fabric:

  • Fabric Lakehouse
  • Fabric Warehouse

Configurar a federação do catálogo

As etapas a seguir orientam você na criação da conexão e do catálogo externo para a OneLake federation.

Etapa 1: Configurar a autenticação do Azure

A federação OneLake dá suporte a dois métodos de autenticação.

  • Identidade Gerenciada do Azure (recomendado): usa um Conector de Acesso do Databricks com uma identidade gerenciada.
  • Entidade de Principal de Serviço do Azure: utiliza um aplicativo ID do Microsoft Entra com credenciais de cliente. Esse método dá suporte à autenticação entre locatários, permitindo que o Databricks acesse workspaces do Fabric localizados em um locatário diferente do Azure.

Opção A: Criar um conector de acesso (Identidade Gerenciada)

O Conector de Acesso do Databricks cria uma identidade gerenciada que o Azure Databricks usa para autenticar com o OneLake.

  1. No Portal do Azure, pesquise por e crie um novo recurso Access Connector para Azure Databricks.

  2. Siga os prompts para criar o conector. Esse recurso cria uma Identidade Gerenciada atribuída pelo sistema.

  3. Registre a ID do recurso do conector recém-criado. Você precisa dessa ID ao criar a credencial de armazenamento do Catálogo do Unity.

    A ID do recurso está no formato:

    /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Databricks/accessConnectors/<connector-name>

Para obter mais informações sobre como criar conectores de acesso e usar identidades gerenciadas, consulte Usar identidades gerenciadas do Azure no Catálogo do Unity para acessar o armazenamento.

Opção B: registrar um principal de serviço

Se você preferir usar uma entidade de serviço em vez de uma identidade gerenciada:

  1. No Portal do Azure, navegue até Microsoft Entra ID>Registros de Aplicativos e registre um novo aplicativo (ou use um existente).
  2. Registre a ID do Aplicativo (cliente) e a ID do Diretório (tenant).
  3. Em Certificados &segredos, crie um novo segredo do cliente e registre o valor do segredo.

Etapa 2: Conceder permissões no Fabric

Conceda permissão à identidade gerenciada ou à entidade de serviço para acessar os dados do Fabric.

  1. No portal Fabric, navegue até o workspace que contém os itens de dados do Lakehouse ou Warehouse.
  2. No workspace, clique no ícone de engrenagem de configurações do Workspace e clique em Gerenciar acesso.
  3. Clique em Adicionar pessoas ou grupos.
  4. Pesquise e selecione a Identidade Gerenciada ou o principal de serviço. Para Identidade Gerenciada, o nome deve corresponder ao conector de acesso criado anteriormente. Para uma entidade de serviço, pesquise o nome do aplicativo que você registrou.
  5. Atribua a identidade à função Membro no mínimo. Você também pode atribuir funções de Colaborador ou Administrador .
  6. Clique em Adicionar.
  7. Verifique se a identidade aparece na lista de acesso com a função apropriada. As permissões em itens individuais do Lakehouse e Warehouse são herdadas da função no nível do espaço de trabalho.

Etapa 3: Criar uma credencial de armazenamento

Crie uma credencial de armazenamento no Catálogo do Unity que faça referência à identidade configurada na Etapa 1.

  1. No workspace do Azure Databricks, clique no ícone Dados.Catálogo.
  2. Na parte superior do painel Catálogo, clique no ícone de Adicionar ou mais e selecione Criar uma credencial no menu.

Se você estiver usando uma Identidade Gerenciada:

  1. Na modal Criar uma nova credencial , para Tipo de Credencial, escolha Identidade Gerenciada do Azure.
  2. Para o nome da credencial, insira um nome para a credencial de armazenamento (por exemplo, onelake_storage_cred).
  3. Para a ID do conector de Acesso, insira a ID do recurso do conector de acesso, a qual você criou anteriormente.
  4. (Opcional) Adicione um comentário.
  5. Clique em Criar.

Se você estiver usando uma Entidade de Serviço:

Você não pode criar uma credencial de armazenamento de entidade de serviço usando o Gerenciador de Catálogos. Você deve ser um administrador de conta do Azure Databricks e usar a API de Credenciais de Armazenamento. Por exemplo:

curl -X POST -n \
https://<databricks-instance>/api/2.1/unity-catalog/storage-credentials \
-d '{
   "name": "<storage-credential-name>",
   "read_only": true,
   "azure_service_principal": {
      "directory_id": "<directory-id>",
      "application_id": "<application-id>",
      "client_secret": "<client-secret>"
   },
   "skip_validation": "false"
   }'

Você também pode criar uma credencial de armazenamento usando o provedor Terraform do Databricks e databricks_storage_credential.

Etapa 4: Criar uma conexão do Catálogo do Unity

Crie uma conexão do Catálogo do Unity que use a credencial de armazenamento para acessar o OneLake.

Gerenciador de Catálogos

  1. No workspace do Azure Databricks, clique no ícone Dados.Catálogo.
  2. Na parte superior do painel Catálogo, clique no ícone de adição e selecione Criar uma conexão no menu.
  3. Na página Noções básicas de conexão, insira um nome de conexão (por exemplo, onelake_connection).
  4. Selecione um tipo de conexão do OneLake.
  5. (Opcional) Adicione um comentário.
  6. Clique em Próximo.
  7. Na página Detalhes da conexão , para Credencial, selecione a credencial de armazenamento que você criou na etapa anterior (por exemplo, onelake_storage_cred).
  8. Para o Workspace, insira a identificação do workspace do Fabric.
  9. Clique em Criar conexão.

SQL

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

  • <connection-name>: um nome para a conexão.
  • <workspace-id>: o GUID do seu workspace do OneLake.
  • <storage-credential-name>: o nome da credencial de armazenamento que você criou na etapa 3.
CREATE CONNECTION <connection-name> TYPE onelake
OPTIONS (
  workspace '<workspace-id>',
  credential '<storage-credential-name>'
);

Etapa 5: Criar um catálogo estrangeiro

Um catálogo estrangeiro vincula um item de dados específico do Fabric a um catálogo no Catálogo do Unity.

Obter a ID do item de dados do Fabric

  1. No portal do Fabric, navegue até o Lakehouse ou Warehouse de destino.

  2. Copie a ID do Item de Dados, que é um identificador global único (GUID) (por exemplo, f089354e-8366-4e18-aea3-4cb4a3a50b48).

    Você pode encontrar esse GUID na interface do usuário do Fabric ou copiá-lo da URL do navegador ao navegar até o Lakehouse ou Warehouse:

    https://app.fabric.microsoft.com/groups/<workspace-id>/lakehouses/<data-item-id>?experience=power-bi

Criar o catálogo

Gerenciador de Catálogos
  1. No workspace do Databricks, clique no ícone Dados.Catálogo.
  2. Na parte superior do painel Catálogo , clique no ícone Adicionar ou mais ícone e selecione Criar um catálogo no menu.
  3. Na caixa de diálogo Criar um novo catálogo , insira um nome para o catálogo (por exemplo, fabric_sales).
  4. Selecione um tipo de estrangeiro.
  5. Selecione a Conexão que você criou na Etapa 4 (por exemplo, onelake_connection).
  6. Para item de dados, insira a ID do item de dados copiada do portal do Fabric.
  7. (Opcional) Clique em Testar conexão para validar sua configuração.
  8. Clique em Criar.
SQL

Execute o seguinte comando SQL em um notebook ou no editor de consultas SQL do Databricks. Os itens entre colchetes são opcionais. Substitua os valores de espaço reservado:

  • <catalog-name>: nome do catálogo no Azure Databricks.
  • <connection-name>: a conexão que você criou na etapa 4.
  • <data-item-id>: GUID do Fabric Lakehouse ou Warehouse.
CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (
  data_item '<data-item-id>'
);

Você também pode especificar os seguintes parâmetros opcionais:

CREATE FOREIGN CATALOG <catalog-name> USING CONNECTION <connection-name>
OPTIONS (
  data_item '<data-item-id>',
  item_type 'Lakehouse',
  create_volume_for_lakehouse_files 'true'
);
  • item_type: Lakehouse (padrão) ou Warehouse.
  • create_volume_for_lakehouse_files: true (padrão) ou false. Quando true, cria um volume para a pasta /Files do Lakehouse. Aplica-se somente aos itens do Lakehouse. Consulte os dados não estruturados do Access.

O catálogo é sincronizado automaticamente, disponibilizando as tabelas do Fabric imediatamente.

Acessar dados não estruturados

A federação OneLake dá suporte ao acesso somente leitura a dados não estruturados armazenados na /Files pasta de um Lakehouse. Isso é feito por meio de volumes do Catálogo do Unity.

Quando você cria um catálogo estrangeiro com create_volume_for_lakehouse_files definido como true (o padrão), um volume é criado automaticamente no onelake-folders esquema. Este volume aponta para a pasta /Files do Lakehouse e oferece acesso somente leitura aos arquivos armazenados lá.

Você pode navegar e ler arquivos usando o caminho do volume:

LIST '/Volumes/<catalog-name>/onelake-folders/files/';

df = spark.read.format("binaryFile").load("/Volumes/<catalog-name>/onelake-folders/files/")

Você também pode consultar arquivos estruturados diretamente:

SELECT * FROM parquet.`/Volumes/<catalog-name>/onelake-folders/files/table.parquet`

Conceder permissões em tabelas federadas

Depois de configurar a federação do catálogo, os usuários devem ter as permissões apropriadas do Catálogo do Unity para acessar tabelas federadas:

  • Todos os usuários precisam USE CATALOG e USE SCHEMA permissões no catálogo e no esquema, respectivamente.
  • Para ler da tabela federada, os usuários precisam da SELECT permissão.

Para obter mais informações sobre privilégios do Catálogo do Unity e como concedê-los, consulte Gerenciar privilégios no Catálogo do Unity.

Consultar dados do OneLake

Depois que a instalação for concluída, você poderá encontrar e consultar dados do OneLake no Catálogo do Unity.

Navegar pelo catálogo

  1. No workspace do Databricks, navegue até o Explorador de Catálogos.
  2. Localize o catálogo que você criou (por exemplo, fabric_sales).
  3. Expanda o catálogo para visualizar os esquemas e tabelas sincronizados do Fabric Lakehouse ou Warehouse.

Executar consultas

Use a convenção de nomenclatura de três partes (catalog.schema.table) no Databricks SQL ou em notebooks:

SELECT COUNT(*)
FROM fabric_sales.silver.customer_details;

SELECT
  customer_id,
  customer_name,
  total_purchases
FROM fabric_sales.silver.customer_details
WHERE total_purchases > 1000
ORDER BY total_purchases DESC
LIMIT 10;

Limitações

A federação do OneLake tem as seguintes limitações:

  • Acesso somente leitura: apenas consultas SELECT são suportadas. As operações de gravação não estão disponíveis.
  • Autenticação: Identidade Gerenciada do Azure e principal de serviço do Azure são os métodos de autenticação suportados.
  • Itens de dados com suporte: há suporte apenas para os itens Fabric Lakehouse e Warehouse.
  • Requisitos de computação: não há suporte para o modo de acesso dedicado.
  • Não há suporte para tipos de dados complexos (matrizes, mapas, structs).
  • Não há suporte para visões e visões materializadas.
  • Last updated on