取得區塊清單

發行項
02/07/2024

Get Block List 作業可擷取已上傳做為區塊 Blob 一部分的區塊清單。

Blob 會維護兩個封鎖清單：

已認可的封鎖清單：已使用 Put Block List 成功認可至指定 Blob 的區塊清單。
未認可的封鎖清單：已使用 Put Block 為 Blob 上傳但尚未認可的區塊清單。這些區塊會儲存在 Azure 中，與 Blob 相關聯，但尚未構成 Blob 的一部分。

您可以呼叫 Get Block List 以傳回已認可的封鎖清單、未認可的封鎖清單或兩個清單。您也可以呼叫此作業來擷取快照集的認可封鎖清單。

要求

Get Block List 要求的建構如下。建議您使用 HTTPS。以記憶體帳戶名稱取代 myaccount ：

GET 方法要求 URI	HTTP 版本
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&versionid=<DateTime>`	HTTP/1.1

模擬記憶體服務要求

對模擬儲存體服務提出要求時，請將模擬器主機名稱和 Blob 服務通訊埠指定為 127.0.0.1:10000，後面接著模擬儲存體帳戶名稱：

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

如需詳細資訊，請參閱使用 Azure 模擬器進行本機 Azure 儲存體開發。

URI 參數

您可以在要求 URI 上指定下列其他參數：

URI 參數	描述
`snapshot`	選擇性。快照集參數是不透明的 `DateTime` 值，當其存在時，會指定要擷取的 Blob 清單。如需使用 Blob 快照集的詳細資訊，請參閱建立 Blob 的快照集。
`versionid`	2019-12-12 版和更新版本的選擇性。參數 `versionid` 是不透明 `DateTime` 值，當存在時，會指定要擷取的 Blob 版本。
`blocklisttype`	指定傳回認可的區塊清單、未認可的區塊清單，或兩種清單一起傳回。有效值為 `committed`、`uncommitted` 或 `all`。如果您省略此參數，`Get Block List` 會傳回認可的區塊清單。
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定 Blob 記憶體作業的逾時。

要求標頭

下表描述必要的和選用的要求標頭。

要求標頭	描述
`Authorization`	必要。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的「國際標準時間」(UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	所有授權要求都需要，匿名要求則為選擇性。指定用於這個要求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`x-ms-lease-id:<ID>`	選擇性。如果指定此標頭，只有同時符合下列兩個條件時，才會執行作業： - Blob 的租用目前為作用中。 - 要求中指定的租用標識碼符合 Blob 的租用標識碼。如果指定此標頭且不符合任一條件，要求就會失敗，且作業失敗，狀態代碼為 412 (前置條件失敗) 。
`x-ms-client-request-id`	選擇性。提供客戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。如需詳細資訊，請參閱監視 Azure Blob 儲存體。

唯有在符合指定條件的情況下，此作業也可支援使用條件式標頭以執行作業。如需詳細資訊，請參閱指定 Blob 記憶體作業的條件式標頭。

要求本文

無。

範例要求

下列範例要求 URI 會針對名為 MOV1.avi 的 Blob 傳回認可的封鎖清單：

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=committed HTTP/1.1

下列範例要求 URI 會同時傳回已認可和未認可的封鎖清單：

GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=all HTTP/1.1

下列範例要求 URI 會傳回快照集的認可封鎖清單。快照集只包含已認可的區塊，因此沒有與它相關聯的未認可區塊。

GET http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&snapshot=2009-09-30T20%3a11%3a15.2735974Z

回應

回應包含 HTTP 狀態代碼、一組響應標頭，以及包含區塊清單的回應本文。

狀態碼

成功的作業會傳回狀態碼 200 (OK)。

如需狀態代碼的相關信息，請參閱狀態和錯誤碼。

回應標頭

這項作業的回應包括下列標頭。回應也可能包含其他標準 HTTP 標頭。所有標準標頭都符合 HTTP/1.1 通訊協議規格。

回應標頭	描述
`Last-Modified`	上次修改 Blob 的日期/時間。日期格式會依照 RFC 1123。如需詳細資訊，請參閱代表標頭中的日期/時間值。只有在 Blob 已認可區塊時，才會傳回。修改 Blob 的任何作業 (包括 Blob 的中繼資料或屬性更新) 都會變更 Blob 上次修改的時間。
`ETag`	Blob 的 ETag。只有在 Blob 已認可區塊時，才會傳回。
`Content-Type`	Blob 的 MIME 內容類型。預設值是 `application/xml`。
`x-ms-blob-content-length`	Blob 大小 (以位元組為單位)。
`x-ms-request-id`	此標頭可唯一識別所做的要求，而且可用來對要求進行疑難解答。如需詳細資訊，請參閱針對 API 作業進行疑難解答。
`x-ms-version`	指出用來執行要求的服務版本。對 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`如果標頭不存在於要求中，則它不會出現在回應中。

只有在符合指定的條件時，此作業也支援使用條件標頭來取得封鎖清單。如需詳細資訊，請參閱指定 Blob 記憶體作業的條件式標頭。

回應本文

僅傳回認可的區塊之要求回應主體的格式如下：

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  <CommittedBlocks>
</BlockList>

同時傳回認可及未認可的區塊之要求回應主體的格式如下：


<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
     <Block>
        <Name>base64-encoded-block-id</Name>
        <Size>size-in-bytes</Size>
     </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>base64-encoded-block-id</Name>
      <Size>size-in-bytes</Size>
    </Block>
  </UncommittedBlocks>
 </BlockList>

範例回應

在下列範例中，blocklisttype 參數已設為 committed，因此只會在回應中傳回 Blob 之認可的區塊。

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:33:19 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
</BlockList>

在下列範例中，blocklisttype 參數已設為 all，因此會在回應中同時傳回 Blob 之認可及未認可的區塊。

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Sun, 25 Sep 2011 00:35:56 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>4194304</Size>
    </Block>
  </CommittedBlocks>
  <UncommittedBlocks>
    <Block>
      <Name>BlockId003</Name>
      <Size>4194304</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024000</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

在下一個範例中 blocklisttype ，參數已設定為 all，但 Blob 尚未認可，因此元素是空的 CommittedBlocks 。

HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Wed, 14 Sep 2011 00:40:22 GMT

<?xml version="1.0" encoding="utf-8"?>
<BlockList>
  <CommittedBlocks />
  <UncommittedBlocks>
    <Block>
      <Name>BlockId001</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId002</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId003</Name>
      <Size>1024</Size>
    </Block>
    <Block>
      <Name>BlockId004</Name>
      <Size>1024</Size>
    </Block>
  </UncommittedBlocks>
</BlockList>

授權

在 Azure 記憶體中呼叫任何數據存取作業時，需要授權。您可以授權 Get Block List 作業，如下所述。

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 Block List作業所需的 RBAC 動作，以及包含此動作的最低特殊許可權內建 Azure RBAC 角色：

Azure RBAC 宏指令：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
最低特殊許可權的內建角色：記憶體 Blob 數據讀取器

若要深入瞭解如何使用 Azure RBAC 指派角色，請參閱指派 Azure 角色以存取 Blob 數據。

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

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

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

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

使用者委派 SAS

使用者委派 SAS 受到 Microsoft Entra 認證保護，也受到指定給 SAS 的許可權保護。

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

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

服務 SAS

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

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

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

帳戶 SAS

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

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

作業	已簽署的服務	已簽署的資源類型	已簽署的許可權
取得區塊清單	Blob (b)	物件 (o)	讀取 r ()

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

備註

呼叫 Get Block List 以傳回已認可至區塊 Blob 的區塊清單、尚未認可的區塊清單，或兩個清單。使用 blocklisttype 參數可指定要傳回的區塊清單。認可區塊的清單會以與 Put Block List 作業所認可的相同順序傳回。

您可以使用未認可的封鎖清單來判斷在呼叫 Put Block 或 Put Block List 失敗時，Blob 遺漏了哪些區塊。未認可的區塊清單會依字母順序傳回。如果重複上傳相同的區塊識別碼，清單中只會顯示最近上傳的區塊。

注意

當 Blob 尚未認可時，呼叫 Get Block List with blocklisttype=all 會傳回未認可的區塊，而且元素是空的 CommittedBlocks 。

Get Block List 讀取未認可的區塊清單時，不支援並行存取。呼叫， Get Block List 其中 blocklisttype=uncommitted 或 blocklisttype=all 的要求速率低於其他讀取作業。如需讀取作業的目標輸送量詳細數據，請參閱 Azure 記憶體延展性和效能目標。

自 2019-12-12 版起，區塊 Blob 可以包含最多 4000 個 mebibytes 的區塊， (MiB) 。若要保護使用帶正負號 32 位整數來表示區塊大小的應用程式，請在包含大於 100 MiB 且 REST 版本早於 2019-12-12 的區塊 Blob 上呼叫 Get Block List ，會導致狀態代碼 409 (Conflict) 。

Get Block List 只適用於區塊 Blob。對分頁 Blob 呼叫 Get Block List 會導致狀態碼 400 (不正確的要求)。

Get Block List 封存區塊 Blob 上的將會失敗。

計費

定價要求可能源自使用 Blob 記憶體 API 的用戶端，無論是直接透過 Blob 記憶體 REST API，還是來自 Azure 記憶體用戶端連結庫。這些要求會累算每個交易的費用。交易類型會影響帳戶的收費方式。例如，讀取交易會累算到與寫入交易不同的計費類別。下表根據記憶體帳戶類型顯示要求的計費類別 Get Block List ：

作業	儲存體帳戶類型	計費類別
取得區塊清單	進階區塊 Blob 標準一般用途 v2	其他作業
取得區塊清單	標準一般用途 v1	讀取作業

若要瞭解指定計費類別的定價，請參閱 Azure Blob 儲存體定價。

另請參閱

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