Partilhar via


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 e não podem ser feitas por meio de APIs ADLS Gen2. Para obter uma lista completa das alterações nessas APIs, consulte Paridade da API do OneLake.

Sintaxe URI

Uma vez que o OneLake existe em toda a sua conta do Microsoft Fabric, pode referir-se a qualquer coisa na sua conta pelo espaço de trabalho, item e caminho:

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

Nota

Como você pode reutilizar nomes de item em vários tipos de item, você deve especificar o tipo de item na extensão. Por exemplo, .lakehouse para uma casa no lago e .datawarehouse para um armazém.

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

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/.

OneLake também suporta o driver Azure Blob Filesystem (ABFS), proporcionando maior 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 este formato de URI no OneLake, substitua 'workspace' por 'filesystem' 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 as APIs do OneLake usando o Microsoft Entra ID, passando 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 diretamente através das APIs DFS, podes autenticar-te com um token de acesso para a tua conta 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 pontuais do OneLake usando chamadas diretas de API, aqui está um exemplo simples que utiliza o PowerShell para iniciar sessão na sua conta do Azure, recuperar um token com escopo de armazenamento de dados e colá-lo na sua área de transferência para uso fácil em outras aplicações ou documentos. Para obter mais informações sobre como recuperar tokens de acesso usando o PowerShell, consulte Get-AzAccessToken.

Nota

OneLake só suporta tokens para a audiência Storage. No exemplo a seguir, definimos o público por meio do ResourceTypeName parâmetro.

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 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 endpoint regional correto verificando a capacidade da região à 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 estaria acessível através do ponto de extremidade regionalhttps://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 é 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 utilizar endpoints personalizados (como o PowerShell). Caso contrário, muitas vezes é uma correção simples adicionar o endpoint do OneLake à lista de endpoints suportados. Se você encontrar um problema de validação de URL ou tiver quaisquer outros problemas ao se conectar ao OneLake, informe-nos.

Recursos

O OneLake é acessível através das mesmas APIs e SDKs do ADLS Gen2. Para saber mais sobre como usar as APIs do ADLS Gen2, consulte as seguintes páginas:

Exemplos

Criar ficheiro

Pedir COLOCAR https://onelake.dfs.fabric.microsoft.com/{workspace}/{item}.{itemtype}/Files/sample?resource=file
Cabeçalhos Authorization: Bearer <userAADToken>
Response Código de resposta:201 Created
Cabeçalhos:
x-ms-version : 2021-06-08
x-ms-request-id : 272526c7-0995-4cc4-b04a-8ea3477bc67b
x-ms-content-crc64 : OAJ6r0dQWP0=
x-ms-request-server-encrypted : true
ETag : 0x8DA58EE365
Corpo: