你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

为 Blob 服务操作指定条件标头

一些 Blob 服务操作支持使用条件标头。 你可以指定条件标头,以便仅在符合指定条件时才执行操作。

Blob 服务遵循条件标头的 HTTP/1.1 协议规范

支持的条件标头

下表说明了支持的条件标头。

条件标头 说明
If-Modified-Since 一个 DateTime 值。 日期格式遵循 RFC 1123。 有关详细信息,请参阅 标头中的日期时间值的表示形式。 指定此标头,以便仅在指定的时间后修改了资源时才执行操作。
If-Unmodified-Since 一个 DateTime 值。 日期格式遵循 RFC 1123。 有关详细信息,请参阅 标头中的日期时间值的表示形式。 指定此标头,以便仅在指定的日期/时间后未修改资源时才执行操作。
If-Match ETag 值。 指定此标头,以便仅在资源的 ETag 与指定的值匹配时才执行操作。 对于 2011-08-18 和更高版本,可以将指定的 ETag 用引号引起来。
If-None-Match ETag 值或通配符 (*)。 指定此标头,以便仅在资源的 ETag 与指定的值不匹配时才执行操作。 对于 2011-08-18 和更高版本,可以将指定的 ETag 用引号引起来。

指定通配符 (*),以便仅在资源不存在以及资源存在但操作失败时才执行操作。

在版本 2013-08-15 或更高版本中为 Blob 服务读取操作指定条件标头

从版本 2013-08-15 开始, 获取 Blob获取 Blob 属性 操作支持多个条件标头。 你可以指定支持的条件标头的任意组合。 Blob 服务将根据以下这些表达式对这些条件进行求值:

If-Match && If-Unmodified-Since && (If-None-Match || If-Modified-Since)

也可以为 If-MatchIf-None-Match 提供多个逗号分隔的值。 如果为 If-Match 指定多个值,则 Blob 服务将在计算整个表达式之前对所有提供的值执行逻辑 OR 操作。 如果为 if-None-Match 指定多个值,则 Blob 服务将在计算整个表达式之前执行逻辑 AND 操作。 不支持为 If-Modified-SinceIf-Unmodified-Since 指定多个值,因此将生成错误代码 400 (Bad Request)。

启用此功能是为了遵守 HTTP/1.1 规范 ,并满足内容分发网络 (CDN) 或代理服务器将其他条件标头添加到机内请求的方案。 下面是条件标头的不同组合的一些示例。

示例 1:

请考虑包含 和 If-Modified-Since 标头的If-Match获取 Blob 请求。 下表指示单独计算标头时的结果以及组合计算标头时的结果。

条件标头 单独计算时的结果 组合计算时的结果
If-Match 412(不满足前提条件) 412(不满足前提条件)
If-Modified-Since 200 (正常) 412(不满足前提条件)
If-Match 412(不满足前提条件) 412(不满足前提条件)
If-Modified-Since 304(未修改) 412(不满足前提条件)
If-Match 200 (正常) 200 (正常)
If-Modified-Since 200 (正常) 200 (正常)
If-Match 200 (正常) 304(未修改)
If-Modified-Since 304(未修改) 304(未修改)

示例 2:

考虑包含 If-None-MatchIf-Modified-Since 标头的请求。

条件标头 单独计算时的结果 组合计算时的结果
If-None-Match 304(未修改) 200 (正常)
If-Modified-Since 200 (正常) 200 (正常)
If-None-Match 200 (正常) 200 (正常)
If-Modified-Since 200 (正常) 200 (正常)
If-None-Match 200 (正常) 200 (正常)
If-Modified-Since 304(未修改) 200 (正常)
If-None-Match 304(未修改) 304(未修改)
If-Modified-Since 304(未修改) 304(未修改)

示例 3:

考虑包含 If-Modified-SinceIf-MatchIf-Unmodified-Since 标头的请求。

条件标头 单独计算时的结果 组合计算时的结果
If-Modified-Since 200 (正常) 412(不满足前提条件)
If-Match 412(不满足前提条件) 412(不满足前提条件)
If-Unmodified-Since 200 (正常) 412(不满足前提条件)
If-Modified-Since 200 (正常) 412(不满足前提条件)
If-Match 200 (正常) 412(不满足前提条件)
If-Unmodified-Since 412(不满足前提条件) 412(不满足前提条件)
If-Modified-Since 304(未修改) 412(不满足前提条件)
If-Match 200 (正常) 412(不满足前提条件)
If-Unmodified-Since 412(不满足前提条件) 412(不满足前提条件)
If-Modified-Since 304(未修改) 304(未修改)
If-Match 200 (正常) 304(未修改)
If-Unmodified-Since 200 (正常) 304(未修改)

示例 4:

考虑包含 If-Modified-SinceIf-None-MatchIf-Unmodified-SinceIf-Match 标头的请求。

组合 单个 http 状态代码 “获取 Blob”状态结果
If-Modified-Since 200 (正常) 200 (正常)
If-None-Match 200 (正常) 200 (正常)
If-Unmodified-Since 200 (正常) 200 (正常)
If-Match 200 (正常) 200 (正常)
If-Modified-Since 200 (正常) 412(不满足前提条件)
If-None-Match 304(未修改) 412(不满足前提条件)
If-Unmodified-Since 412(不满足前提条件) 412(不满足前提条件)
If-Match 200 (正常) 412(不满足前提条件)
If-Modified-Since 200 (正常) 200 (正常)
If-None-Match 304(未修改) 200 (正常)
If-Unmodified-Since 200 (正常) 200 (正常)
If-Match 200 (正常) 200 (正常)
If-Modified-Since 304(未修改) 412(不满足前提条件)
If-None-Match 200 (正常) 412(不满足前提条件)
If-Unmodified-Since 200 (正常) 412(不满足前提条件)
If-Match 412(不满足前提条件) 412(不满足前提条件)
If-Modified-Since 304(未修改) 412(不满足前提条件)
If-None-Match 200 (正常) 412(不满足前提条件)
If-Unmodified-Since 412(不满足前提条件) 412(不满足前提条件)
If-Match 412(不满足前提条件) 412(不满足前提条件)
If-Modified-Since 304(未修改) 200 (正常)
If-None-Match 200 (正常) 200 (正常)
If-Unmodified-Since 200 (正常) 200 (正常)
If-Match 200 (正常) 200 (正常)
If-Modified-Since 304(未修改) 412(不满足前提条件)
If-None-Match 304(未修改) 412(不满足前提条件)
If-Unmodified-Since 412(不满足前提条件) 412(不满足前提条件)
If-Match 200 (正常) 412(不满足前提条件)

在 2013-08-15 之前的版本中指定读取操作的条件标头并在所有版本中指定写入操作的条件标头

(获取 Blob获取 Blob 属性) 2013-08-15 版本调用 Blob 服务读取操作时,无论版本如何,调用任何写入操作时,请记住以下事项:

  • 如果请求指定了 If-None-MatchIf-Modified-Since 标头,则根据在 If-None-Match 中指定的条件评估请求。

  • 如果请求指定了 If-MatchIf-Unmodified-Since 标头,则根据在 If-Match 中指定的条件评估请求。

  • 除了上面列出的两个条件标头组合以外,每个请求只能指定一个条件标题。 指定多个条件标头将导致返回状态代码 400 (Bad Request)。

  • 如果响应包含 ETag,请在处理 ETag 之前验证请求和响应的版本。 例如,版本 2011-08-18 和更高版本返回带引号的 ETag,但以前的版本不带引号。 在评估之前,请确保你的应用程序可以处理这两种 ETag 格式。

  • RFC 2616 允许在单个标头中使用多个 ETag 值,但对 Blob 服务的请求只能包含一个 ETag 值。 指定多个 ETag 值将导致返回状态代码 400 (Bad Request)。

支持条件标头的操作

下表说明了支持条件标头的操作。

REST 操作 操作类型 支持的条件标头
追加块

(版本 2015-02-21 及更高版本)
写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
从 URL 追加块

(版本 2018-11-09 及更高版本)
写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
复制 Blob 读和写 对于目标 Blob 上的条件:

- If-Modified-Since

- If-Unmodified-Since

- If-Match

- If-None-Match

- x-ms-if-tags

对于源 Blob 上的条件:

- x-ms-source-if-modified-since

- x-ms-source-if-unmodified-since

- x-ms-source-if-match

- x-ms-source-if-none-match

- x-ms-source-if-tags
删除 Blob 写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
删除容器 写入 If-Modified-Since

If-Unmodified-Since
获取 Blob 读取 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
获取 Blob 元数据 读取 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
获取 Blob 属性 读取 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
获取 Blob 标记

(版本 2019-12-12 及更高版本)
读取 x-ms-if-tags
获取阻止列表 读取 x-ms-if-tags
获取页面范围 读取 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
租用 Blob 写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
Lease Container(租赁容器) 写入 If-Modified-Since

If-Unmodified-Since
从 URL 放置 Blob 写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

对于源 Blob 上的条件:

- x-ms-source-If-Modified-Since

- x-ms-source-if-Unmodified-Since

- x-ms-source-If-Match

- x-ms-source-If-None-Match

放置 Blob 写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
从 URL 放置块

(版本 2018-03-28 及更高版本)
写入 x-ms-source-If-Modified-Since

x-ms-source-If-Unmodified-Since

x-ms-source-If-Match

x-ms-source-If-None-Match
放置块列表 写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
放置页 写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
从 URL 放置页

(版本 2018-11-09 及更高版本)
写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
设置 Blob 元数据 写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
设置 Blob 属性 写入 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
Set Container ACL 写入 If-Modified-Since

If-Unmodified-Since
设置容器元数据 写入 If-Modified-Since
设置 Blob 标记

(版本 2019-12-12 及更高版本)
写入 x-ms-if-tags
设置 Blob 层 写入 x-ms-if-tags
快照 Blob 读取 If-Modified-Since

If-Unmodified-Since

If-Match

If-None-Match

x-ms-if-tags
设置 Blob 不可变性策略 写入 If-Unmodified-Since

以下 Blob 服务数据操作当前不支持条件标头:

支持条件标头的操作的 HTTP 响应代码

如果请求包含条件标头,并且请求的资源不符合指定的条件,Blob 服务将返回 HTTP 响应代码。 返回的响应代码遵循 HTTP/1.1 协议规范 (RFC 2616)。

Azure .NET 客户端库中的方法将这些错误响应代码转换为 StorageException 对象。

读取操作

下表指示了在执行读取操作时为每个条件标头的不符合条件返回的响应代码。 读取操作使用 GET 或 HEAD 动词。

条件标头 不符合条件时的响应代码
If-Modified-Since 未修改 (304 (Not Modified))
If-Unmodified-Since 不满足前提条件 (412 (Precondition Failed))
If-Match 不满足前提条件 (412 (Precondition Failed))
If-None-Match 未修改 (304 (Not Modified))

在对版本 2013-08-15 或更高版本使用多个标头时,请参考上面的示例获取结果。

写入操作

下表指示了在执行写入操作时为每个条件标头的不符合条件返回的响应代码。 写入操作使用 PUT 或 DELETE 动词。

条件标头 不符合条件时的响应代码
If-Modified-Since 不满足前提条件 (412 (Precondition Failed))
If-Unmodified-Since 不满足前提条件 (412 (Precondition Failed))
If-Match 不满足前提条件 (412 (Precondition Failed))
If-None-Match 不满足前提条件 (412 (Precondition Failed))

复制操作

下表指示了在执行复制操作时为每个条件标头的不符合条件返回的响应代码。 复制 Blob 操作使用谓词 PUT。

条件标头 不符合条件时的响应代码
If-Modified-Since 不满足前提条件 (412 (Precondition Failed))
If-Unmodified-Since 不满足前提条件 (412 (Precondition Failed))
If-Match 不满足前提条件 (412 (Precondition Failed))
If-None-Match 不满足前提条件 (412 (Precondition Failed))
x-ms-source-if-modified-since 不满足前提条件 (412 (Precondition Failed))
x-ms-source-if-unmodified-since 不满足前提条件 (412 (Precondition Failed))
x-ms-source-if-match 不满足前提条件 (412 (Precondition Failed))
x-ms-source-if-none-match 不满足前提条件 (412 (Precondition Failed))

标记条件操作

除了 Blob 服务支持的标准 HTTP 条件标头外,多个操作还支持针对 Blob 资源上的标记的条件。

条件标头 说明
x-ms-if-tags 版本 2019-12-12 及更新版本。 一个 TagsPredicate 值。 指定此标头以仅当谓词针对 Blob 标记的计算结果为 true 时才执行操作。
x-ms-source-if-tags 版本 2019-12-12 及更新版本。 仅适用于复制 Blob。 一个 TagsPredicate 值。 仅当谓词针对源 Blob 的标记的计算结果为 true 时,才指定此标头以执行操作。

x-ms-if-tags如果 或 x-ms-source-if-tags 条件标头存在于请求中,并且 TagsPredicate 的计算结果为 false,则 Blob 服务将返回错误代码 412 (操作的前置条件失败) 。

调用方必须有权读取 Blob 上的标记,才能使用 x-ms-if-tagsx-ms-source-if-tags 条件标头。

标记谓词语法

Blob 服务支持标头值的 ANSI SQL WHERE 子句语法的 TagsPredicate 子集。 支持以下运算符:

运算符 说明 示例
= 等于 Status = 'In Progress'
<> 不等于 Status <> 'Done'
> 大于 LastModified > '2018-06-18 20:51:26Z'
>= 大于或等于 Priority >= '05'
< 小于 Age < '032'
<= 小于或等于 Reviewer <= 'Smith'
AND 逻辑与 Name > 'C' AND Name < 'D'
Age > '032' AND Age < '100'
OR 逻辑或 Status = 'Done' or LastModified > '2018-06-18 20:51:26Z'

所有标记值都是字符串,支持的二元关系运算符使用标记值的字典排序。 若要支持非字符串数据类型(包括数字和日期),必须采用适当的填充和可排序格式。 标记值必须用单引号引起来。

如果标记名称是常规 SQL 标识符,则它们可能存在而不转义;如果它们包含任何特殊字符,则必须用双引号分隔 (例如“TagName” = 'TagValue') 。

表达式可能包括多个标记名称和值的比较。 括号 (()) 可用于对逻辑表达式进行分组和控制操作的规范顺序。 最多 TagsPredicate 可以包含 10 个 (10 个) 逻辑操作。

存储服务将拒绝包含无效表达式且错误代码为 400 的任何请求 (错误的请求) 。

另请参阅

Blob 服务概念