Paridade da API do OneLake e do Azure Data Lake Storage (ADLS) Gen2

  • Artigo

O OneLake dá suporte às mesmas APIs do Azure Data Lake Storage (ADLS) Gen2, permitindo que os usuários leiam, escrevam e gerenciem seus dados no OneLake com as ferramentas que eles já usam hoje. Como o OneLake é um data lake lógico gerenciado, alguns recursos são gerenciados de forma diferente do que no Armazenamento do Microsoft Azure e nem todos os comportamentos têm suporte no OneLake. Esta página detalha essas diferenças, incluindo pastas gerenciadas do OneLake, diferenças de API e compatibilidade de software livre.

Pastas gerenciadas do OneLake

Os workspaces e os itens de dados em seu locatário do Fabric definem a estrutura do OneLake. O gerenciamento de workspaces e itens é feito por meio de experiências do Fabric – o OneLake não dá suporte à criação, atualização ou exclusão de workspaces ou itens por meio das APIs do ADLS Gen2. O OneLake só permite chamadas HEAD no nível do workspace (contêiner) e no nível do locatário (conta), pois você deve fazer alterações no locatário e nos workspaces no portal de administração do Fabric.

O OneLake também impõe uma estrutura de pastas para itens do Fabric, protegendo itens e suas subpastas gerenciadas da criação, exclusão ou renomeação por meio de APIs do ADLS Gen2. As pastas gerenciadas pelo Fabric incluem a pasta de nível superior em um item (por exemplo, /MyLakehouse.lakehouse) e o primeiro nível de pastas dentro dela (por exemplo, /MyLakehouse.lakehouse/Files e /MyLakehouse.lakehouse/Tables).

Você pode executar operações CRUD em qualquer pasta ou arquivo criado dentro dessas pastas gerenciadas e executar operações somente leitura no workspace e nas pastas de itens.

Cabeçalhos e parâmetros de solicitação sem suporte

Mesmo em arquivos e pastas criados pelo usuário, o OneLake restringe algumas operações de gerenciamento do Fabric por meio da APIs do ADLS Gen2. Você deve usar experiências do Fabric para atualizar permissões ou editar itens e workspaces, e o Fabric gerencia outras opções, como camadas de acesso.

O OneLake aceita quase todos os mesmos cabeçalhos que o ADLS Gen2, ignorando apenas alguns cabeçalhos relacionados a ações não permitidas no OneLake. Como esses cabeçalhos não alteram o comportamento de toda a chamada, o OneLake ignora os cabeçalhos banidos, retorna-os em um novo cabeçalho de resposta "x-ms-rejected-headers" e permite o restante da chamada. Por exemplo, o OneLake ignora o parâmetro "x-ms-owner" em uma chamada PUT, pois o Fabric e o OneLake não têm o mesmo conceito de possuir usuários que o Armazenamento do Microsoft Azure.

O OneLake rejeita solicitações que contêm parâmetros de consulta não permitidos, pois os parâmetros de consulta alteram o comportamento de toda a chamada. Por exemplo, as chamadas UPDATE com o parâmetro "setAccessControl" são bloqueadas, pois o OneLake nunca dá suporte à configuração do controle de acesso por meio de APIs de Armazenamento do Microsoft Azure.

O OneLake não permite os seguintes comportamentos e seus cabeçalhos de solicitação e parâmetros de URI associados:

  • Definir controle de acesso
    • Parâmetro do URI:
      • ação: setAccessControl (solicitação rejeitada)
      • ação: setAccessControlRecursive (solicitação rejeitada)
    • Cabeçalhos de solicitação:
      • x-ms-owner (cabeçalho ignorado)
      • x-ms-group (cabeçalho ignorado)
      • x-ms-permissions (cabeçalho ignorado)
      • x-ms-group (cabeçalho ignorado)
      • x-ms-acls (cabeçalho ignorado)
  • Definir escopo de criptografia
    • Cabeçalhos de solicitação:
      • x-ms-encryption-key (cabeçalho ignorado)
      • x-ms-encryption-key (cabeçalho ignorado)
      • x-ms-encryption-algorithm:AES256 (cabeçalho ignorado)
  • Definir camada de acesso
    • Cabeçalhos de solicitação:
      • x-ms-access-tier (cabeçalho ignorado)

Diferenças de cabeçalho de resposta

Como o OneLake usa um modelo de permissão diferente do ADLS Gen2, os cabeçalhos de resposta relacionados às permissões são tratados de maneira diferente:

  • "x-ms-owner" e "x-ms-group" sempre retorna "$superuser" já que o OneLake não tem usuários ou grupos proprietários
  • "x-ms-permissions" sempre retorna "---------" já que o OneLake não tem usuários, grupos ou permissões de acesso público proprietários
  • "x-ms-acl" retorna as permissões do Fabric para o usuário de chamada convertido em uma lista de controle de acesso (ACL) POSIX, no formato "rwx"

Integração de Software Livre

Como o OneLake dá suporte às mesmas APIs que o ADLS Gen2, muitas bibliotecas e pacotes de software livre compatíveis com o ADLS Gen2 funcionam perfeitamente com o OneLake. Outras bibliotecas podem exigir pequenas atualizações para acomodar pontos de extremidade do OneLake ou outros problemas de compatibilidade. As bibliotecas a seguir são confirmadas como compatíveis com o OneLake devido a alterações recentes. Essa lista não é completa:

Exemplos

Listar itens em um workspace

GET https://onelake.dfs.fabric.microsoft.com/myWorkspace?resource=filesystem&recursive=false

Criar uma pasta dentro de um lakehouse

PUT https://onelake.dfs.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/newFolder/?resource=directory

Conteúdo relacionado