Conectando-se ao Microsoft OneLake
O Microsoft OneLake fornece acesso aberto a todos os seus itens do Fabric por meio de APIs e SDKs existentes do ADLS Gen2. Você pode acessar seus dados no OneLake por meio de qualquer API, SDK ou ferramenta compatível com o ADLS Gen2 simplesmente utilizando um URI do OneLake. Você pode carregar dados em um lakehouse por meio de Gerenciador de Armazenamento do Microsoft Azure ou ler uma tabela delta por meio de um atalho do Azure Databricks.
Como o OneLake é software como serviço (SaaS), algumas operações, como gerenciar permissões ou atualizar itens, devem ser feitas por meio de experiências do Fabric e não podem ser feitas por meio de APIs do ADLS Gen2. Para obter uma lista completa de 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 workspace, item e caminho:
https://onelake.dfs.fabric.microsoft.com/<workspace>/<item>.<itemtype>/<path>/<fileName>
Observação
Como os nomes de item podem ser reutilizados em vários tipos de item, você deve especificar o tipo de item na extensão. Por exemplo, .lakehouse para um lakehouse e .datawarehouse para um warehouse.
O OneLake também dá suporte à referência de workspaces e itens com identificadores globalmente exclusivos (GUIDs). O OneLake atribui GUIDs e GUIDs não são alterados, mesmo que o nome do workspace ou do item seja alterado. Você pode encontrar o GUID associado para seu workspace ou item na URL no portal do Fabric. Você deve usar GUIDs para o workspace 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 workspace.
- O caminho de dados começa no item. Por exemplo:
/mylakehouse.lakehouse/Files/.
O OneLake também dá suporte ao ABFS (driver do Sistema de Arquivos de Blob do Azure) para obter mais compatibilidade com o ADLS Gen2 e Armazenamento de Blobs do Azure. O driver ABFS usa seu próprio identificador de esquema abfs 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 workspace 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 aos espaços de trabalho e itens com os identificadores globais exclusivos (GUIDs), conforme descrito anteriormente nesta seção.
Autorização
É possível autenticar APIs do OneLake usando o Microsoft Entra ID 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 exige apenas o token do usuário e não leva em consideração a sua assinatura do Azure.
Ao chamar o OneLake diretamente por meio das APIs do DFS, 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 fazer um teste rápido e ad-hoc do OneLake usando chamadas diretas à API, confira 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 facilitar o uso dele em outro lugar. Para obter mais informações sobre como recuperar tokens de acesso utilizando o PowerShell, confira Get-AzAccessToken.
Observação
A OneLake suporta apenas tokens no público-alvo Storage No exemplo a seguir, definimos o público-alvo por meio do parâmetro 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
Residência de dadosResidência de dados
Se você usar o endpoint global ('https://onelake.dfs.fabric.microsoft.com`) para consultar dados em uma região diferente da região do seu espaço de trabalho, é possível que os dados saiam da sua região durante o processo de resolução do endpoint. Se você estiver preocupado com a residência de dados, usar o ponto de extremidade regional correto para seu workspace garante que seus dados permaneçam dentro de sua região atual e não ultrapassem limites regionais. Você pode descobrir o ponto de extremidade regional correto verificando a região da capacidade à qual o workspace está anexado.
Todos os pontos de extremidade regionais do OneLake seguem o mesmo formato: https://<region>-onelake.dfs.fabric.microsoft.com. Por exemplo, um workspace anexado a uma capacidade na região Oeste dos EUA estaria acessível por meio do ponto de extremidade regional https://westus-onelake.dfs.fabric.microsoft.com.
Problemas comuns
Se uma ferramenta ou pacote compatível com o ADLS Gen2 não estiver funcionando no OneLake, o problema mais comum será a validação da URL. Como o OneLake usa um ponto de extremidade diferente (dfs.fabric.microsoft.com) do ADLS Gen2 (dfs.core.windows.net), algumas ferramentas não reconhecem o ponto de extremidade do OneLake e o bloqueiam. Algumas ferramentas permitirão que você utilize pontos de extremidade personalizados (como o PowerShell). Caso contrário, geralmente é uma correção simples adicionar o ponto de extremidade do OneLake como um ponto de extremidade suportado. Se encontrar um problema de validação de URL ou tiver qualquer outro problema ao se conectar ao OneLake, informe-nos.
Exemplos
Criar arquivo
| Solicitação | PUT https://onelake.dfs.fabric.microsoft.com/{workspace}/{item}.{itemtype}/Files/sample?resource=file |
|---|---|
| Cabeçalhos | Authorization: Bearer <userAADToken> |
| Response | ResponseCode: 201 CreatedCabeçalhos: 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: |