创建 OneLake 共享访问签名 (SAS)（预览版）

项目
12/03/2024

你可以创建 OneLake SAS，以依托 Microsoft Entra 凭据提供对 OneLake 中文件夹或文件的短期委派访问权限。 OneLake SAS 可以在不支持 Microsoft Entra 的情况下提供对应用程序的临时访问权限，从而允许它们加载数据或充当其他客户应用程序或独立软件供应商 (ISV) 之间的代理。

若要创建 OneLake SAS，必须先请求用户委派密钥，然后使用该密钥对 SAS 进行签名。若要请求用户委派密钥，请调用 Get User Delegation Key 操作。 OneLake SAS 只能授予对数据项中的文件和文件夹的访问权限，且不能用于创建或删除相关项或工作区等管理操作。

OneLake SAS 只能授予对数据项中的文件和文件夹的访问权限，并且不能用于创建工作区或相关项等管理操作。

OneLake SAS 的创建方式与 Azure 存储用户委派的 SAS 类似，所用参数相同以便兼容可与 Azure 存储兼容的工具和应用程序。

重要

此功能目前为预览版。

分配权限

请求用户委派密钥是 Fabric 中的租户级操作。若要请求用户委派密钥，请求用户委派密钥的用户或安全主体必须在 Fabric 租户的一个工作区中至少具有读取权限。请求用户的标识是为了对 SAS 进行身份验证，这意味着该用户必须有权访问他们要授予 SAS 访问权限的数据。

获取 OAuth 2.0 令牌

若要获取用户委派密钥，请首先从 Microsoft Entra ID 请求 OAuth 2.0 令牌。通过提供带有持有者方案的令牌，可授权对 Get User Delegation Key 操作的调用。有关从 Microsoft Entra ID 请求 OAuth 令牌的详细信息，请参阅身份验证流和应用程序方案。

请求用户委派密钥

调用 Get User Delegation Key 操作时会将密钥作为一组值返回，这些值将用作用户委派 SAS 令牌的参数。 Get User Delegation Key 参考文章和下一部分介绍了这些参数。

当客户端使用 OAuth 2.0 令牌请求用户委派密钥时，OneLake 会代表客户端返回用户委派密钥。使用此用户委派密钥创建的 SAS 将获得最高授权，即授予客户端的权限，但范围将缩小到在 SAS 中显式授予的权限。

你可以在用户委派密钥的生存期内创建任意数量的 OneLake SAS。但是，OneLake SAS 和用户委派密钥的有效期最多为一小时，并且不能超过请求它们的令牌的生命周期。这些生存期限制要比 Azure 存储用户委派 SAS 的最大生存期短。

构造用户委派 SAS

下表汇总了 OneLake SAS 令牌支持的字段。后续部分将详细介绍这些参数及其与 Azure 存储 SAS 令牌有何不同。 OneLake 不支持 Azure 存储支持的部分可选参数，使用不受支持的参数构造的 OneLake SAS 将被拒绝。

SAS 字段名称	SAS 令牌参数	状态	说明
`signedVersion`	`sv`	必须	指示用于构造签名字段的服务版本。 OneLake 支持版本“2020-02-10”、2020-12-06 之后的所有版本，以及“2020-02-10”之前的版本。
`signedResource`	`sr`	必须	指定可通过共享访问签名访问哪些资源。只有 Blob (`b`) 和目录 (`d`) 适用于 OneLake。
`signedStart`	`st`	可选	共享访问签名生效的时间。 ISO 8601 UTC 格式。
`signedExpiry`	`se`	必须	共享访问签名过期的时间
`signedPermissions`	`sp`	必须	指示 SAS 可以对资源执行的操作。指定权限部分提供了更多详细信息
`signedObjectId`	`skoid`	必须	标识 Microsoft Entra 安全主体。
`signedtenantId`	`sktid`	必须	指定要在哪个 Microsoft Entra 租户中定义安全主体。
`signedKeyStartTime`	`skt`	可选	签名密钥开始时的 UTC 时间。由 Get User Delegation Key 操作返回。
`signedKeyExpiryTime`	`ske`	必须	签名密钥结束时的 UTC 时间。由 Get User Delegation Key 操作返回。
`signedKeyVersion`	`skv`	必须	用于获取用户委派密钥的存储服务版本。由 Get User Delegation Key 操作返回。 OneLake 支持 2020-02-10 及之前的版本，以及 2020-12-06 及之后的版本
`signedKeyService`	`sks`	必须	用户委派密钥的有效服务。 OneLake 仅支持 Blob 存储 (`sks=b`)。
`signature`	`sig`	必须	签名是一个基于哈希的消息验证码 (HMAC)，使用 SHA256 算法通过字符串到签名和密钥进行计算，然后使用 Base64 编码技术进行编码。
`signedAuthorizedObjectId`	`saoid`	不支持	OneLake SAS 不支持此功能。
`signedUnauthorizedObjectId`	`suoid`	不支持	OneLake SAS 不支持此功能。
`signedCorrelationId`	`suoid`	不支持	OneLake SAS 不支持此参数。
`signedDirectoryDepth`	`sdd`	可选	指示在字符串到签名的 canonicalizedResource 字段中所指定的目录的根文件夹中的目录数。仅在 `sr=d` 时受支持。
`signedEncryptionScope`	`ses`	不支持	OneLake SAS 目前不支持自定义加密范围。
`signedIP`	`sip`	不支持	OneLake SAS 目前不支持 IP 筛选
`signedProtocol`	`spr`	可选	OneLake 仅支持 https 请求。
`Cache-Control` 响应头	`rscc`	不支持	OneLake SAS 不支持此参数。
`Content-Disposition` 响应头	`rscd`	不支持	OneLake SAS 不支持此参数。
`Content-Encoding` 响应头	`rsce`	不支持	OneLake SAS 不支持此参数。
`Content-Language` 响应头	`rscl`	不支持	OneLake SAS 不支持此参数。
`Content Type` 响应头	`rsct`	不支持	OneLake SAS 不支持此参数。

指定权限

在 SAS 令牌上的 signedPermissions (sp) 字段中指定的权限将指示拥有 SAS 的客户端可以对资源执行的操作。

权限可以组合在一起，以允许客户端使用相同的 SAS 执行多个操作。构造 SAS 时，必须按以下顺序添加权限：racwdxltmeop。

有效权限设置的示例包括 rw、rd、rl、wd、wl 和 rl。不能多次指定一个权限。

为了确保与现有 Azure 存储工具的一致性，OneLake 使用与 Azure 存储相同的权限格式。 OneLake 会评估 signedPermissions 中授予 SAS 的权限、Fabric 中签名标识的权限和所有 OneLake 数据访问角色（如果适用）。请注意，某些操作（例如设置权限或删除工作区）通常不允许通过 Azure 存储 API 在 OneLake 上执行，因此授予该权限 (sp=op) 不会允许 OneLake SAS 执行这些操作。

权限	URI 符号	资源	允许的操作
读取	r	目录、Blob	读取容器或目录中任何 Blob 的内容、阻止列表、属性和元数据。使用 Blob 作为复制操作的源。
添加	a	目录、Blob	向追加 Blob 添加块。
创建	c	目录、Blob	编写新的 Blob、创建 Blob 快照或将一个 Blob 复制到新 Blob。
写	w	目录、Blob	创建或写入内容、属性、元数据或阻止列表。创建 Blob 快照或租用 Blob。使用 Blob 作为复制操作的目标。
删除	d	目录、Blob	删除 Blob。
删除版本	x	Blob	删除 blob 版本。
永久删除	y	Blob	永久删除 Blob 快照或版本。
列出	l	Directory	以非递归方式列出 Blob。
标记	t	Blob	读取或写入 Blob 上的标记。
移动	m	目录、Blob	将 Blob 或目录及其内容移动到新位置。
执行	e	目录、Blob	获取系统属性，如果为存储帐户启用了分层命名空间，则同时获取 Blob 的 POSIX ACL。
所有权	o	目录、Blob	设置所有者或所属组。 OneLake 不支持
权限	p	目录、Blob	设置权限。 OneLake 不支持
设置不可变性策略	i	Blob	设置或删除 Blob 的不可变性策略或法定保留。

指定签名

signature (sig) 字段用于使用共享访问签名授权客户端发出的请求。字符串到签名是根据在授权请求时必须验证的字段构造的唯一字符串。签名是使用 SHA256 算法通过字符串到签名和密钥计算的 HMAC，然后会使用 bBase65 编码技术进行编码。

若要构造用户委派 SAS 的签名字符串，请根据相应请求发出的字段创建字符串到签名，将字符串进行 UTF-8 编码，然后使用 HMAC-SHA256 算法计算签名。字符串到签名中包含的字段必须进行 URL 解码。

字符串到签名中所需的字段取决于用于授权 (sv) 字段的服务版本。以下部分介绍支持 OneLake SAS 的版本的字符串到签名配置。

版本 2020-12-06 及更高版本

StringToSign =  signedPermissions + "\n" +
                signedStart + "\n" +
                signedExpiry + "\n" +
                canonicalizedResource + "\n" +
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +
                signedProtocol + "\n" +
                signedVersion + "\n" +
                signedResource + "\n" +
                signedSnapshotTime + "\n" +
                signedEncryptionScope + "\n" +
                rscc + "\n" +
                rscd + "\n" +
                rsce + "\n" +
                rscl + "\n" +
                rsct

版本 2020-01-10

StringToSign =  signedPermissions + "\n" +
                signedStart + "\n" +
                signedExpiry + "\n" +
                canonicalizedResource + "\n" +
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +
                signedProtocol + "\n" +
                signedVersion + "\n" +
                signedResource + "\n" +
                signedSnapshotTime + "\n" +
                rscc + "\n" +
                rscd + "\n" +
                rsce + "\n" +
                rscl + "\n" +
                rsct

低于 2020-02-10 的版本

StringToSign =  signedPermissions + "\n" +  
                signedStart + "\n" +  
                signedExpiry + "\n" +  
                canonicalizedResource + "\n" +  
                signedKeyObjectId + "\n" +
                signedKeyTenantId + "\n" +
                signedKeyStart + "\n" +
                signedKeyExpiry  + "\n" +
                signedKeyService + "\n" +
                signedKeyVersion + "\n" +
                signedAuthorizedUserObjectId + "\n" +
                signedUnauthorizedUserObjectId + "\n" +
                signedCorrelationId + "\n" +
                signedIP + "\n" +  
                signedProtocol + "\n" +  
                signedVersion + "\n" +  
                signedResource + "\n" +
                rscc + "\n" +
                rscd + "\n" +  
                rsce + "\n" +  
                rscl + "\n" +  
                rsct

规范化资源

字符串的 canonicalizedResource 部分是资源的规范化路径。它必须包含 OneLake 终结点和资源名称，并且必须进行 URL 解码。 OneLake 路径必须包含其工作区，目录路径则必须包含对应于 sdd 参数的子目录数。

以下示例演示如何将 OneLake URL 转换为相应的规范化资源。请注意，OneLake 支持 DFS 和 Blob 操作及终结点，并且 OneLake 的帐户名必须是“onelake”。

Blob 文件

URL = https://onelake.blob.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/sales.csv
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/sales.csv"

DFS 目录

URL = https://onelake.dfs.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/
canonicalizedResource = "/blob/onelake/myWorkspace/myLakehouse.Lakehouse/Files/"

OneLake SAS 示例

以下示例显示了一个 OneLake SAS URI，其中追加了 OneLake SAS 令牌。 SAS 令牌可提供对湖屋中“Files”文件夹的读取和写入权限。

https://onelake.blob.fabric.microsoft.com/myWorkspace/myLakehouse.Lakehouse/Files/?sp=rw&st=2023-05-24T01:13:55Z&se=2023-05-24T09:13:55Z&skoid=<object-id>&sktid=<tenant-id>&skt=2023-05-24T01:13:55Z&ske=2023-05-24T09:13:55Z&sks=b&skv=2022-11-02&sv=2022-11-02&sr=d&sig=<signature>

通过

创建 OneLake 共享访问签名 (SAS)（预览版）

分配权限

获取 OAuth 2.0 令牌

请求用户委派密钥

构造用户委派 SAS

指定权限

指定签名

版本 2020-12-06 及更高版本

版本 2020-01-10

低于 2020-02-10 的版本

规范化资源

Blob 文件

DFS 目录

OneLake SAS 示例

反馈

其他资源

通过

创建 OneLake 共享访问签名 (SAS)（预览版）

分配权限

获取 OAuth 2.0 令牌

请求用户委派密钥

构造用户委派 SAS

指定权限

指定签名

版本 2020-12-06 及更高版本

版本 2020-01-10

低于 2020-02-10 的版本

规范化资源

Blob 文件

DFS 目录

OneLake SAS 示例

相关内容

反馈

其他资源