取得頁面範圍
取得頁面範圍作業會傳回分頁 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.0.1：10000，後面接著模擬記憶體帳戶名稱：
| GET 方法要求 URI | HTTP 版本 |
|---|---|
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist |
HTTP/1.1 |
如需詳細資訊，請參閱使用 Azure 儲存體模擬器進行開發和測試。
URI 參數
您可以在要求 URI 上指定下列其他參數：
| 參數 | Description |
|---|---|
marker |
選擇性版本 2020-10-02 和更新版本。 使用下一個 GetPageRanges 作業識別要傳回的範圍部分。 如果傳回的範圍不完整，作業會傳回回應本文中的標記值。 標記值接著可用於後續呼叫，以要求下一組範圍。 此標記值對於用戶端為不透明。 |
maxresults |
選擇性版本 2020-10-02 和更新版本。 指定要傳回的頁面範圍數目上限。 如果要求指定大於 10,000 的值，則伺服器最多會傳回 10,000 個專案。 如果傳回其他結果，服務會在 NextMarker 回應項目中傳回接續令牌。 將 設定 maxresults 為小於或等於零的值會導致錯誤回應碼 400 (不正確的要求) 。 |
snapshot |
選擇性。 不透明的 DateTime 值，當存在時，會指定要從中擷取資訊的 Blob 快照集。 如需使用 Blob 快照集的詳細資訊，請參閱 建立 Blob 的快照集。 |
timeout |
選擇性。 以秒表示。 如需詳細資訊，請參閱 設定 Blob 記憶體作業的逾時。 |
prevsnapshot |
選擇性版本 2015-07-08 和更新版本。 DateTime 值，指定回應只會包含目標 Blob 與上一個快照集之間變更的頁面。 已變更的頁面包括已更新和已清除的頁面。 只要 所 prevsnapshot 指定的快照集是兩者較舊的快照集，目標 Blob 就可以是快照集。注意：目前僅針對在 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 的租用目前為作用中。 - 要求中指定的租用標識碼符合 Blob 的租用標識碼。 如果指定此標頭且不符合任一條件，要求會失敗，且作業失敗，狀態代碼為 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 kibibyte (KiB) 字元限制，這會在啟用 Azure 儲存體分析 記錄時記錄在分析記錄中。 強烈建議您在將用戶端活動與伺服器收到的要求相互關聯時，請使用此標頭。 如需詳細資訊，請參閱關於 儲存體分析 記錄和 Azure 記錄：使用記錄來追蹤 Azure 記憶體要求。 |
唯有在符合指定條件的情況下，此作業也可支援使用條件式標頭以取得分頁範圍。 如需詳細資訊，請參閱 指定 Blob 記憶體作業的條件式標頭。
要求本文
無。
回應
回應包括 HTTP 狀態碼、一組回應標頭和回應主體。
狀態碼
成功的作業會傳回狀態碼 200 (OK)。
如需狀態代碼的詳細資訊，請參閱 狀態和錯誤碼。
回應標頭
這項作業的回應包括下列標頭。 回應也可能包括其他標準 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 ，且值不包含超過 1,024 個可見的 ASCII 字元。 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 作業，如下所示。
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指定的快照集。 接著，您可以使用 Put Page，將傳回的頁面複製到另一個記憶體帳戶中的備份分頁 Blob。
從 2019-07-07 版開始，您可以使用 x-ms-previous-snapshot-url 標頭，在受控磁碟帳戶中指定增量快照集的快照集。 如果您不是使用受控磁碟，請使用 prevsnapshot 查詢參數。
呼叫 Blob 以傳回累加快照集時，Blob 上的某些作業會導致 Get Page Ranges 失敗。 Get Pages Ranges如果呼叫的 Blob 是以 Put Blob 為目標的 Blob 或擷取快照prevsnapshot集之後的 Blob 上呼叫，則發生錯誤碼 409 (衝突) 失敗。 如果作業的目標 Get Page Ranges 本身是快照集，只要指定的 prevsnapshot 快照集較舊，呼叫就會成功，而且兩個快照集之間的間隔中不會 Put Blob 呼叫 或 Copy Blob 作業。
注意
目前僅針對在 2016 年 1 月 1 日或之後建立的 Blob 支援增量快照集。 嘗試在較舊的 Blob 上使用這項功能會導致 BlobOverwritten 錯誤，也就是 HTTP 錯誤碼 409 (衝突) 。