[This is prerelease documentation and is subject to change in future releases.]
The Get Block List operation retrieves the list of blocks that have been uploaded as part of a blob.
Request
The Get Block List request may be constructed as follows. Replace myaccount with the name of your storage account:
| Version | Method | Request URI |
|---|
Default | GET | http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist
|
2009-04-14 | GET | http://myaccount.blob.core.windows.net/mycontainer/myblob?comp=blocklist&blocklisttype=[committed|uncommitted|all]
|
.gif) Note |
|---|
| The 2009-04-14 version of Get Block List is not currently supported by the Windows® Azure™ SDK development environment, including development storage and the Storage Client sample library. |
Development Storage URI
When making a request against development storage, specify the local hostname and Blob service port as 127.0.0.1:10000, followed by the development storage account name:
| Version | Method | Request URI |
|---|
Default | GET | http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=blocklist
|
For more information, see About Development Storage.
URI Parameters
The following additional parameters may be specified on the request URI.
| Version | URI Parameter | Description |
|---|
2009-04-14 | blocklisttype | Specifies whether to return the list of committed blocks, the list of uncommitted blocks, or both lists together. Valid values are committed, uncommitted, or all. |
Request Headers
The following table describes required and optional request headers.
| Version | Request Header | Description |
|---|
All | Authorization | Required. Specifies the authentication scheme, account name, and signature. For more information, see Authentication Schemes. |
All | Date or x-ms-date | Required. Specifies the Coordinated Universal Time (UTC) for the request. For more information, see Authentication Schemes. |
All | x-ms-version | Optional if calling the default version of Get Block List; required if calling the 2009-04-14 version. Specifies the version of the operation to use for this request. For more information, see Storage Service Versioning. |
Request Body
Sample Request
The following sample request returns the committed block list for a blob named MOV1.avi; note that the x-ms-version header is set to 2009-04-14:
GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=committed
HTTP/1.1
x-ms-date: Wed, 08 Apr 2009 00:31:26 GMT
x-ms-version: 2009-04-14
Authorization: SharedKey myaccount:TOfGagLfokWXYXlGJ+R2neNr1+lIeKbURzlRfZR5fso=
The following sample request returns both the committed and the uncommitted block list:
GET http://myaccount.blob.core.windows.net/movies/MOV1.avi?comp=blocklist&blocklisttype=all
HTTP/1.1
x-ms-date: Wed, 08 Apr 2009 00:42:36 GMT
x-ms-version: 2009-04-14
Authorization: SharedKey myaccount:JoqnL0VayI4+wxIGeCVgr85Vm3diHD+Cfe37re3PQqo=
Response
The response includes an HTTP status code, a set of response headers, and a response body containing the list of blocks.
Status Code
A successful operation returns status code 200 (OK).
For information about status codes, see Status and Error Codes.
Response Headers
The response for this operation includes the following headers. The response may also include additional standard HTTP headers. All standard headers conform to the HTTP/1.1 protocol specification.
| Version | Response header | Description |
|---|
All | Content-Type | The MIME content type of the blob. Currently this header is set to application/xml. |
All | x-ms-request-id | This header uniquely identifies the request that was made and can be used for troubleshooting the request. For more information, see Troubleshooting API Operations. |
Response Body
The format of the response body is as follows:
<?xml version="1.0" encoding="utf-8"?>
<BlockList>
<Block>
<Name>base64-encoded-block-id</Name>
<Size>size-in-bytes</Size>
</Block>
</BlockList>
Sample Response
The following sample responses demonstrate the default and 2009-04-14 versions of Get Block List.
Sample Response: Committed Block List (Default Version)
Here is an example of the response body returned by default version of the Get Block List operation. The blob was assembled from three blocks.
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Blob Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Mon, 06 Apr 2009 00:23:47 GMT
<?xml version="1.0" encoding="utf-8"?>
<BlockList>
<Block>
<Name>AAAAAA==</Name>
<Size>1048576</Size>
</Block>
<Block>
<Name>AQAAAA==</Name>
<Size>1048576</Size>
</Block>
<Block>
<Name>AgAAAA==</Name>
<Size>402848</Size>
</Block>
</BlockList>
Sample Response: Committed Block List (2009-04-14 Version)
In this example, the blocklisttype parameter was set to committed, so only the blob's committed blocks are returned in the response.
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Blob Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Wed, 08 Apr 2009 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>
Sample Response: Committed and Uncommitted Block Lists (Version 2009-04-14)
In this example, the blocklisttype parameter was set to all, and both the blob's committed and uncommitted blocks are returned in the response.
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Blob Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Wed, 08 Apr 2009 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>
Sample Response: Committed and Uncommitted Block Lists (Version 2009-04-14)
In this example, the blocklisttype parameter was set to all, but the blob has not yet been committed, so the CommittedBlocks element is empty.
HTTP/1.1 200 OK
Transfer-Encoding: chunked
Content-Type: application/xml
Server: Blob Service Version 1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: 42da571d-34f4-4d3e-b53e-59a66cb36f23
Date: Wed, 08 Apr 2009 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>
Authorization
If the container's ACL is set to allow anonymous access, any client may call the default version of Get Block List.
If the container's ACL is set to allow anonymous access, any client may call the 2009-04-14 version of Get Block List with blocklisttype=committed. Only the account owner may call the 2009-04-14 version of Get Block List where blocklisttype=uncommitted or blocklisttype=all.
Remarks
The maximum timeout for a Get Block List operation is 60 seconds.
Two versions of Get Block List are now available, described in the following sections.
Default Version
The default version of Get Block List returns only blocks that have already have been committed to the Blob service with the Put Block List operation.
The list of blocks is returned in the same order that they were committed by the Put Block List operation.
2009-04-14 Version
With the 2009-04-14 version of Get Block List, you can return the list of blocks that have been committed to the Blob service, the list of blocks that have not yet been committed, or both lists. Use the blocklisttype parameter to specify which list of blocks to return.
The list of committed blocks is returned in the same order that they were committed by the Put Block List operation.
The list of uncommitted blocks is returned beginning with the most recently uploaded block to the oldest uploaded block. If a block ID has been uploaded more than once, only the most recently uploaded block appears in the list.
Note that when a blob has not yet been committed, calling Get Block List with blocklisttype=all returns the uncommitted blocks, and the CommittedBlocks element is empty.
See Also
Copyright © 2009 by Microsoft Corporation. All rights reserved.