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

获取页面范围

获取页范围操作返回页 Blob 或页 Blob 快照的有效页范围列表。

请求

可以按如下所示构造“获取页面范围”请求。 建议使用 HTTPS。 将 myaccount 替换为存储帐户的名称:

GET 方法请求 URI HTTP 版本
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>

https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>&prevsnapshot=<DateTime>
HTTP/1.1

模拟存储服务 URI

针对模拟存储服务发出请求时,请将模拟器主机名和 Blob 服务端口指定为 127.0.0.1:10000,后跟模拟的存储帐户名称:

GET 方法请求 URI HTTP 版本
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist HTTP/1.1

有关详细信息,请参阅使用用于开发和测试的Azure 存储 Emulator

URI 参数

可以在请求 URI 上指定以下附加参数。

参数 说明
marker 版本 2020-10-02 及更新版本中可选。 该 marker 参数标识使用下一个 GetPageRanges 操作返回的范围部分。 如果返回的范围未完成,该操作将返回响应正文中的标记值。 然后,可以在后续调用中使用标记值来请求下一组范围。

标记值对客户端不透明。
maxresults 版本 2020-10-02 及更新版本中可选。 该 maxresults 参数指定要返回的最大页范围数。 如果请求指定大于 10000 的值,服务器将返回最多 10000 个项目。 如果返回其他结果,服务在 NextMarker 响应元素中返回延续标记。

将 maxresult 设置为小于或等于零的值会导致错误响应代码 400 (错误请求) 。
snapshot 可选。 快照参数是一个不透明的 DateTime 值,如果存在,则指定要从中检索信息的 Blob 快照。 有关使用 Blob 快照的详细信息,请参阅 创建 Blob 的快照
timeout 可选。 timeout 参数以秒表示。 有关详细信息,请参阅 为 Blob 服务操作设置超时
prevsnapshot 版本 2015-07-08 及更新版本中可选。 该 prevsnapshot 参数是一个 DateTime 值,指定响应将仅包含目标 Blob 和上一快照之间更改的页面。 已更改的页面包括已更新和清除的页面。 只要 prevsnapshot 指定的快照是二者中的旧版本,目标 Blob 可能是快照。

请注意,目前仅支持在 2016 年 1 月 1 日或之后创建的 Blob 使用增量快照。

请求标头

下表介绍必需的和可选的请求标头。

请求标头 说明
Authorization 必需。 指定授权方案、帐户名称和签名。 有关详细信息,请参阅授权对Azure 存储的请求
Datex-ms-date 必需。 指定请求的协调世界时 (UTC)。 有关详细信息,请参阅授权对Azure 存储的请求
x-ms-version 对于所有已授权请求,对于匿名请求是可选的。 指定用于此请求的操作的版本。 有关详细信息,请参阅Azure 存储服务的版本控制
Range 可选。 指定要列出范围的字节范围(含该字节)。 如果省略,则返回 Blob 的所有范围。
x-ms-range 可选。 指定要列出范围的字节范围(含该字节)。 如果指定了 Rangex-ms-range,服务将使用 x-ms-range 值。 有关详细信息 ,请参阅指定 Blob 服务操作的范围标头
x-ms-lease-id:<ID> 可选。 如果指定了此标头,只有在符合下面的两个条件时,才会执行此操作:

- Blob 的租约当前处于活动状态。

- 请求中指定的租约 ID 与 Blob 的租约 ID 匹配。

如果指定了此标头并且不符合这两个条件,请求将失败,并且此操作失败并返回状态代码 412(前提条件失败)。
x-ms-previous-snapshot-url 版本 2019-07-07 及更新版本中可选。 指定 previous-snapshot-url 响应将仅包含目标 Blob 和位于指定 URI 的快照之间更改的页面。 已更改的页面包括已更新和清除的页面。 只要此标头指定的快照较旧,目标 Blob 可能是快照。

请注意,目前仅支持在 2016 年 1 月 1 日或之后创建的 Blob 创建增量快照,并且此标头只应在托管磁盘方案中使用。 否则,请使用 prevsnapshot 参数。
x-ms-client-request-id 可选。 提供客户端生成的不透明值,该值具有 1 KiB 字符限制,在启用存储分析日志记录时记录在分析日志中。 强烈建议使用此标头将客户端活动与服务器接收的请求相关联。 有关详细信息,请参阅关于存储分析日志记录和 Azure 日志记录:使用日志跟踪存储请求

此操作还支持仅在满足指定条件时才使用条件标头来获取页范围。 有关详细信息,请参阅为 Blob 服务操作指定条件标头

请求正文

无。

响应

响应包含 HTTP 状态代码、一组响应标头以及响应正文。

状态代码

此操作成功后返回状态代码 200(正常)。

有关状态代码的信息,请参阅 “状态”和“错误代码”。

响应标头

此操作的响应包括以下标头。 该响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范

语法 说明
Last-Modified 上次修改 Blob 的日期/时间。 日期格式遵循 RFC 1123。

修改 Blob 的任何操作将会更改 Blob 的上次修改时间,包括更新 Blob 的元数据或属性。
ETag ETag 包含一个值,客户端可以使用该值有条件地执行操作。 如果请求版本为 2011-08-18 和更高版本,ETag 值将用引号引起来。
x-ms-blob-content-length Blob 大小,以字节为单位。
x-ms-request-id 此标头唯一地标识发出的请求,并且可用于解决请求问题。 有关详细信息,请参阅 API 操作疑难解答
x-ms-version 指示用于执行请求的 BLOB 服务的版本。 针对 2009-09-19 和更高版本发出的请求将返回此标头。

如果使用 BLOB 服务的 2009-09-19 版将容器标记为公共访问,则也会为未指定版本的匿名请求返回此标头。
Date 服务生成的 UTC 日期/时间值指示启动响应的时间。
x-ms-client-request-id 此标头可用于对请求和相应的响应进行故障排除。 如果此标头存在于请求中并且该值最多为 1024 个可见 ASCII 字符, x-ms-client-request-id 则此标头的值等于标头的值。 如果请求中不存在标头 x-ms-client-request-id ,则响应中将不会显示此标头。

响应正文

响应正文包含有效的非重叠页面范围列表,这是按照递增的地址页面范围排序的。 响应正文的格式如下所示。

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
</PageList>  

如果已清除 Blob 的整个页面集,响应正文将不包含任何页面范围。

如果指定了 prevsnapshot 参数,则响应将仅包含目标快照或 Blob 与上一快照之间的差异的页面。 返回的页面包括已更新或清除的两个页面。 此响应正文的格式如下所示:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
</PageList>  
  

如果已清除 Blob 的整个页集且 prevsnapshot 未指定参数,则响应正文将不会包含任何页面范围。

maxresults如果指定了参数,则响应将仅包含具有标记中NextMarker延续标记的指定范围数。 如果没有更多挂起的范围,则延续标记将为空,否则它将包含需要作为 marker 参数在下一个请求中作为参数发送的不透明值。 此响应正文的格式如下所示:

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>
   <NextMarker/>
</PageList>  
  

授权

帐户所有者或使用有权读取 Blob 的共享访问签名的任何人执行此操作。 如果容器的 ACL 设置为允许匿名访问,则任何客户端都可以调用此操作。

备注

每个页面范围的起始和结束字节偏移将包含在内。

在具有大量写入操作的高分段页 Blob 中,Get Page Ranges请求可能会由于内部服务器超时而失败。 检索具有大量写入操作的页 Blob 范围的应用程序每次应检索一部分页面范围。 有关详细信息,请参阅 获取段中大型页 Blob 的页范围

从版本 2015-07-08 开始,可以使用参数调用Get Page Rangesprevsnapshot以返回基本 Blob 和快照之间或 blob 的两个快照之间的不同页。 使用这些页差异,可以保存页 Blob 的增量快照。 如果要实现自己的备份解决方案,增量快照是备份虚拟机磁盘的一种经济高效方法。

使用prevsnapshot参数调用Get Page Ranges将返回自创建快照prevsnapshot后已更新或清除的页面。 然后,可以使用 Put Page 将返回的页面复制到另一个存储帐户中的备份页 Blob。

从版本 2019-07-07 开始, x-ms-previous-snapshot-url 标头可用于在托管磁盘帐户中为增量快照指定快照。 如果不使用托管磁盘,prevsnapshot则应使用查询参数。

调用 Blob 以返回增量快照时,对 blob 的某些操作将导致 Get Page Ranges 失败。 Get Pages Ranges如果在创建由创建快照prevsnapshot后作为放置 Blob复制 Blob 请求目标的 Blob 上调用,则错误代码为 409 (冲突) 失败。 如果操作的目标 Get Page Ranges 本身是快照,则只要指定的快照 prevsnapshot 较旧,调用就会成功,并且两个快照之间的间隔内未 Put Blob 调用任何或 Copy Blob 操作。

注意

目前仅支持在 2016 年 1 月 1 日或之后创建的 Blob 创建增量快照。 尝试在较旧的 Blob 上使用此功能将导致 BlobOverwritten 错误,即 HTTP 错误代码 409 (冲突) 。

另请参阅

授权对Azure 存储的请求
状态和错误代码
为 Blob 服务操作设置超时
分段获取较大页 Blob 的页面范围