Abilitare la federazione del catalogo OneLake

Questo articolo illustra come leggere i dati in OneLake usando la federazione del catalogo. In questo modo, le query del catalogo Unity possono essere eseguite direttamente nell'archiviazione OneLake.

La federazione di OneLake consente di analizzare i dati archiviati in Lakehouse o Warehouse senza copiarli, portando funzionalità avanzate di analisi e intelligenza artificiale/BI in Azure Databricks direttamente ai dati di OneLake. L'accesso ai dati è di sola lettura.

Prima di iniziare

Per eseguire query federate in OneLake, è necessario soddisfare i requisiti seguenti usando la federazione del catalogo:

Requisiti dell'area di lavoro:

• Area di lavoro attivata per il catalogo Unity.

Requisiti di calcolo:

• Connettività di rete dalla risorsa di calcolo ai sistemi di database di destinazione. Vedi Raccomandazioni sulla rete per Lakehouse Federation.
• Il calcolo di Azure Databricks deve usare Databricks Runtime 18.0 o versione successiva e la modalità di accesso standard.
• I warehouse SQL devono usare la versione 2025.40 o successiva.

Autorizzazioni necessarie:

• Per creare una connessione, è necessario essere un amministratore del metastore o un utente con privilegi CREATE CONNECTION e CREATE STORAGE CREDENTIAL nel metastore del catalogo Unity collegato all'area di lavoro.
• Per creare un catalogo straniero, è necessario avere il permesso CREATE CATALOG sul metastore ed essere il proprietario della connessione o avere il privilegio CREATE FOREIGN CATALOG sulla connessione.

In ogni sezione basata su attività che segue vengono specificati requisiti di autorizzazione aggiuntivi.

• È necessario disporre delle autorizzazioni per creare risorse in Azure, configurare l'accesso in Fabric e gestire Unity Catalog in Azure Databricks.
• Metodi di autenticazione supportati:
  • Identità gestita di Azure tramite un connettore di accesso per Azure Databricks
  • Principale di servizio di Azure

Impostazioni del tenant e dell'area di lavoro del Fabric:

• Un amministratore di Fabric deve abilitare l'impostazione del tenant che permette ai principali del servizio di utilizzare le API di Fabric. In questo modo, le identità gestite e i principali del servizio possono autenticarsi con Fabric. Per ulteriori informazioni, vedere Configurazione del principale di servizio tenant.
• Un amministratore di Infrastruttura deve abilitare l'impostazione Consenti alle app in esecuzione all'esterno di Fabric di accedere ai dati tramite l'impostazione del tenant di OneLake . Ciò consente ad Azure Databricks di connettersi all'archiviazione OneLake. Per altre informazioni, vedere Consentire alle app in esecuzione all'esterno di Fabric di accedere ai dati tramite OneLake.
• Nell'area di lavoro Fabric che contiene i tuoi dati, è necessario abilitare l'autenticazione utilizzando i token SAS delegati dall'utente OneLake. Passare a Impostazioni >dell'area di lavoroImpostazioni delegate > DiOneLake per abilitare questa impostazione.

Sono supportati gli elementi di dati di Fabric seguenti:

• Fabric Lakehouse
• Magazzino tessuti

Configurare la federazione del catalogo

La procedura seguente illustra come creare la connessione e il catalogo esterno per la federazione onelake.

Passaggio 1: Configurare l'autenticazione di Azure

La federazione di OneLake supporta due metodi di autenticazione.

• Identità gestita di Azure (scelta consigliata): usa un connettore di accesso di Databricks con un'identità gestita.
• Entità servizio di Azure: usa un'applicazione Microsoft Entra ID con credenziali client. Questo metodo supporta l'autenticazione tra tenant, consentendo a Databricks di accedere alle aree di lavoro di Fabric che si trovano in un tenant di Azure diverso.

Opzione A: Creare un connettore di accesso (identità gestita)

Databricks Access Connector crea un'identità gestita usata da Azure Databricks per l'autenticazione con OneLake.

1. Nel portale di Azure cercare e creare un nuovo connettore di accesso per la risorsa Azure Databricks .

2. Seguire le istruzioni per creare il connettore. Questa risorsa crea un'identità gestita assegnata dal sistema.

3. Registrare l'ID risorsa del connettore appena creato. Questo ID è necessario quando si creano le credenziali di archiviazione del catalogo Unity.

   L'ID risorsa è nel formato:

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

Per altre informazioni sulla creazione di connettori di accesso e sull'uso di identità gestite, vedere Usare le identità gestite di Azure nel catalogo unity per accedere all'archiviazione.

Opzione B: Registrare un principale del servizio

Se preferisci utilizzare un'entità servizio anziché un'identità gestita:

1. Nel portale di Azure passare aRegistrazioni app > e registrare una nuova applicazione (o usarne una esistente).
2. Registrare l'ID applicazione (client) e l'ID directory (tenant).
3. In Certificati e segreti creare un nuovo segreto client e registrare il valore del segreto.

Passaggio 2: Concedere le autorizzazioni in Fabric

Concedere all'identità gestita o all'entità servizio l'autorizzazione per la lettura dei dati di Fabric.

1. Nel portale Fabric, naviga allo spazio di lavoro che contiene i tuoi elementi di dati Lakehouse o Warehouse.
2. Nell'area di lavoro fare clic sull'icona a forma di ingranaggio Impostazioni area di lavoro, quindi fare clic su Gestisci accesso.
3. Fare clic su Aggiungi persone o gruppi.
4. Cercare e selezionare l'identità gestita o il principale del servizio. Per Identità gestita, il nome deve corrispondere al connettore di accesso creato in precedenza. Per un'entità servizio, cercare il nome dell'applicazione registrato.
5. Assegnare almeno l'identità al ruolo Membro . È anche possibile assegnare ruoli collaboratore o amministratore .
6. Fare clic su Aggiungi.
7. Verificare che l'identità venga visualizzata nell'elenco di accesso con il ruolo appropriato. Le autorizzazioni per singoli elementi Lakehouse e Warehouse vengono ereditate dal ruolo a livello di area di lavoro.

Passaggio 3: Creare credenziali di archiviazione

Creare credenziali di archiviazione nel catalogo unity che faccia riferimento all'identità configurata nel passaggio 1.

1. Nell'area di lavoro di Azure Databricks fare clic Catalogo.
2. Nella parte superiore del riquadro Catalogo, fare clic sull'icona e selezionare Crea una credenziale dal menu.

Se si usa un'identità gestita:

1. In Crea una nuova credenziale modale scegliere Identità gestita di Azure per Tipo di credenziale.
2. Per Nome credenziale immettere un nome per le credenziali di archiviazione, ad esempio onelake_storage_cred.
3. Per ID del connettore di accesso inserire l'ID risorsa del connettore di accesso creato in precedenza.
4. (Facoltativo) Aggiungere un commento.
5. Clicca su Crea.

Se stai utilizzando un principale del servizio:

Non è possibile creare una credenziale di archiviazione per il principale del servizio usando Catalog Explorer. È necessario essere un amministratore dell'account Azure Databricks e usare l'API Credenziali di archiviazione. Per esempio:

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"
   }'

È anche possibile creare credenziali di archiviazione usando il provider Databricks Terraform e databricks_storage_credential.

Passaggio 4: Creare una connessione al catalogo Unity

Creare una connessione al catalogo Unity che usa le credenziali di archiviazione per accedere a OneLake.

Esploratore di cataloghi

1. Nell'area di lavoro di Azure Databricks fare clic Catalogo.
2. Nella parte superiore del riquadro Catalogo, fare clic sull'icona e selezionare Crea una connessione dal menu.
3. Nella pagina Informazioni di base sulla connessione immettere un nome di connessione , ad esempio onelake_connection.
4. Selezionare un tipo di connessione di OneLake.
5. (Facoltativo) Aggiungere un commento.
6. Fare clic su Avanti.
7. Nella pagina Dettagli connessione selezionare le credenziali di archiviazione create nel passaggio precedente, ad esempio onelake_storage_cred.
8. In Area di lavoro, immettere l'ID area di lavoro del proprio Fabric workspace.
9. Fai clic su Crea connessione.

SQL

Eseguire il seguente comando in un notebook o nell'editor di query SQL di Databricks. Sostituisci i valori segnaposto:

• <connection-name>: nome della connessione.
• <workspace-id>: GUID dell'area di lavoro di OneLake.
• <storage-credential-name>: nome delle credenziali di archiviazione create nel passaggio 3.

CREATE CONNECTION <connection-name> TYPE onelake
OPTIONS (
  workspace '<workspace-id>',
  credential '<storage-credential-name>'
);

Passaggio 5: Creare un catalogo esterno

Un catalogo esterno collega un elemento di dati di Fabric specifico a un catalogo in Unity Catalog.

Ottenere l'ID dell'elemento di dati Fabric

1. Nel portale Fabric, vai al Lakehouse o Warehouse di destinazione.

2. Copiare l'ID dell'elemento di dati, ovvero un GUID , ad esempio f089354e-8366-4e18-aea3-4cb4a3a50b48.

   È possibile trovare questo GUID nell'interfaccia utente di Fabric o copiandolo dall'URL del browser quando si accede a Lakehouse o Warehouse.

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

Creare il catalogo

Esploratore di cataloghi

1. Nell'area di lavoro di Databricks fare clic Catalogo.
2. Nella parte superiore del riquadro Catalogo, fare clic sull'icona e selezionare Crea un catalogo dal menu.
3. Nella finestra di dialogo Crea un nuovo catalogo immettere un nome per il catalogo , ad esempio fabric_sales.
4. Selezionare un tipo di straniero.
5. Selezionare la connessione creata nel passaggio 4 , ad esempio onelake_connection.
6. Per Elemento dati immettere l'ID elemento di dati copiato dal portale di Fabric.
7. (Facoltativo) Fare clic su Test connessione per convalidare la configurazione.
8. Clicca su Crea.

SQL

Eseguire il comando SQL seguente in un notebook o nell'editor di query SQL di Databricks. Gli elementi tra parentesi sono facoltativi. Sostituisci i valori segnaposto:

• <catalog-name>: Nome per il catalogo in Azure Databricks.
• <connection-name>: connessione creata nel passaggio 4.
• <data-item-id>: GUID del Fabric Lakehouse o del Data Warehouse.

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS (
  data_item '<data-item-id>'
);

È anche possibile specificare i parametri facoltativi seguenti:

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 (impostazione predefinita) o Warehouse.
• create_volume_for_lakehouse_files: true (impostazione predefinita) o false. Quando true crea un volume per la cartella /Files del Lakehouse. Si applica solo agli elementi Lakehouse. Vedere Accedere a dati non strutturati.

Il catalogo viene sincronizzato automaticamente, rendendo immediatamente disponibili le tabelle di Fabric.

Accedere ai dati non strutturati

La federazione di OneLake supporta l'accesso in sola lettura ai dati non strutturati archiviati nella /Files cartella di un Lakehouse. Questo viene ottenuto tramite i volumi di Unity Catalog.

• Richiede Databricks Runtime 18.1 o superiore, o SQL Warehouse versione 2026.10 o superiore.

Quando si crea un catalogo esterno con create_volume_for_lakehouse_files impostato su true (impostazione predefinita), viene creato automaticamente un volume nello onelake-folders schema. Questo volume indirizza alla /Files cartella di Lakehouse e fornisce accesso in sola lettura ai file archiviati in tale posizione.

È possibile esplorare e leggere i file usando il percorso del volume:

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

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

È anche possibile eseguire query sui file strutturati direttamente:

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

Concedere le autorizzazioni per le tabelle federate

Dopo aver configurato la federazione del catalogo, gli utenti devono disporre delle autorizzazioni appropriate per il catalogo Unity per accedere alle tabelle federate:

• Tutti gli utenti necessitano delle autorizzazioni USE CATALOG per il catalogo e USE SCHEMA per lo schema, rispettivamente.
• Per leggere dalla tabella federata, gli utenti devono disporre dell'autorizzazione SELECT .

Per altre informazioni sui privilegi del catalogo Unity e su come concederli, vedere Gestire i privilegi in Unity Catalog.

Eseguire query sui dati di OneLake

Al termine dell'installazione, è possibile trovare ed eseguire query sui dati di OneLake in Unity Catalog.

Esplorare il catalogo

1. Nell'area di lavoro di Databricks passare a Esplora cataloghi.
2. Individuare il catalogo creato, ad esempio fabric_sales.
3. Espandere il catalogo per visualizzare gli schemi e le tabelle sincronizzati da Fabric Lakehouse o Warehouse.

Esegui le query

Usare la convenzione di denominazione in tre parti (catalog.schema.table) in Databricks SQL o notebook:

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;

Limitazioni

La federazione di OneLake presenta le limitazioni seguenti:

• Accesso in sola lettura: Solo le query SELECT sono supportate. Le operazioni di scrittura non sono disponibili.
• Autenticazione: Identità Gestita di Azure e Principal di Servizio di Azure sono i metodi di autenticazione supportati.
• Elementi di dati supportati: sono supportati solo gli elementi Fabric Lakehouse e Warehouse.
• Requisiti di calcolo: la modalità di accesso dedicato non è supportata.
• I tipi di dati complessi (matrici, mappe, struct) non sono supportati.
• Le viste e le viste materializzate non sono supportate.
• L'accesso non strutturato ai dati (volumi) richiede Databricks Runtime 18.1 o versione successiva o SQL Warehouse versione 2026.10 o successiva.