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.
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 é saaS (software como serviço), 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 item no seu locatário pelo workspace, pelo item e pelo 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 GUIDs (identificadores globalmente exclusivos). O OneLake atribui GUIDs e os GUIDs não mudam, mesmo que o nome do espaço de trabalho ou do item seja alterado. Você pode encontrar o GUID associado ao seu workspace ou item no URL do portal do Fabric. Você precisa 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 da área de trabalho.
- 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 proporcionar mais compatibilidade com o ADLS Gen2 e o 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 as APIs do OneLake usando o Microsoft Entra ID passando por um cabeçalho de autorização. Se uma ferramenta oferecer suporte ao login na sua conta do Azure para habilitar a passagem de tokens, 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-se usando 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 na sua conta do Azure, recuperar um token com escopo de armazenamento e copiá-lo para a á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
O OneLake só dá suporte a tokens no público-alvo do Storage. No exemplo a seguir, definimos o público-alvo por meio do parâmetro ResourceTypeName.
Connect-AzAccount
$testToken = Get-AzAccessToken -AsSecureString -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 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ê tiver preocupação com a residência de dados, usar o ponto de extremidade regional correto para o workspace garantirá que os seus dados permaneçam na região atual e não ultrapassem os limites regionais. Você pode descobrir o ponto de extremidade regional correto verificando a região da capacidade à qual o workspace está conectado.
Todos os pontos de extremidade regionais do OneLake seguem o mesmo formato: https://<region>-onelake.dfs.fabric.microsoft.com. Por exemplo, um workspace conectado a uma capacidade na região Oeste dos EUA estará 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 permitem que você use 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 com suporte. Se encontrar um problema de validação de URL ou tiver qualquer outro problema ao se conectar ao OneLake, informe-nos.
Recursos
O OneLake é acessível por meio das mesmas APIs e SDKs que o ADLS Gen2. Para saber mais sobre como usar APIs do ADLS Gen2, consulte as seguintes páginas:
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: |