你当前正在访问 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=pagelisthttps://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
对模拟存储服务发出请求时，将模拟器主机名和Azure Blob 存储端口指定为 127.0.0.1：10000，后跟模拟存储帐户名称：
| GET 方法请求 URI | HTTP 版本 |
|---|---|
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist |
HTTP/1.1 |
有关详细信息，请参阅使用 Azure 存储模拟器进行开发和测试。
URI 参数
可以在请求 URI 上指定以下附加参数：
| 参数 | 说明 |
|---|---|
marker |
可选版本 2020-10-02 及更高版本。 标识要与下一个 GetPageRanges 操作一起返回的区域部分。 如果返回的范围不完整，则操作在响应正文中返回标记值。 然后，可以在后续调用中使用标记值来请求下一组范围。 标记值对客户端不透明。 |
maxresults |
可选版本 2020-10-02 及更高版本。 指定要返回的最大页数。 如果请求指定的值大于 10,000，则服务器最多返回 10,000 项。 如果有其他结果要返回，则服务将在 NextMarker 响应元素中返回一个延续标记。 设置为 maxresults 小于或等于零的值会导致错误响应代码 400 (错误的请求) 。 |
snapshot |
可选。 一个不透明的 DateTime 值，如果存在，则指定从中检索信息的 blob 快照。 有关使用 Blob 快照的详细信息，请参阅Create blob 的快照。 |
timeout |
可选。 以秒为单位表示。 有关详细信息，请参阅 为 Blob 存储操作设置超时。 |
prevsnapshot |
可选版本 2015-07-08 及更高版本。 一个 DateTime 值，该值指定响应将仅包含目标 blob 与上一个快照之间已更改的页面。 已更改的页面包括更新的页面和清除的页面。 目标 blob 可以是快照，只要 指定的prevsnapshot快照是两者中较早的。注意：目前仅支持在 2016 年 1 月 1 日或之后创建的 Blob 使用增量快照。 |
请求标头
下表介绍必需的和可选的请求标头。
| 请求标头 | 说明 |
|---|---|
Authorization |
必需。 指定授权方案、帐户名称和签名。 有关详细信息，请参阅授权对 Azure 存储的请求。 |
Date 或 x-ms-date |
必需。 指定请求的协调世界时 (UTC)。 有关详细信息，请参阅授权对 Azure 存储的请求。 |
x-ms-version |
对于所有已授权的请求是必需的，对于匿名请求是可选的。 指定用于此请求的操作的版本。 有关详细信息，请参阅 Azure 存储服务的版本控制。 |
Range |
可选。 指定要列出范围的字节范围（含该字节）。 如果 Range 省略 ，则返回 Blob 的所有范围。 |
x-ms-range |
可选。 指定要列出范围的字节范围（含该字节）。 如果指定了 Range 和 x-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 (KiB) 字符限制，启用 Azure 存储分析 日志记录时，会记录在分析日志中。 强烈建议在将客户端活动与服务器接收的请求相关联时使用此标头。 有关详细信息，请参阅关于存储分析日志记录和 Azure 日志记录：使用日志跟踪 Azure 存储请求。 |
此操作还支持仅在满足指定条件时才使用条件标头来获取页范围。 有关详细信息，请参阅 为 Blob 存储操作指定条件标头。
请求正文
无。
响应
响应包含 HTTP 状态代码、一组响应标头以及响应正文。
状态代码
此操作成功后返回状态代码 200（正常）。
有关状态代码的详细信息，请参阅 状态和错误代码。
响应头
此操作的响应包括以下标头。 该响应还可能包括其他标准 HTTP 标头。 所有标准标头都符合 HTTP/1.1 协议规范。
| 语法 | 说明 |
|---|---|
Last-Modified |
上次修改 Blob 的日期/时间。 日期格式遵循 RFC 1123。 修改 Blob 的任何操作将会更改 Blob 的上次修改时间，包括更新 Blob 的元数据或属性。 |
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 |
可用于对请求和相应的响应进行故障排除。 如果请求中存在标头， x-ms-client-request-id 并且该值包含的可见 ASCII 字符不超过 1,024 个，则此标头的值等于标头的值。
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>
授权
在 Azure 存储中调用任何数据访问操作时，都需要授权。 可以授权操作， Get Page Ranges 如下所述。
重要
Microsoft 建议将 Microsoft Entra ID 与托管标识结合使用来授权对 Azure 存储的请求。 与共享密钥授权相比，Microsoft Entra ID提供更高的安全性和易用性。
Azure 存储支持使用 Microsoft Entra ID 来授权对 Blob 数据的请求。 使用 Microsoft Entra ID，可以使用 Azure 基于角色的访问控制 (Azure RBAC) 向安全主体授予权限。 安全主体可以是用户、组、应用程序服务主体或 Azure 托管标识。 安全主体由 Microsoft Entra ID 进行身份验证，以返回 OAuth 2.0 令牌。 然后可以使用令牌来授权对 Blob 服务发出请求。
若要详细了解如何使用 Microsoft Entra ID 授权，请参阅使用 Microsoft Entra ID 授权访问 blob。
权限
下面列出了Microsoft Entra用户、组、托管标识或服务主体调用操作Get Page Ranges所需的 RBAC 操作，以及包含此操作的最低特权内置 Azure RBAC 角色：
- Azure RBAC 操作：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
- 最低特权内置角色：存储 Blob 数据读取者
若要详细了解如何使用 Azure RBAC 分配角色，请参阅 分配 Azure 角色以访问 Blob 数据。
注解
每个页面范围的起始和结束字节偏移将包含在内。
在具有大量写入操作的高分段页 Blob 中，Get Page Ranges请求可能会由于内部服务器超时而失败。 检索具有大量写入操作的页 Blob 范围的应用程序每次应检索一部分页面范围。
从版本 2015-07-08 开始，可以使用 参数调用 Get Page Rangesprevsnapshot 以返回在基本 Blob 和快照之间或 Blob 的两个快照之间不同的页面。 通过使用这些页差异，可以保存页 blob 的增量快照。 如果要实现自己的备份解决方案，增量快照是备份虚拟机磁盘的一种经济高效方法。
使用 prevsnapshot 参数调用 Get Page Ranges 将返回自使用 指定的prevsnapshot快照以来已更新或清除的页面。 然后，可以使用放置页将返回的页面复制到另一个存储帐户中的备份 页 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 BlobCopy Blob 操作，调用将成功。
注意
目前仅支持在 2016 年 1 月 1 日或之后创建的 Blob 使用增量快照。 尝试在较旧的 blob 上使用此功能将导致 BlobOverwritten 错误，即 HTTP 错误代码 409 (冲突) 。