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

项目
10/25/2024

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

若要创建 OneLake SAS，必须先请求用户委派密钥，然后使用该密钥对 SAS 进行签名。若要请求用户委派密钥，请调用 “获取用户委派密钥 ”操作。 OneLake SAS 只能授予对数据项中的文件和文件夹的访问权限，不能用于管理操作，例如创建或删除项目或工作区。

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

OneLake SAS 的创建方式类似于Azure 存储用户委托的 SAS，其参数与与Azure 存储兼容的工具和应用程序兼容。

重要

此功能目前为预览版。

分配权限

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

获取 OAuth 2.0 令牌

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

请求用户委派密钥

调用“获取用户委派密钥”操作会将密钥作为一组值返回，这些值用作用户委托 SAS 令牌的参数。这些参数在 “获取用户委派密钥 ”参考和下一部分进行介绍。

当客户端使用 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 时间。由 “获取用户委派密钥 ”操作返回。
`signedKeyExpiryTime`	`ske`	必须	签名密钥结束时采用 UTC 时间。由 “获取用户委派密钥 ”操作返回。
`signedKeyVersion`	`skv`	必须	用于获取用户委派密钥的存储服务版本。由 “获取用户委派密钥 ”操作返回。 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`	可选	指示字符串到签名的规范化Resource 字段中所指定的目录根文件夹中的目录数。仅当 `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、、rdrl、wd和wlrl。不能多次指定权限。

为了确保与现有Azure 存储工具奇偶一致，OneLake 使用与Azure 存储相同的权限格式。 OneLake 评估授予 SAS 的权限 signedPermissions、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 作为复制操作的目标。
删除	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 的不可变性策略或法定保留。

指定签名

（signaturesig）字段用于授权客户端使用共享访问签名发出的请求。字符串到签名是从必须验证以授权请求的字段构造的唯一字符串。签名是通过 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 令牌为 Lakehouse 中的 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 示例

相关内容

反馈

其他资源

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