Connessione a Microsoft OneLake
Microsoft OneLake offre l'accesso aperto a tutti gli elementi di Fabric tramite le API e gli SDK di Azure Data Lake Storage (ADLS) Gen2 esistenti. È possibile accedere ai dati in OneLake tramite qualsiasi API, SDK o strumento compatibile con ADLS Gen2 usando un URI OneLake. È possibile caricare dati in un lakehouse tramite Azure Storage Explorer oppure leggere una tabella delta tramite un collegamento da Azure Databricks.
Poiché OneLake è un Software as a Service (SaaS), alcune operazioni, ad esempio la gestione delle autorizzazioni o l'aggiornamento degli elementi, devono essere eseguite tramite le esperienze di Fabric anziché tramite le API di ADLS Gen2. Per un elenco completo delle modifiche apportate a queste API, vedere Parity dell'API di OneLake.
Sintassi dell'URI
Poiché OneLake esiste nell'intero tenant di Microsoft Fabric, è possibile fare riferimento a qualsiasi elemento nel tenant in base all'area di lavoro, all'elemento e al percorso:
https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.<itemtype>/<path>/<fileName>
Nota
Poiché è possibile riutilizzare i nomi degli elementi in più tipi di elemento, è necessario specificare il tipo di elemento nell'estensione. Per esempio, .lakehouse per un lakehouse e .datawarehouse per un warehouse.
OneLake supporta anche il riferimento a aree di lavoro ed elementi con identificatori univoci globali (GUID). OneLake assegna i GUID e questi non cambiano, anche se cambia l'area di lavoro o il nome dell'elemento. È possibile trovare il GUID associato per l'area di lavoro o l'elemento nell'URL nel portale di Fabric. È necessario usare i GUID sia per l'area di lavoro che per l'elemento; non è necessario il tipo di elemento.
https://onelake.dfs.fabric.microsoft.com/<workspaceGUID>/<itemGUID>/<path>/<fileName>
Quando si adotta uno strumento per utilizzarlo su OneLake invece che su ADLS Gen2, usare il mapping seguente:
- Il nome dell'account è sempre
onelake. - Il nome contenitore è il nome dell'area di lavoro.
- Il percorso dati inizia dall'elemento. Ad esempio:
/mylakehouse.lakehouse/Files/.
OneLake supporta anche il driver del file system BLOB di Azure (ABFS) per una maggiore compatibilità con ADLS Gen2 e Archiviazione BLOB di Azure. Il driver ABFS usa il proprio identificatore di schema abfs e un formato URI diverso per indicare i file e le directory negli account ADLS Gen2. Per usare questo formato URI su OneLake, scambiare l'area di lavoro per il file system e includere l'elemento e il tipo di elemento.
abfs[s]://<workspace>@onelake.dfs.fabric.microsoft.com/<item>.<itemtype>/<path>/<fileName>
L'URI del driver abfs non consente caratteri speciali, per esempio gli spazi, nel nome dell'area di lavoro. In questi casi, è possibile fare riferimento alle aree di lavoro e agli elementi con gli identificatori univoci globali (GUID), come descritto in precedenza in questa sezione.
Autorizzazione
È possibile autenticare le API OneLake usando Microsoft Entra ID, passando da un'intestazione dell’autorizzazione. Se uno strumento supporta l'accesso all'account Azure per abilitare il pass-through dei token, è possibile selezionare qualsiasi sottoscrizione. OneLake richiede solo il token utente e non tiene conto della sottoscrizione di Azure.
Quando si chiama OneLake direttamente tramite API file system DFS, è possibile eseguire l'autenticazione con un bearer token per l'account Microsoft Entra. Per altre informazioni sulla richiesta e sulla gestione dei bearer token per l'organizzazione, vedere Microsoft Authentication Library.
Per un test rapido e ad hoc di OneLake usando chiamate API dirette, ecco un semplice esempio che usa PowerShell per accedere all'account Azure, recuperare un token con ambito di archiviazione e copiarlo negli Appunti per utilizzarlo altrove. Per altre informazioni sul recupero dei token di accesso tramite PowerShell, vedere Get-AzAccessToken.
Nota
OneLake supporta solo i token nel destinatario Storage. Nell'esempio seguente il destinatario viene impostato tramite il parametro ResourceTypeName.
Connect-AzAccount
$testToken = Get-AzAccessToken -ResourceTypeName Storage
# Retrieved token is of string type which you can validate with the "$testToken.Token.GetTypeCode()" command.
$testToken.Token | Set-Clipboard
Residenza dei dati
Se si usa l'endpoint globale ("https://onelake.dfs.fabric.microsoft.com") per eseguire query sui dati in un'area diversa da quella dell'area di lavoro, è possibile che i dati possano lasciare l'area durante il processo di risoluzione degli endpoint. Se si è preoccupati per la residenza dei dati, l'uso dell'endpoint regionale corretto per l'area di lavoro garantisce che i dati rimangano all'interno della zona corrente e non attraversino alcun limite a livello di area. È possibile individuare l'endpoint regionale corretto controllando l'area della capacità a cui è collegata l'area di lavoro.
Gli endpoint regionali di OneLake seguono tutti lo stesso formato: https://<region>-onelake.dfs.fabric.microsoft.com. Per esempio, un'area di lavoro collegata a una capacità nell'area Stati Uniti occidentali è accessibile tramite l'endpoint regionale https://westus-onelake.dfs.fabric.microsoft.com.
Problemi comuni
Se uno strumento o un pacchetto compatibile con ADLS Gen2 non funziona su OneLake, il problema più comune è la convalida degli URL. Poiché OneLake usa un endpoint diverso (dfs.fabric.microsoft.com) rispetto ad ADLS Gen2 (dfs.core.windows.net), alcuni strumenti non riconoscono l'endpoint di OneLake e lo bloccano. Alcuni strumenti consentono di usare endpoint personalizzati, come per esempio PowerShell. Altrimenti, spesso basta eseguire una semplice correzione per aggiungere l'endpoint di OneLake come endpoint supportato. Se viene rilevato un problema di convalida dell'URL o si verificano altri problemi di connessione a OneLake, bisogna segnalarlo.
Esempi
Crea file
| Richiedi | PUT https://onelake.dfs.fabric.microsoft.com/{workspace}/{item}.{itemtype}/Files/sample?resource=file |
|---|---|
| Intestazioni | Authorization: Bearer <userAADToken> |
| Response | ResponseCode: 201 CreatedIntestazioni: x-ms-version : 2021-06-08x-ms-request-id : 272526c7-0995-4cc4-b04a-8ea3477bc67bx-ms-content-crc64 : OAJ6r0dQWP0=x-ms-request-server-encrypted : trueETag : 0x8DA58EE365Corpo: |