连接到 Microsoft OneLake

Microsoft OneLake 通过现有的 Azure Data Lake Storage (ADLS) Gen2 API 和 SDK 提供对所有 Fabric 项的开放访问。 只需改用 OneLake URI 即可通过与 ADLS Gen2 兼容的任何 API、SDK 或工具访问 OneLake 中的数据。 可以通过 Azure 存储资源管理器将数据上传到湖屋,或通过 Azure Databricks 中的快捷方式读取 Delta 表。

由于 OneLake 是软件即服务 (SaaS),因此某些操作(如管理权限或更新项目)必须通过 Fabric 体验来完成,而不是通过 ADLS Gen2 API 完成。 有关这些 API 更改的完整列表,请参阅 OneLake API 一致性

URI 语法

由于 OneLake 存在于整个 Microsoft Fabric 租户中,因此可以按其工作区、项目和路径引用租户中的任何内容:

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

注意

由于可以跨多个项目类型重复使用项名,因此必须在扩展中指定项目类型。 例如,.lakehouse 表示湖屋,.datawarehouse 表示仓库。

OneLake 还支持引用具有全局唯一标识符 (GUID) 的工作区和项。 即使工作区或项目名称发生更改,OneLake 分配的 GUID 和 GUID 也不会更改。 可以在 Fabric 门户的 URL 中找到工作区或项目的关联 GUID。 必须为工作区和项目使用 GUID,并且不需要项目类型。

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

采用用于 OneLake 而不是 ADLS Gen2 的工具时,请使用以下映射:

  • 帐户名始终是 onelake
  • 容器名称是你的工作区名称。
  • 数据路径从项目开始。 例如:/mylakehouse.lakehouse/Files/

OneLake 还支持 Azure Blob 文件系统驱动程序 (ABFS),以便与 ADLS Gen2 和 Azure Blob 存储更加兼容。 ABFS 驱动程序会使用自己的方案标识符“abfs”和不同的 URI 格式来寻址 ADLS Gen2 帐户中的文件和目录。 若要通过 OneLake 使用此 URI 格式,请将工作区交换为文件系统,并包括项和项类型。

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

abfs 驱动程序 URI 不允许在工作区名称中使用特殊字符(如空格)。 在这些情况下,可以使用全局唯一标识符 (GUID) 引用工作区和项,如本节前面所述。

授权

可以通过传递授权标头,使用 Microsoft Entra ID 对 OneLake API 进行身份验证。 如果某个工具支持登录到 Azure 帐户以启用令牌直通,则可以选择任何订阅。 OneLake 仅需要用户令牌,不需要你的 Azure 订阅。

通过 DFS API 直接调用 OneLake 时,可以使用 Microsoft Entra 帐户的持有者令牌进行身份验证。 若要详细了解如何请求和管理组织的持有者令牌,请查看 Microsoft 身份验证库

有关使用直接 API 调用对 OneLake 进行快速即席测试,下面是使用 PowerShell 登录到 Azure 帐户、检索存储范围的令牌并将其复制到剪贴板以便于其他地方使用的简单示例。 若要详细了解如何使用 PowerShell 检索访问令牌,请参阅 Get-AzAccessToken

注意

OneLake 仅支持“Storage”受众中的令牌。 在以下示例中,我们通过 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

数据驻留

如果使用全局端点(“https://onelake.dfs.fabric.microsoft.com”)在与你的工作区区域不同的区域中查询数据,则在端点解析过程中,数据可能会离开你的区域。 如果担心数据驻留,请为工作区使用正确的区域终结点,以确保数据保留在其当前区域内,并且不会跨越任何区域边界。 可以通过检查工作区附加到的容量区域来发现正确的区域终结点。

OneLake 区域终结点都遵循相同的格式:https://<region>-onelake.dfs.fabric.microsoft.com。 例如,附加到美国西部区域中容量的工作区可通过区域端点 https://westus-onelake.dfs.fabric.microsoft.com 访问。

常见问题

如果与 ADLS Gen2 兼容的工具或包无法通过 OneLake 运行,最常见的问题是 URL 验证。 由于 OneLake 使用的终结点 (dfs.fabric.microsoft.com) 与 ADLS Gen2 不同 (dfs.core.windows.net),因此某些工具无法识别 OneLake 终结点并会阻止它。 某些工具允许使用自定义终结点(例如 PowerShell)。 否则,将 OneLake 的终结点添加为支持的终结点通常就能简单地解决这个问题。 如果发现 URL 验证问题,或者在连接到 OneLake 时遇到任何其他问题,请告诉我们

示例

创建文件

请求 PUT https://onelake.dfs.fabric.microsoft.com/{workspace}/{item}.{itemtype}/Files/sample?resource=file
标头 Authorization: Bearer <userAADToken>
响应 ResponseCode: 201 Created
标头:
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
正文: