你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
创建帐户 SAS
从版本 2015-04-05 开始,Azure 存储支持在存储帐户级别创建一种新型共享访问签名 (SAS) 。 通过创建帐户 SAS,可以:
委托对服务特定 SAS 当前不可用的服务级别操作的访问权限,例如
Get/Set Service Properties
和Get Service Stats
操作。一次性委托对存储帐户中多个服务的访问权限。 例如,可以使用帐户 SAS 委托对 Azure Blob 存储和 Azure 文件存储中的资源的访问权限。
委托对容器、队列、表和文件共享的写入和删除操作的访问权限,这些操作不适用于特定于对象的 SAS。
指定要从中接受请求的 IP 地址或 IP 地址范围。
指定从中接受请求的 HTTP 协议, (HTTPS 或 HTTP/HTTPS) 。
帐户 SAS 目前不支持存储访问策略。
注意
共享访问签名是授予存储资源权限的密钥,应像保护帐户密钥一样保护它们。 防止 SAS 被恶意使用或意料之外的使用很重要。 请谨慎分发 SAS,并制定撤销受到安全威胁的 SAS 的计划。 使用共享访问签名的操作应仅通过 HTTPS 连接执行,SAS URI 应仅在安全连接(如 HTTPS)上分发。
授权帐户 SAS
使用存储帐户密钥保护帐户 SAS。 创建帐户 SAS 时,客户端应用程序必须拥有帐户密钥。
若要使用Microsoft Entra凭据来保护容器或 Blob 的 SAS,请创建用户委托 SAS。
构造帐户 SAS URI
帐户 SAS URI 由 SAS 将为其委派访问权限的资源的 URI 组成,后跟 SAS 令牌。 SAS 令牌是包含授权资源请求所需的所有信息的查询字符串。 它指定可供访问的服务、资源和权限,以及签名有效的时间段。
指定帐户 SAS 参数
下表描述了 SAS 令牌的必需参数和可选参数:
SAS 查询参数 | 说明 |
---|---|
api-version |
可选。 指定用于执行使用帐户 SAS URI 发出的请求的存储服务版本。 有关详细信息,请参阅 使用共享访问签名授权请求。 |
SignedVersion (sv) |
必需。 指定用于授权使用此帐户 SAS 发出的请求的已签名存储服务版本。 它必须设置为版本 2015-04-05 或更高版本。 有关详细信息,请参阅 使用共享访问签名授权请求。 |
SignedServices (ss) |
必需。 指定可通过帐户 SAS 访问的已签名服务。 可能的值包括: - Blob ( b )- 队列 ( q )- 表 ( t )- 文件 ( f )可以将值组合在一起,以提供对多个服务的访问权限。 例如, ss=bf 指定对 Blob 存储和Azure 文件存储终结点的访问权限。 |
SignedResourceTypes (srt) |
必需。 指定可使用帐户 SAS 访问的已签名资源类型。 - 服务 ( s ) :访问服务级别 API (,例如,获取/设置服务属性、获取服务统计信息、列出容器/队列/表/共享) 。- 容器 ( c ) :访问容器级 API (例如,创建/删除容器、创建/删除队列、创建/删除表、创建/删除共享、列出 Blob/文件和目录) 。- 对象 ( o ) :访问 blob、队列消息、表实体和文件的对象级 API, (例如放置 Blob、查询实体、获取消息、创建文件) 。可以将值组合在一起,以提供对多个资源类型的访问权限。 例如, srt=sc 指定对服务和容器资源的访问权限。 |
SignedPermissions (sp) |
必需。 指定帐户 SAS 的已签名权限。 仅当权限与指定的签名资源类型匹配时,权限才有效。 如果不匹配,则忽略它们。 - 读取 ( r ):对所有已签名的资源类型(服务、容器和对象)有效。 允许对指定的资源类型的读取权限。- 写入 ( w ):对所有已签名的资源类型(服务、容器和对象)有效。 允许对指定的资源类型进行写入访问,允许用户创建和更新资源。- 删除 ( d ):对容器和对象资源类型有效,但队列消息除外。- 永久删除 ( y ):仅对 Blob 的对象资源类型有效。- 列出 ( l ):仅对服务和容器资源类型有效。- 添加 ( a ):仅对以下对象资源类型有效:队列消息、表实体和追加 Blob。- 创建 ( c ) :对容器资源类型和以下对象资源类型有效:blob 和文件。 用户可以创建新资源,但不能覆盖现有资源。- 更新 ( u ):仅对以下对象资源类型有效:队列消息和表实体。- 处理 ( p ):仅对以下对象资源类型有效:队列消息。- 标记 ( t ):仅对以下对象资源类型有效:Blob。 允许 Blob 标记操作。- 筛选 ( f ):仅对以下对象资源类型有效:Blob。 允许按 Blob 标记进行筛选。- 设置不可变性策略 ( i ):仅对以下对象资源类型有效:Blob。 允许对 Blob 设置/删除不可变性策略和法定保留。 |
SignedStart (st) |
可选。 SAS 生效的时间,以接受的 ISO 8601 UTC 格式之一表示。 如果省略,则假定开始时间是存储服务接收请求的时间。 有关接受的 UTC 格式的详细信息,请参阅 设置 DateTime 值的格式。 |
SignedExpiry (se) |
必需。 共享访问签名无效的时间,以接受的 ISO 8601 UTC 格式之一表示。 有关接受的 UTC 格式的详细信息,请参阅 设置 DateTime 值的格式。 |
SignedIP (sip) |
可选。 指定要从中接受请求的 IP 地址或 IP 地址范围。 指定范围时,请记住,该范围是非独占的。 仅支持 IPv4 地址。 例如 sip=168.1.5.65 或 sip=168.1.5.60-168.1.5.70 。 |
SignedProtocol (spr) |
可选。 指定允许使用帐户 SAS 发出的请求的协议。 可能的值为“HTTPS 和 HTTP”(https,http ) 或“仅 HTTPS”(https )。 默认值是 https,http 。请注意,“仅限 HTTP”是不允许的值。 |
SignedEncryptionScope (ses) |
可选。 指示用于加密请求内容的加密范围。 版本 2020-12-06 及更高版本支持此字段。 |
Signature (sig) |
必需。 URI 的签名部分用于授权使用共享访问签名发出的请求。 string-to-sign 是一个唯一字符串,它由必须验证才能授权请求的字段构造而成。 签名是基于哈希的消息身份验证代码, (HMAC) 使用 SHA256 算法通过字符串到签名和密钥计算,然后使用 Base64 编码进行编码。 |
指定 signedVersion
字段
“ signedVersion
(sv
) ”字段包含共享访问签名的服务版本。 此值指定) 字段中此共享访问签名 (signature
使用的共享密钥授权版本。 值还指定使用此共享访问签名发出的请求的服务版本。
有关通过共享访问签名执行请求时使用哪个版本的信息,请参阅 Azure 存储服务的版本控制。
有关此参数如何影响使用共享访问签名发出的请求的授权的信息,请参阅 使用共享访问签名委托访问权限。
字段名称 | 查询参数 | 说明 |
---|---|---|
signedVersion |
sv |
必需。 在版本 2015-04-05 及更高版本中受支持。 用于授权和处理使用此共享访问签名发出的请求的存储服务版本。 有关详细信息,请参阅 Azure 存储服务的版本控制。 |
指定 IP 地址或 IP 范围
从版本 2015-04-05 开始,可选的 signedIp
(sip
) 字段指定接受请求的公共 IP 地址或公共 IP 地址范围。 如果请求源自的 IP 地址与 SAS 令牌上指定的 IP 地址或地址范围不匹配,则请求未获得授权。 仅支持 IPv4 地址。
指定 IP 地址范围时,请记住该范围是非独占的。例如,在 sip=168.1.5.65
SAS 上指定 或 sip=168.1.5.60-168.1.5.70
会将请求限制为这些 IP 地址。
下表说明是否根据客户端环境和存储帐户的位置,在指定方案的 SAS 令牌上包括 signedIp
字段。
客户端环境 | 存储帐户位置 | 建议 |
---|---|---|
在 Azure 中运行的客户端 | 与客户端位于同一区域中 | 在此方案中提供给客户端的 SAS 不应包含 字段的 signedIp 出站 IP 地址。 使用具有指定出站 IP 地址的 SAS 的同一区域中发出的请求将失败。请改用 Azure 虚拟网络来管理网络安全限制。 从同一区域中向 Azure 存储发出的请求始终通过专用 IP 地址进行。 有关详细信息,请参阅配置 Azure 存储防火墙和虚拟网络。 |
在 Azure 中运行的客户端 | 在与客户端不同的区域中 | 在此方案中提供给客户端的 SAS 可能包括字段的公共 IP 地址或地址 signedIp 范围。 使用 SAS 发出的请求必须源自指定的 IP 地址或地址范围。 |
在本地或其他云环境中运行的客户端 | 在任何 Azure 区域中 | 在此方案中提供给客户端的 SAS 可能包括字段的公共 IP 地址或地址 signedIp 范围。 使用 SAS 发出的请求必须源自指定的 IP 地址或地址范围。如果请求通过代理或网关传递,请为 signedIp 字段提供该代理或网关的公共出站 IP 地址。 |
指定 HTTP 协议
从版本 2015-04-05 开始,可选的 signedProtocol
(spr
) 字段指定允许使用 SAS 发出的请求的协议。 可能的值为“HTTPS 和 HTTP”(https,http
) 或“仅 HTTPS”(https
)。 默认值是 https,http
。 请注意,“仅限 HTTP”是不允许的值。
指定加密范围
通过使用 signedEncryptionScope
URI 上的 字段,可以指定客户端应用程序可以使用的加密范围。 使用 SAS 令牌上传 blob (PUT) 时,它会使用指定的加密范围强制实施服务器端加密。 GET 和HEAD不会像以前一样受到限制和执行。
下表介绍如何在 URI 上引用已签名的加密范围:
字段名称 | 查询参数 | 说明 |
---|---|---|
signedEncryptionScope |
ses |
可选。 指示用于加密请求内容的加密范围。 |
版本 2020-12-06 或更高版本支持此字段。 如果在支持的版本之前添加 ses
,则服务将返回错误响应代码 403 (禁止) 。
如果为容器或文件系统设置默认加密范围,则 ses
查询参数将遵循容器加密策略。 如果查询参数和x-ms-default-encryption-scope
标头不匹配ses
,并且x-ms-deny-encryption-scope-override
标头设置为 true
,则服务将返回错误响应代码 403 (禁止) 。
在 PUT 请求中提供 x-ms-encryption-scope
标头和 ses
查询参数时,如果不匹配,服务将返回错误响应代码 400 (错误请求) 。
构造签名字符串
若要为帐户 SAS 构造签名字符串,请首先从构成请求的字段构造字符串到签名,然后将字符串编码为 UTF-8,并使用 HMAC-SHA256 算法计算签名。
注意
字符串到签名中包含的字段必须进行 URL 解码。
若要构造帐户 SAS 的字符串到签名,请使用以下格式:
StringToSign = accountname + "\n" +
signedpermissions + "\n" +
signedservice + "\n" +
signedresourcetype + "\n" +
signedstart + "\n" +
signedexpiry + "\n" +
signedIP + "\n" +
signedProtocol + "\n" +
signedversion + "\n"
版本 2020-12-06 添加了对已签名加密范围字段的支持。 若要构造帐户 SAS 的字符串到签名,请使用以下格式:
StringToSign = accountname + "\n" +
signedpermissions + "\n" +
signedservice + "\n" +
signedresourcetype + "\n" +
signedstart + "\n" +
signedexpiry + "\n" +
signedIP + "\n" +
signedProtocol + "\n" +
signedversion + "\n" +
signedEncryptionScope + "\n"
帐户 SAS 权限(按操作)
以下部分中的表列出了每个服务的各种 API,以及每个操作支持的已签名资源类型和已签名权限。
Blob 服务
下表列出了 Blob 服务操作,并指示在委派对这些操作的访问权限时要指定的已签名资源类型和已签名权限。
操作 | 已签名服务 | 已签名资源类型 | 已签名权限 |
---|---|---|---|
列出容器 | Blob (b) | 服务 () | 列出 (l) |
获取 BLOB 服务属性 | Blob (b) | 服务 () | 读取 (r) |
设置 Blob 服务属性 | Blob (b) | 服务 () | 使用) 编写 ( |
获取 Blob 服务统计信息 | Blob (b) | 服务 () | 读取 (r) |
创建容器 | Blob (b) | 容器 (c) | 使用) 创建 (c) 或写入 ( |
获取容器属性 | Blob (b) | 容器 (c) | 读取 (r) |
获取容器元数据 | Blob (b) | 容器 (c) | 读取 (r) |
设置容器元数据 | Blob (b) | 容器 (c) | 使用) 编写 ( |
租赁容器 | Blob (b) | 容器 (c) | 写入 (w) 或删除 (d) 1 |
删除容器 | Blob (b) | 容器 (c) | 删除 (d) 1 |
在容器中按标记查找 Blob | Blob (b) | 容器 (c) | 筛选 (f) |
列出 Blob | Blob (b) | 容器 (c) | 列出 (l) |
将 Blob (创建新的块 blob) | Blob (b) | 对象 (o) | 使用) 创建 (c) 或写入 ( |
放置 Blob (覆盖现有块 blob) | Blob (b) | 对象 (o) | 使用) 编写 ( |
将 Blob (创建新的页 blob) | Blob (b) | 对象 (o) | 使用) 创建 (c) 或写入 ( |
将 Blob (覆盖现有页 blob) | Blob (b) | 对象 (o) | 使用) 编写 ( |
获取 Blob | Blob (b) | 对象 (o) | 读取 (r) |
获取 Blob 属性 | Blob (b) | 对象 (o) | 读取 (r) |
设置 Blob 属性 | Blob (b) | 对象 (o) | 使用) 编写 ( |
获取 Blob 元数据 | Blob (b) | 对象 (o) | 读取 (r) |
设置 Blob 元数据 | Blob (b) | 对象 (o) | 使用) 编写 ( |
获取 Blob 标记 | Blob (b) | 对象 (o) | 标记 (t) |
设置 Blob 标记 | Blob (b) | 对象 (o) | 标记 (t) |
按标记查找 Blob | Blob (b) | 对象 (o) | 筛选 (f) |
删除 Blob | Blob (b) | 对象 (o) | 删除 (d) 1 |
永久删除快照/版本 | Blob (b) | 对象 (o) | 永久删除 (y) |
租赁 Blob | Blob (b) | 对象 (o) | 写入 (w) 或删除 (d) 1 |
快照 Blob | Blob (b) | 对象 (o) | 使用) 创建 (c) 或写入 ( |
复制 Blob (目标是新的 blob) | Blob (b) | 对象 (o) | 使用) 创建 (c) 或写入 ( |
复制 Blob (目标是现有的 blob) | Blob (b) | 对象 (o) | 使用) 编写 ( |
增量复制 | Blob (b) | 对象 (o) | 使用) 创建 (c) 或写入 ( |
中止复制 Blob | Blob (b) | 对象 (o) | 使用) 编写 ( |
放置块 | Blob (b) | 对象 (o) | 使用) 编写 ( |
将块列表 (创建新的 blob) | Blob (b) | 对象 (o) | 使用) 编写 ( |
将块列表 (更新现有 blob) | Blob (b) | 对象 (o) | 使用) 编写 ( |
获取阻止列表 | Blob (b) | 对象 (o) | 读取 (r) |
放置页面 | Blob (b) | 对象 (o) | 使用) 编写 ( |
获取页面范围 | Blob (b) | 对象 (o) | 读取 (r) |
追加块 | Blob (b) | 对象 (o) | 使用) 添加 () 或写入 ( |
清除页面 | Blob (b) | 对象 (o) | 使用) 编写 ( |
1 权限 Delete
允许中断 2017-07-29 及更高版本的 Blob 或容器上的租约。
队列服务
下表列出了队列服务操作,并指示在委派对这些操作的访问权限时要指定的已签名资源类型和已签名权限。
操作 | 已签名服务 | 已签名的资源类型 | 已签名的权限 |
---|---|---|---|
获取队列服务属性 | 队列 (q) | 服务 () | 读取 (r) |
设置队列服务属性 | 队列 (q) | 服务 () | 使用) 编写 ( |
列出队列 | 队列 (q) | 服务 () | 列出 (l) |
获取队列服务统计信息 | 队列 (q) | 服务 () | 读取 (r) |
创建队列 | 队列 (q) | 容器 (c) | 使用) 创建 (c) 或写入 ( |
删除队列 | 队列 (q) | 容器 (c) | 删除 (d) |
获取队列元数据 | 队列 (q) | 容器 (c) | 读取 (r) |
设置队列元数据 | 队列 (q) | 容器 (c) | 使用) 编写 ( |
放置消息 | 队列 (q) | 对象 (o) | 添加 () |
获取消息 | 队列 (q) | 对象 (o) | 进程 (p) |
查看消息 | 队列 (q) | 对象 (o) | 读取 (r) |
删除消息 | 队列 (q) | 对象 (o) | 进程 (p) |
清除消息 | 队列 (q) | 对象 (o) | 删除 (d) |
更新消息 | 队列 (q) | 对象 (o) | 更新 (u) |
表服务
下表列出了表服务操作,并指示在将访问权限委托给这些操作时要指定的已签名资源类型和已签名权限。
操作 | 已签名服务 | 已签名的资源类型 | 已签名权限 |
---|---|---|---|
获取表服务属性 | 表 (t) | 服务 () | 读取 (r) |
设置表服务属性 | 表 (t) | 服务 () | 使用) 编写 ( |
获取表服务统计信息 | 表 (t) | 服务 () | 读取 (r) |
查询表 | 表 (t) | 容器 (c) | 列出 (l) |
创建表 | 表 (t) | 容器 (c) | 使用) 创建 (c) 或写入 ( |
删除表 | 表 (t) | 容器 (c) | 删除 (d) |
查询实体 | 表 (t) | 对象 (o) | 读取 (r) |
插入实体 | 表 (t) | 对象 (o) | 添加 () |
插入或合并实体 | 表 (t) | 对象 (o) | 添加 () 和更新 (u) 1 |
插入或替换实体 | 表 (t) | 对象 (o) | 添加 () 和更新 (u) 1 |
更新实体 | 表 (t) | 对象 (o) | 更新 (u) |
合并实体 | 表 (t) | 对象 (o) | 更新 (u) |
删除实体 | 表 (t) | 对象 (o) | 删除 (d) |
1 对表服务执行更新插入操作需要“添加”和“更新”权限。
文件服务
下表列出了文件服务操作,并指示在委派对这些操作的访问权限时要指定的已签名资源类型和已签名权限。
操作 | 已签名服务 | 已签名资源类型 | 已签名权限 |
---|---|---|---|
列出共享 | 文件 (f) | 服务 () | 列出 (l) |
获取文件服务属性 | 文件 (f) | 服务 () | 读取 (r) |
设置文件服务属性 | 文件 (f) | 服务 () | 使用) 编写 ( |
获取共享统计信息 | 文件 (f) | 容器 (c) | 读取 (r) |
创建共享 | 文件 (f) | 容器 (c) | 使用) 创建 (c) 或写入 ( |
快照共享 (Snapshot Share) | 文件 (f) | 容器 (c) | 使用) 创建 (c) 或写入 ( |
获取共享属性 | 文件 (f) | 容器 (c) | 读取 (r) |
设置共享属性 | 文件 (f) | 容器 (c) | 使用) 编写 ( |
获取共享元数据 | 文件 (f) | 容器 (c) | 读取 (r) |
设置共享元数据 | 文件 (f) | 容器 (c) | 使用) 编写 ( |
删除共享 | 文件 (f) | 容器 (c) | 删除 (d) |
列出目录和文件 | 文件 (f) | 容器 (c) | 列出 (l) |
创建目录 | 文件 (f) | 对象 (o) | 使用) 创建 (c) 或写入 ( |
获取目录属性 | 文件 (f) | 对象 (o) | 读取 (r) |
获取目录元数据 | 文件 (f) | 对象 (o) | 读取 (r) |
设置目录元数据 | 文件 (f) | 对象 (o) | 使用) 编写 ( |
删除目录 | 文件 (f) | 对象 (o) | 删除 (d) |
创建文件 (创建新) | 文件 (f) | 对象 (o) | 使用) 创建 (c) 或写入 ( |
创建文件 (覆盖现有) | 文件 (f) | 对象 (o) | 使用) 编写 ( |
获取文件 | 文件 (f) | 对象 (o) | 读取 (r) |
获取文件属性 | 文件 (f) | 对象 (o) | 读取 (r) |
获取文件元数据 | 文件 (f) | 对象 (o) | 读取 (r) |
设置文件元数据 | 文件 (f) | 对象 (o) | 使用) 编写 ( |
删除文件 | 文件 (f) | 对象 (o) | 删除 (d) |
重命名文件 | 文件 (f) | 对象 (o) | 使用) 删除 (d) 或写入 ( |
放置范围 | 文件 (f) | 对象 (o) | 使用) 编写 ( |
列出范围 | 文件 (f) | 对象 (o) | 读取 (r) |
中止复制文件 | 文件 (f) | 对象 (o) | 使用) 编写 ( |
复制文件 | 文件 (f) | 对象 (o) | 使用) 编写 ( |
清除范围 | 文件 (f) | 对象 (o) | 使用) 编写 ( |
帐户 SAS URI 示例
以下示例显示了一个 Blob 服务 URI,其中追加了帐户 SAS 令牌。 帐户 SAS 令牌提供对服务、容器和对象的权限。 该表对 URI 的每个部分进行细分:
https://blobsamples.blob.core.windows.net/?sv=2022-11-02&ss=b&srt=sco&sp=rwlc&se=2023-05-24T09:51:36Z&st=2023-05-24T01:51:36Z&spr=https&sig=<signature>
名称 | SAS 部分 | 说明 |
---|---|---|
资源 URI | https://myaccount.blob.core.windows.net/?restype=service&comp=properties |
服务终结点,其参数用于在使用 GET) 调用时获取服务属性 (,或使用 SET) 调用时 (设置服务属性。 根据已签名服务字段 (ss ) 的值,此 SAS 可用于 Blob 存储或Azure 文件存储。 |
分隔符 | ? |
查询字符串前面的分隔符。 分隔符不是 SAS 令牌的一部分。 |
存储服务版本 | sv=2022-11-02 |
对于 Azure 存储服务版本 2012-02-12 及更高版本,此参数指示要使用的版本。 |
服务 | ss=b |
SAS 适用于 Blob 服务。 |
资源类型 | srt=sco |
SAS 适用于服务级别、容器级和对象级操作。 |
权限 | sp=rwlc |
权限授予读取、写入、列出和创建操作的访问权限。 |
开始时间 | st=2019-08-01T22%3A18%3A26Z |
以 UTC 时间格式指定。 如果想要 SAS 立即生效,则省略开始时间。 |
到期时间 | se=2019-08-10T02%3A23%3A26Z |
以 UTC 时间格式指定。 |
协议 | spr=https |
仅允许使用 HTTPS 的请求。 |
签名 | sig=<signature> |
用于授予对 Blob 的访问权限。 签名是 HMAC,它通过使用 SHA256 算法通过字符串到签名和密钥进行计算,然后使用 Base64 编码进行编码。 |
由于权限仅限于服务级别,因此使用此 SAS 的可访问操作是 获取 Blob 服务属性 (读取) 和 设置 Blob 服务属性 (写入) 。 但是,使用其他资源 URI,同一个 SAS 令牌还可用于委派对获取 Blob 服务统计信息(读取)的访问权限。