取得頁面範圍

發行項
07/10/2024

取得頁面範圍作業會傳回分頁 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

當您對模擬記憶體服務提出要求時，請將模擬器主機名和 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 快照集的詳細資訊，請參閱 Create 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`	可用來針對要求和對應的回應進行疑難解答。如果此標頭存在於要求中，且值包含不超過 1,024 個可見的 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>

授權

在 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 數據。

SAS) 共用存取簽章 (提供記憶體帳戶中資源的安全委派存取權。透過 SAS，您可以細微地控制用戶端如何存取數據。您可以指定用戶端可以存取的資源、這些資源的許可權，以及 SAS 的有效時間長度。

此 Get Page Ranges 作業支援三種類型的共用存取簽章：使用者委派 SAS、服務 SAS 和帳戶 SAS。

基於安全性最佳作法，建議您使用 Microsoft Entra 認證，而不是記憶體帳戶密鑰，這更容易遭到入侵。如果您的應用程式設計需要共用存取簽章，請盡可能使用 Microsoft Entra 認證來建立使用者委派 SAS。

不允許記憶體帳戶存取共用密鑰時，對 Blob 記憶體的要求不允許服務 SAS 令牌或帳戶 SAS 令牌。若要深入瞭解，請參閱瞭解不允許共用密鑰如何影響 SAS 令牌。

使用者委派 SAS

使用者委派 SAS 會受到 Microsoft Entra 認證保護，以及 SAS 所指定的許可權。

Get Page Ranges使用委派給容器或 Blob 資源的 SAS 令牌呼叫作業，需要讀取 (r) 許可權作為使用者委派 SAS 令牌的一部分。

若要深入瞭解使用者委派 SAS，請參閱 Create 使用者委派 SAS。

服務 SAS

服務 SAS 會使用儲存體帳戶金鑰加以保護。服務 SAS 會將存取權委派給單一 Azure 記憶體服務中的資源，例如 Blob 記憶體。

Get Page Ranges使用委派給容器或 Blob 資源的 SAS 令牌呼叫作業，需要讀取 (r) 許可權作為服務 SAS 令牌的一部分。

若要深入瞭解服務 SAS，請參閱 Create 服務 SAS。

帳戶 SAS

帳戶 SAS 會使用儲存體帳戶金鑰加以保護。帳戶 SAS 則將存取權限委派給一或多個儲存體服務的資源。所有作業皆可透過服務 SAS 或使用者委派 SAS 取得，也可透過帳戶 SAS 取得。

下表指出委派存取權時所要指定的已簽署資源類型和已簽署許可權：

作業	已簽署的服務	已簽署的資源類型	已簽署的許可權
取得頁面範圍	Blob (b)	物件 (o)	讀取 r ()

若要深入了解帳戶 SAS，請參閱 Create 帳戶 SAS。

備註

每個分頁範圍的開始和結束位元組位移都包含在內。

在具有大量寫入的高度片段化分頁 Blob 中，Get Page Ranges 要求會因為內部伺服器逾時而失敗。當應用程式擷取具有大量寫入作業的分頁 Blob 範圍時，應一次擷取一個分頁範圍子集。

從 2015-07-08 版開始，您可以使用參數呼叫 Get Page Rangesprevsnapshot ，以傳回基底 Blob 與快照集之間差異的頁面，或在 Blob 的兩個快照集之間。藉由使用這些頁面差異，您可以儲存分頁 Blob 的增量快照集。如果您想要實作自己的備份解決方案，增量快照集是備份虛擬機磁碟符合成本效益的方式。

使用參數呼叫 Get Page Ranges 會 prevsnapshot 傳回已更新或清除的頁面，因為已擷取所 prevsnapshot 指定的快照集。接著，您可以使用 Put Page，將傳回至另一個記憶體帳戶中備份分頁 Blob 的頁面複製。

從 2019-07-07 版開始，您可以使用 x-ms-previous-snapshot-url 標頭在受控磁碟帳戶中指定增量快照集的快照集。如果您不是使用受控磁碟，請使用 prevsnapshot 查詢參數。

呼叫 Blob 以傳回增量快照集時，Blob 上的某些作業會導致 Get Page Ranges 失敗。 Get Pages Ranges失敗，錯誤碼為 409 (衝突) 如果在擷取所指定prevsnapshot快照集之後，於放置 Blob 或複製 Blob 要求的目標 Blob 上呼叫衝突。如果作業的目標 Get Page Ranges 本身是快照集，只要所 prevsnapshot 指定的快照集較舊，而且兩個快照集之間的間隔內沒有 Put Blob 呼叫或 Copy Blob 作業，呼叫就會成功。

注意

目前僅針對在 2016 年 1 月 1 日或之後建立的 Blob 支援增量快照集。嘗試在較舊的 Blob 上使用此功能會導致 BlobOverwritten 錯誤，也就是 HTTP 錯誤碼 409 (衝突) 。

另請參閱

授權對 Azure 記憶體的要求
 狀態和錯誤碼
 設定 Blob 記憶體作業的逾時

共用方式為