销售电话: 1-800-867-1380

列出 Blob

更新时间: 2015年2月

List Blobs 操作对指定容器下的 Blob 列表进行枚举。

可以按如下方式构建List Blobs请求。建议使用 HTTPS。将 myaccount 替换为你的存储帐户名称:

 

方法 请求 URI HTTP 版本

GET

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list

HTTP/1.1

在针对模拟的存储服务发出请求时,请将模拟器主机名和 BLOB 服务端口指定为 127.0.0.1:10000,后跟模拟的存储帐户名称:

 

方法 请求 URI HTTP 版本

GET

http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list

HTTP/1.1

有关详细信息,请参阅使用 Azure 存储模拟器进行开发和测试

可在 URI 中指定以下其他参数。

 

Parameter 说明

prefix

可选。筛选结果以便仅返回名称以指定前缀开头的 Blob。

delimiter

可选。当请求包含此参数时,操作将在响应正文中返回一个 BlobPrefix 元素,该元素充当分隔符字符出现之前名称以同一子字符串开头的所有 Blob 的占位符。分隔符可以是单个字符或字符串。

marker

可选。一个字符串值,该值指定要使用下一个列表操作返回的列表部分。如果返回的列表不完整,此操作将在响应正文中返回标记值。然后,可以在后续调用中使用该标记值请求下一组列表项。

标记值对客户端不透明。

maxresults

可选。指定要返回的 Blob(包括所有 BlobPrefix 元素)的最大数量。如果请求未指定 maxresults,或者指定大于 5,000 的值,服务器最多返回 5,000 个项。

maxresults 设置为小于等于零的值会导致出现错误响应代码 400(错误请求)。

include={snapshots,metadata,uncommittedblobs,copy}

可选。指定要包含在响应中的一个或多个数据集:

  • snapshots:指定应包含在枚举中的快照。在响应中,将按最旧到最新的顺序列出快照。

  • metadata:指定要在响应中返回的 Blob 元数据。

  • uncommittedblobs:指定要在响应包含其块已上载,但尚未使用 放置块列表 (REST API) 提交的 Blob。

  • copy:2012-02-12 和更高版本。指定应在响应中包含与任何当前或以前 Copy Blob 操作相关的元数据。

要在 URI 中指定其中多个选项,必须用 URL 编码的逗号 ("%82") 分隔各选项。

timeout

可选。timeout 参数以秒表示。有关详细信息,请参阅为 BLOB 服务操作设置超时

下表介绍必需的和可选的请求标头。

 

请求标头 说明

Authorization

必需。指定身份验证方案、帐户名和签名。有关详细信息,请参阅Azure 存储服务身份验证

Datex-ms-date

必需。为请求指定协调世界时 (UTC)。有关详细信息,请参阅Azure 存储服务身份验证

x-ms-version

对于所有验证的请求是必需的,对于匿名请求是可选的。指定用于此请求的操作的版本。有关详细信息,请参阅Windows Azure 中 BLOB 服务、队列服务和表服务的版本管理

x-ms-client-request-id

可选。提供客户端生成的、附带 1 KB 字符限制的模糊值,在启用存储分析日志记录时,将在分析日志中记录该值。强烈建议使用此标头将客户端活动与服务器接收的请求相关联。有关详细信息,请参阅关于存储分析日志记录Azure 日志记录:使用日志跟踪存储请求

无。

有关示例请求,请参见枚举 Blob 资源

响应包括 HTTP 状态代码、一组响应标头以及采用 XML 格式的响应正文。

此操作成功后返回状态代码 200(正常)。

有关状态代码的信息,请参阅状态和错误代码

此操作的响应包括以下标头。该响应还可能包括其他标准 HTTP 标头。所有标准标头都符合 HTTP/1.1 协议规范

 

响应标头 说明

Content-Type

指定返回的结果所采用的格式。目前,该值为 application/xml

x-ms-request-id

此标头唯一地标识发出的请求,并且可用于解决请求问题。有关详细信息,请参阅API 操作故障排除

x-ms-version

指示用于执行请求的 BLOB 服务的版本。为使用 2009-09-19 版及更新版本发出的请求返回此标头。

如果使用 BLOB 服务的 2009-09-19 版将容器标记为公共���问,则也会为未指定版本的匿名请求返回此标头。

Date

服务生成的 UTC 日期/时间值指示启动响应的时间。

XML 响应的格式如下所示。

请注意,仅当在请求 URI 中指定了 PrefixMarkerMaxResultsDelimiter 元素时,这些元素才存在。只有在列表结果不完整时,NextMarker 元素才具有值。

仅当使用 include 参数在请求 URI 中指定了快照、Blob 元数据和未提交的 Blob 时,它们才会包含在响应中。

在 2009-09-19 版及更新版本中,Blob 的属性将封装在 Properties 元素中。

在 2013-08-15 版及更新版本中,EnumerationResults 元素包含用于指定 Blob 终结点的 ServiceEndpoint 属性和用于指定容器名称的 ContainerName 字段。在之前的版本中,这两个属性在 ContainerName 字段中组合在一起使用。此外,在 2013-08-15 版及更新版本中,删除了 Url 下的 Blob 元素。

<?xml version="1.0" encoding="utf-8"?>
<EnumerationResults ServiceEndpoint="http://myaccount.blob.core.windows.net/"  ContainerName="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>
      <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>
        <LeaseState>available | leased | expired | breaking | broken</LeaseState>
        <LeaseDuration>infinite | fixed</LeaseDuration>
        <CopyId>id</CopyId>
        <CopyStatus>pending | success | aborted | failed </CopyStatus>
        <CopySource>source url</CopySource>
        <CopyProgress>bytes copied/bytes total</CopyProgress>
        <CopyCompletionTime>datetime</CopyCompletionTime>
        <CopyStatusDescription>error string</CopyStatusDescription>
      </Properties>
      <Metadata>   
        <Name>value</Name>
      </Metadata>
    </Blob>
    <BlobPrefix>
      <Name>blob-prefix</Name>
    </BlobPrefix>
  </Blobs>
  <NextMarker />
</EnumerationResults>

LeaseStateLeaseDuration 仅出现在 2012-02-12 版及更高版本中。

CopyIdCopyStatusCopySourceCopyProgressCopyCompletionTimeCopyStatusDescription 仅出现在 2012-02-12 版及更高版本中,这时此操作包括 include={copy} 参数。如果此 Blob 从未成为 Copy Blob 操作中的目标,或者在结束的 Copy Blob 操作后使用 Set Blob PropertiesPut BlobPut Block List 修改过,则这些元素不会出现。在 2012-02-12 版之前,这些元素不会与由 复制 Blob 创建的 Blob 一起出现。

note备注
从 2009-09-19 版开始,List Blobs 在响应正文中返回以下重命名的元素:

  • Last-Modified(以前为 LastModified

  • Content-Length(以前为 Size

  • Content-Type(以前为 ContentType

  • Content-Encoding(以前为 ContentEncoding

  • Content-Language(以前为 ContentLanguage

Content-MD5 元素与使用 2009-09-19 版及更新版本创建的 Blob 一起出现。在 2012-02-12 版及更新版本中,BLOB 服务在使用 放置 Blob (REST API) 上载 Blob 时计算 Content-MD5 值,但在使用 放置块列表 (REST API) 创建 Blob 时不计算此值。创建 Blob 时可以显式设置 Content-MD5 值,也可通过调用 放置块列表 (REST API)设置 Blob 属性 (REST API) 操作来设置。

有关示例响应,请参见枚举 Blob 资源

如果容器的访问控制列表 (ACL) 设置为允许匿名访问容器,则任何客户端都可以调用此操作。在其他情况下,此操作可由帐户所有者以及使用共享访问签名且有权列出容器中的 Blob 的任何人调用。

响应中的 Blob 属性

如果已请求要在枚举中包含未提交的 Blob,请注意直到提交 Blob 后才会设置某些属性,因此某些属性可能不会在响应中返回。

x-ms-blob-sequence-number 元素将仅为页 Blob 返回。

对于页 Blob,Content-Length 元素中返回的值与 Blob 的 x-ms-blob-content-length 标头的值相对应。

仅当已使用 2009-09-19 版或更高版本为 Blob 设置 Content-MD5 元素时,该元素才会出现在响应正文中。可在创建 Blob 时设置 Content-MD5 属性,也可通过调用 设置 Blob 属性 (REST API) 来设置。在 2012-02-12 和更高版本中,即使 Put Blob 请求不包含 MD5 标头,Put Blob 也会设置块 Blob 的 MD5 值。

响应中的元数据

只有在 URI 上指定了 Metadata 参数时,才会显示 include=metadata 元素。在 Metadata 元素中,将在与每个名称-值对的名称对应的元素中列出该对的值。

请注意,必须按照 BLOB 服务 2009-09-19 版规定的命名限制来存储使用此参数请求的元数据。从该版本开始,所有元数据名称必须遵循 C# 标识符的命名约定。

如果元数据名称-值对违反 2009-09-19 版强制规定的命名限制,响应正文将在 x-ms-invalid-name 元素中指定有问题的名称,如以下 XML 代码段中所示:


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

响应中的快照

仅当在 URI 中指定了 include=snapshots 参数时,才会在响应���列出快照。列在响应中的快照不包含 LeaseStatus 元素,因为快照不能具有活动租约。

如果调用带分隔符的 List Blobs,也不能在枚举中包含快照。包含这两者的请求将返回 InvalidQueryParameter 错误(HTTP 状态代码 400 – 错误请求)。

响应中的未提交 Blob

仅当在 URI 中指定了 include=uncommittedblobs 参数时,才会在响应中列出未提交的 Blob。列在响应中的未提交 Blob 不包含以下任何元素:

  • Last-Modified

  • Etag

  • Content-Type

  • Content-Encoding

  • Content-Language

  • Content-MD5

  • Cache-Control

  • Metadata

使用标记值返回结果集

如果为 maxresults 参数指定一个值,而要返回的 Blob 数量超过此值,或者超过 maxresults 的默认值,则响应正文将包含一个 NextMarker 元素,该元素指示要在后续请求中返回的下一个 Blob。要返回下一组项,请在后续请求的 URI 上将 NextMarker 值指定为标记参数。

请注意,NextMarker 值应视为不透明。

使用分隔符遍历 Blob 命名空间

通过 delimiter 参数,调用方可以使用用户配置的分隔符遍历 Blob 命名空间。这样,你就可以遍历 Blob 的虚拟层次结构,就好像它是文件系统一样。分隔符可以是单个字符或字符串。如果请求包含该参数,此操作将返回 BlobPrefix 元素。将返回 BlobPrefix 元素以替代在出现分隔符字符之前以同一子字符串开头的所有 Blob。BlobPrefix 元素的值是 substring+delimiter,其中 substring 是作为一个或多个 Blob 名称的前缀的公用子字符串,而 delimiterdelimiter 参数的值。

可以通过为请求 URI 上的 BlobPrefix 参数指定 BlobPrefix 值,使用 prefix 值进行后续调用以列出以该前缀开头的 Blob。

请注意,每个返回的 BlobPrefix 元素都会根据最大结果进行计数,就像每个 Blob 元素一样。

Blob 在响应正文中按字母顺序列出,大写字母将先列出。

CopyStatusDescription 中出现复制错误

CopyStatusDescription 包含有关 Copy Blob 错误的详细信息。

  • 当复制尝试失败而 BLOB 服务仍在检索操作时,CopyStatus 将设置为 pending,并且 CopyStatusDescription 文本将描述上次复制尝试期间可能发生的故障。

  • CopyStatus 设置为 failed 时,CopyStatusDescription 文本将描述导致复制操作失败的错误。

下表说明了每个 CopyStatusDescription 值的三个字段。

 

组件 说明

HTTP 状态代码

指定错误的标准 3 位整数。

错误代码

Azure 在 <ErrorCode> 元素中提供的错误描述关键字。如果未显示 <ErrorCode> 元素,则使用包含与 HTTP 规范中的 3 位 HTTP 状态代码关联的标准错误文本的关键字。请参见通用 REST API 错误代码

信息

用引号引起来的详细错误说明。

下表说明了常见错误情形的 CopyStatusCopyStatusDescription 值。

Important重要提示
此处显示的说明文本可能会更改而不提供警告,即使版本没有发生变化也是如此,因此,不要依赖于精确匹配该文本。

 

方案 CopyStatus 值 CopyStatusDescription 值

已成功完成复制操作。

成功

empty

在完成之前,用户终止了复制操作。

已中止

empty

在复制操作期间从源 Blob 中读取时出现错误,但会重试该操作。

挂起

502 BadGateway“读取源时遇到可重试的错误。将重试。出错时间:<时间>”

在写入到复制操作的目标 Blob 时出现错误,但会重试该操作。

挂起

500 InternalServerError“遇到可重试的错误。将重试。出错时间:<时间>”

从复制操作的源 Blob 中读取时出现无法恢复的错误。

失败

404 ResourceNotFound“在读取源时复制失败”。

note备注
在报告此基本错误时,Azure 将在 ResourceNotFoundErrorCode< 元素中返回 >。如果响应中未显示 <ErrorCode> 元素,则会显示 HTTP 状态的标准字符串表示形式,如 NotFound

限制所有复制操作的超时时间已过。(当前超时时间为 2 周。)

失败

500 OperationCancelled“复制超过允许的最长时间”。

从源中读取时,复制操作失败过于频繁,而不符合最低的尝试成功比率要求。(此超时可防止在失败之前重试较差的源超过 2 周。)

失败

500 OperationCancelled“在读取源时复制失败”。

本文是否对您有所帮助?
(1500 个剩余字符)
感谢您的反馈
显示:
© 2015 Microsoft