Conectando-se ao Microsoft OneLake

O Microsoft OneLake fornece acesso aberto a todos os seus itens de malha por meio de APIs e SDKs Gen2 existentes do Azure Data Lake Storage (ADLS). Você pode acessar seus dados no OneLake por meio de qualquer API, SDK ou ferramenta compatível com o ADLS Gen2 apenas usando um URI do OneLake. Pode carregar dados para uma lakehouse através do Azure Storage Explorer ou ler uma tabela delta através de um atalho do Azure Databricks.

Como o OneLake é software como serviço (SaaS), algumas operações, como gerenciamento de permissões ou atualização de itens, devem ser feitas por meio de experiências de malha em vez das APIs ADLS Gen2. Para obter uma lista completa das alterações nessas APIs, consulte Paridade da API do OneLake.

Sintaxe URI

Como o OneLake existe em todo o locatário do Microsoft Fabric, você pode se referir a qualquer coisa em seu locatário por seu espaço de trabalho, item e caminho:

https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.<itemtype>/<path>/<fileName>

O OneLake também suporta a referência de espaços de trabalho e itens com GUIDs (identificadores globais exclusivos). O OneLake atribui GUIDs e GUIDs não mudam, mesmo se o espaço de trabalho ou o nome do item for alterado. Você pode encontrar o GUID associado para seu espaço de trabalho ou item na URL no portal da malha. Você deve usar GUIDs para o espaço de trabalho e o item e não precisa do tipo de item.

https://onelake.dfs.fabric.microsoft.com/<workspaceGUID>/<itemGUID>/<path>/<fileName>

Ao adotar uma ferramenta para uso no OneLake em vez do ADLS Gen2, use o seguinte mapeamento:

• O nome da conta é sempre onelake.
• O nome do contêiner é o nome do espaço de trabalho.
• O caminho de dados começa no item. Por exemplo: /mylakehouse.lakehouse/Files/.

O OneLake também suporta o driver do Sistema de Arquivos de Blob do Azure (ABFS) para obter mais compatibilidade com o ADLS Gen2 e o Armazenamento de Blobs do Azure. O driver ABFS usa seu próprio identificador abfs de esquema e um formato URI diferente para endereçar arquivos e diretórios em contas ADLS Gen2. Para usar esse formato de URI no OneLake, troque o espaço de trabalho pelo sistema de arquivos e inclua o item e o tipo de item.

abfs[s]://<workspace>@onelake.dfs.fabric.microsoft.com/<item>.<itemtype>/<path>/<fileName>

O URI do driver abfs não permite caracteres especiais, como espaços, no nome do espaço de trabalho. Nesses casos, você pode fazer referência a espaços de trabalho e itens com os GUIDs (identificadores globais exclusivos), conforme descrito anteriormente nesta seção.

Autorização

Você pode autenticar APIs do OneLake usando a ID do Microsoft Entra passando por um cabeçalho de autorização. Se uma ferramenta der suporte ao logon em sua conta do Azure para habilitar a passagem de token, você poderá selecionar qualquer assinatura. O OneLake requer apenas seu token de usuário e não se importa com sua assinatura do Azure.

Ao chamar o OneLake via APIs DFS diretamente, você pode autenticar com um token de portador para sua conta do Microsoft Entra. Para saber mais sobre como solicitar e gerenciar tokens de portador para sua organização, confira a Biblioteca de Autenticação da Microsoft.

Para testes rápidos e ad-hoc do OneLake usando chamadas diretas de API, aqui está um exemplo simples usando o PowerShell para entrar em sua conta do Azure, recuperar um token com escopo de armazenamento e copiá-lo para sua área de transferência para uso fácil em outro lugar. Para obter mais informações sobre como recuperar tokens de acesso usando o PowerShell, consulte Get-AzAccessToken.

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

Residência de dados

Se você usar o ponto de extremidade global ('https://onelake.dfs.fabric.microsoft.com') para consultar dados em uma região diferente da região do seu espaço de trabalho, há uma possibilidade de que os dados saiam da sua região durante o processo de resolução do ponto de extremidade. Se você estiver preocupado com a residência de dados, usar o ponto de extremidade regional correto para seu espaço de trabalho garante que seus dados permaneçam dentro de sua região atual e não cruzem nenhum limite regional. Você pode descobrir o ponto de extremidade regional correto verificando a região da capacidade à qual o espaço de trabalho está anexado.

Todos os endpoints regionais OneLake seguem o mesmo formato: https://<region>-onelake.dfs.fabric.microsoft.com. Por exemplo, um espaço de trabalho anexado a uma capacidade na região Oeste dos EUA seria acessível através do ponto de extremidade https://westus-onelake.dfs.fabric.microsoft.comregional.

Problemas comuns

Se uma ferramenta ou pacote compatível com o ADLS Gen2 não estiver funcionando no OneLake, o problema mais comum é a validação de URL. Como o OneLake usa um endpointdfs.fabric.microsoft.com () diferente do ADLS Gen2 (dfs.core.windows.net), algumas ferramentas não reconhecem o endpoint do OneLake e o bloqueiam. Algumas ferramentas permitem que você use pontos de extremidade personalizados (como o PowerShell). Caso contrário, muitas vezes é uma correção simples adicionar o endpoint do OneLake como um endpoint suportado. Se você encontrar um problema de validação de URL ou tiver quaisquer outros problemas ao se conectar ao OneLake, informe-nos.

Exemplos

Criar ficheiro

Conteúdos relacionados

• Paridade e integração OneLake
• Conecte-se ao OneLake com Python
• Integração do OneLake com o Azure Synapse Analytics