List Blobs

The List Blobs request may be constructed as follows. Replace myaccount with the name of your storage account:

The response includes an HTTP status code, a set of response headers, and a response body in XML format.

Response Body

---

The format of the XML response is as follows.

Note that the Prefix, Marker, MaxResults, and Delimiter elements are present only if they were specified on the request URI. The NextMarker element has a value only if the list results are not complete.

Snapshots, blob metadata, and uncommitted blobs are included in the response only if they are specified with the include parameter on the request URI.

In version 2009-09-19, the blob's properties are encapsulated within a Properties element.

Copier

<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ContainerName="http://myaccount.blob.core.windows.net/mycontainer">
  <Prefix>string-value</Prefix>
  <Marker>string-value</Marker>
  <MaxResults>int-value</MaxResults>
  <Delimiter>string-value</Delimiter>
  <Blobs>
    <Blob>
      <Name>blob-name</name>
      <Snapshot>date-time-value</Snapshot>
      <Url>blob-address</Url>
      <Properties>
        <Last-Modified>date-time-value</Last-Modified>
        <Etag>etag</Etag>
        <Content-Length>size-in-bytes</Content-Length>
        <Content-Type>blob-content-type</Content-Type>
        <Content-Encoding />
        <Content-Language />
        <Content-MD5 />
        <Cache-Control />
        <x-ms-blob-sequence-number>sequence-number</x-ms-blob-sequence-number>
        <BlobType>BlockBlob|PageBlob</BlobType>
        <LeaseStatus>locked|unlocked</LeaseStatus>
      </Properties>
      <Metadata>   
        <Name>value</Name>
      </Metadata>
    </Blob>
    <BlobPrefix>
      <Name>blob-prefix</Name>
    </BlobPrefix>
  </Blobs>
  <NextMarker />
</EnumerationResults>

Remarque

Beginning with version 2009-09-19, List Blobs returns the following renamed elements in the response body: Last-Modified (previously LastModified) Content-Length (previously Size) Content-Type (previously ContentType) Content-Encoding (previously ContentEncoding) Content-Language (previously ContentLanguage) The Content-MD5 element appears only if the blob was created with version 2009-09-19 or later.

If the container's access control list (ACL) is set to allow anonymous access to the container, any client may call this operation. Otherwise, only the account owner can list the blobs within a container.

Blob Properties in the Response

If you have requested that uncommitted blobs be included in the enumeration, note that some properties are not set until the blob is committed, so some properties may not be returned in the response.

The x-ms-blob-sequence-number element is only returned for page blobs.

For page blobs, the value returned in the Content-Length element corresponds to the value of the blob's x-ms-blob-content-length header.

The Content-MD5 element appears in the response body only if it has been set on the blob using version 2009-09-19 or later. You can set the Content-MD5 property when the blob is created or by calling Set Blob Properties.

Metadata in the Response

The Metadata element is present only if the include=metadata parameter was specified on the URI. Within the Metadata element, the value of each name-value pair is listed within an element corresponding to the pair's name.

Note that metadata requested with this parameter must be stored in accordance with the naming restrictions imposed by the 2009-09-19 version of the Blob service. Beginning with this version, all metadata names must adhere to the naming conventions for C# identifiers.

If a metadata name-value pair violates the naming restrictions enforced by the 2009-09-19 version, the response body indicates the problematic name within an x-ms-invalid-name element, as shown in the following XML fragment:

      …
      <Metadata>
        <MyMetadata1>first value</MyMetadata1>
        <MyMetadata2>second value</MyMetadata2>
        <x-ms-invalid-name>invalid-metadata-name</x-ms-invalid-name>
      </Metadata>
      …

Snapshots in the Response

Snapshots are listed in the response only if the include=snapshots parameter was specified on the URI. Snapshots listed in the response do not include the LeaseStatus element, as snapshots cannot have active leases.

If you call List Blobs with a delimiter, you cannot also include snapshots in the enumeration. A request that includes both returns an InvalidQueryParameter error (HTTP status code 400 – Bad Request).

Uncommitted Blobs in the Response

Uncommitted blobs are listed in the response only if the include=uncommittedblobs parameter was specified on the URI. Uncommitted blobs listed in the response do not include any of the following elements:

• Last-Modified
  
  
• Etag
  
  
• Content-Type
  
  
• Content-Encoding
  
  
• Content-Language
  
  
• Content-MD5
  
  
• Cache-Control
  
  
• Metadata
  
  

Returning Result Sets Using a Marker Value

If you specify a value for the maxresults parameter and the number of blobs to return exceeds this value, or exceeds the default value for maxresults, the response body will contain a NextMarker element that indicates the next blob to return on a subsequent request. To return the next set of items, specify the value of NextMarker as the marker parameter on the URI for the subsequent request.

Note that the value of NextMarker should be treated as opaque.

Using a Delimiter to Traverse the Blob Namespace

The delimiter parameter enables the caller to traverse the blob namespace by using a user-configured delimiter. In this way, you can traverse a virtual hierarchy of blobs as though it were a file system. The delimiter may be a single character or a string. When the request includes this parameter, the operation returns a BlobPrefix element. The BlobPrefix element is returned in place of all blobs whose names begin with the same substring up to the appearance of the delimiter character. The value of the BlobPrefix element is substring+delimiter, where substring is the common substring that begins one or more blob names, and delimiter is the value of the delimiter parameter.

You can use the value of BlobPrefix to make a subsequent call to list the blobs that begin with this prefix, by specifying the value of BlobPrefix for the prefix parameter on the request URI.

Note that each BlobPrefix element returned counts toward the maximum result, just as each Blob element does.

Blobs are listed in alphabetical order in the response body.

Concepts