你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

列出 Blob

项目
06/27/2024

List Blobs 操作返回指定容器下 blob 的列表。

请求

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

方法	请求 URI	HTTP 版本
`GET`	`https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list`	HTTP/1.1

模拟存储服务 URI

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

方法	请求 URI	HTTP 版本
`GET`	`http://127.0.0.1:10000/devstoreaccount1/mycontainer?restype=container&comp=list`	HTTP/1.1

有关详细信息，请参阅使用 Azurite 模拟器进行本地 Azure 存储开发。

URI 参数

可以在 URI 上指定以下附加参数。

参数	描述
`prefix`	自选。筛选结果以仅返回名称以指定前缀开头的 Blob。在具有分层命名空间的帐户中，在前缀路径中间显示文件名称时，将发生错误。例如，可以使用前缀路径 `folder1/folder2/readme/readmefile.txt`来尝试查找 `readmefile.txt` 命名的 blob。如果任何子文件夹包含名为 `readme`的文件，则会出现错误。
`delimiter`	自选。当请求包含此参数时，该操作在响应正文中返回 `BlobPrefix` 元素。此元素充当所有名称以相同子字符串开头的 blob 的占位符，最大为分隔符字符的外观。分隔符可以是单个字符或字符串。
`marker`	自选。一个字符串值，该值标识要在下一个列表操作中返回的列表部分。如果返回的列表未完成，该操作在响应正文中返回标记值。然后，可以在后续调用中使用标记值来请求下一组列表项。标记值对客户端不透明。
`maxresults`	自选。指定要返回的最大 blob 数，包括所有 `BlobPrefix` 元素。如果请求未指定 `maxresults`，或指定大于 5,000 的值，服务器将返回最多 5,000 个项目。如果返回其他结果，服务在 `NextMarker` 响应元素中返回延续标记。在某些情况下，服务可能返回的结果可能少于 `maxresults`指定的结果，并返回继续标记。将 `maxresults` 设置为小于或等于零的值会导致错误响应代码 400（错误请求）。
`include={snapshots,metadata,uncommittedblobs,copy,deleted,tags,versions,` `deletedwithversions,immutabilitypolicy,legalhold,permissions}`	自选。指定要包含在响应中的一个或多个数据集： - `snapshots`：指定应在枚举中包含快照。快照在响应中从最早到最新列出。 - `metadata`：指定在响应中返回 Blob 元数据。 - `uncommittedblobs`：指定已上传块但尚未使用放置块列表提交的 blob 包含在响应中。 - `copy`：版本 2012-02-12 及更高版本。指定响应中应包含与任何当前或以前的 `Copy Blob` 操作相关的元数据。 - `deleted`：版本 2017-07-29 及更高版本。指定应在响应中包含软删除的 Blob。 - `tags`：版本 2019-12-12 及更高版本。指定响应中应包含用户定义的 Blob 索引标记。 - `versions`：版本 2019-12-12 及更高版本。指定应在枚举中包含 Blob 的版本。 - `deletedwithversions`：版本 2020-10-02 及更高版本。指定响应中应包含任何版本的已删除 Blob（活动或已删除）。永久删除的项会显示在响应中，直到垃圾回收处理它们。使用标记 `\<HasVersionsOnly\>`，值 `true`。 - `immutabilitypolicy`：版本 2020-06-12 及更高版本。指定枚举应包括直到日期的不可变性策略，以及 Blob 的不可变性策略模式。 - `legalhold`：版本 2020-06-12 及更高版本。指定枚举应包括 Blob 的法律保留。 - `permissions`：版本 2020-06-12 及更高版本。仅支持启用了分层命名空间的帐户。如果请求包含此参数，则列出的 Blob 或目录的所有者、组、权限和访问控制列表将包含在枚举中。若要在 URI 上指定多个选项，必须用 URL 编码的逗号（“%82”）分隔每个选项。
`showonly={deleted,files,directories}`	自选。指定要在响应中返回的以下数据集之一： - `deleted`：可选。版本 2020-08-04 及更高版本。仅适用于启用了分层命名空间的帐户。当请求包含此参数时，列表仅包含软删除的 Blob。请注意，列出软删除的 Blob 不支持 POSIX ACL 授权回退。如果还指定了 `include=deleted`，则请求失败并出现错误请求（400）。 - `files`：可选。版本 2020-12-06 及更高版本。仅适用于启用了分层命名空间的帐户。当请求包含此参数时，列表仅包含文件。 - `directories`：可选。版本 2020-12-06 及更高版本。仅适用于启用了分层命名空间的帐户。当请求包含此参数时，列表仅包含目录。
`timeout`	自选。 `timeout` 参数以秒为单位表示。有关详细信息，请参阅设置 Blob 存储操作的超时。

请求标头

下表描述了必需和可选的请求标头。

请求标头	描述
`Authorization`	必填。指定授权方案、帐户名称和签名。有关详细信息，请参阅授权对 Azure 存储的请求。
`Date` 或 `x-ms-date`	必填。指定请求的协调世界时（UTC）。有关详细信息，请参阅授权对 Azure 存储的请求。
`x-ms-version`	所有授权请求和匿名请求可选。指定要用于此请求的操作的版本。有关详细信息，请参阅 azure 存储服务版本控制。
`x-ms-client-request-id`	自选。提供客户端生成的不透明值，该值具有配置日志记录时日志中记录的 1-kibibyte （KiB）字符限制。强烈建议使用此标头将客户端活动与服务器接收的请求相关联。有关详细信息，请参阅监视 Azure Blob 存储。
`x-ms-upn`	自选。仅在为帐户启用分层命名空间并且请求中提供 `include=permissions` 时有效。如果 `true`，则 <所有者>、<组>中返回的用户标识值，并将 <Acl> 字段从 Microsoft Entra 对象 ID 转换为用户主体名称。如果 `false`，这些值将作为Microsoft Entra 对象 ID 返回。默认值为 `false`。请注意，组和应用程序对象 ID 不会翻译，因为它们没有唯一的友好名称。

请求正文

没有。

示例请求

有关示例请求，请参阅枚举 blob 资源。

响应

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

状态代码

成功的操作返回状态代码 200（正常）。有关状态代码的信息，请参阅状态和错误代码。

响应标头

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

响应标头	描述
`Content-Type`	指定返回结果的格式。目前此值为 `application/xml`。
`x-ms-request-id`	此标头唯一标识已发出的请求，并可用于对请求进行故障排除。有关详细信息，请参阅 API 操作故障排除。
`x-ms-version`	指示用于运行请求的 Blob 存储版本。对于使用版本 2009-09-19 及更高版本发出的请求，将返回此标头。如果使用 2009-09-19 版本的 Blob 存储，则此标头还会为匿名请求返回，但未指定版本。
`Date`	一个 UTC 日期/时间值，指示响应的启动时间。服务将生成此值。
`x-ms-client-request-id`	可以使用此标头对请求和相应的响应进行故障排除。此标头的值等于 `x-ms-client-request-id` 标头的值（如果请求中存在）。该值最多为 1024 个可见 ASCII 字符。如果请求中不存在 `x-ms-client-request-id` 标头，则响应中不会显示此标头。

响应正文

XML 响应的格式如下所示。

请注意，仅当在请求 URI 上指定 Prefix、Marker、MaxResults和 Delimiter 元素时才存在。仅当列表结果未完成时，NextMarker 元素才具有值。

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

在版本 2009-09-19 及更高版本中，blob 的属性封装在 Properties 元素中。

从版本 2009-09-19 开始，List Blobs 在响应正文中返回以下重命名的元素：

Last-Modified（以前 LastModified）
Content-Length（以前 Size）
Content-Type（以前 ContentType）
Content-Encoding（以前 ContentEncoding）
Content-Language（以前 ContentLanguage）

对于使用版本 2009-09-19 及更高版本创建的 blob，将显示 Content-MD5 元素。在版本 2012-02-12 及更高版本中，Blob 存储通过使用放置 Blob来计算上传 blob 时的 Content-MD5 值。使用放置块列表创建 Blob 时，Blob 存储不会计算此值。创建 blob 时，或者通过调用放置块列表或设置 Blob 属性操作来显式设置 Content-MD5 值。

对于 2009-09-19 及更高版本，但在版本 2015-02-21 之前，不能对包含追加 blob 的容器调用 List Blobs。如果列表的结果包含追加 Blob，服务将返回状态代码 409（冲突）。

LeaseState 和 LeaseDuration 仅在版本 2012-02-12 及更高版本中显示。

CopyId、CopyStatus、CopySource、CopyProgress、CopyCompletionTime和 CopyStatusDescription 仅出现在版本 2012-02-12 及更高版本中，此操作包括 include={copy} 参数。如果此 blob 从未成为 Copy Blob 操作中的目标，则不会显示这些元素。如果使用 Set Blob Properties、Put Blob或 Put Block List，在结束 Copy Blob 操作后修改此 blob，则不会显示这些元素。这些元素也不会显示在版本 2012-02-12 之前，复制 Blob创建的 blob。

在版本 2013-08-15 及更高版本中，EnumerationResults 元素包含指定 blob 终结点的 ServiceEndpoint 属性。此元素还包含一个指定容器名称的 ContainerName 字段。在以前的版本中，这两个属性在 ContainerName 字段中组合在一起。在版本 2013-08-15 及更高版本中，Blob 下的 Url 元素已被删除。

对于版本 2015-02-21 及更高版本，List Blobs 返回所有类型的 blob（块、页和追加 blob）。

对于版本 2015-12-11 及更高版本，List Blobs 返回 ServerEncrypted 元素。如果 blob 和应用程序元数据已完全加密，则此元素设置为 true，否则 false。

对于版本 2016-05-31 及更高版本，List Blobs 返回增量复制 blob 和快照的 IncrementalCopy 元素，该值设置为 true。

对于版本 2017-04-17 及更高版本，如果显式设置了访问层，List Blobs 返回 AccessTier 元素。有关允许的高级页 Blob 层的列表，请参阅 VM 的高性能高级存储和托管磁盘。对于 Blob 存储或常规用途 v2 帐户，有效值 Hot、Cool和 Archive。如果 blob 处于解除冻结挂起状态，则 ArchiveStatus 元素返回有效值之一（rehydrate-pending-to-hot、rehydrate-pending-to-cool或 rehydrate-pending-to-cold）。有关块 blob 分层的详细信息，请参阅热、冷和存档存储层。

对于版本 2017-04-17 及更高版本，List Blobs 返回 Blob 存储或常规用途 v2 帐户上的 AccessTierInferred 元素。如果块 Blob 没有访问层集，则从存储帐户属性推断层信息，此值设置为 true。仅当从帐户属性推断层时，才会显示此标头。

对于版本 2017-04-17 及更高版本，List Blobs 返回 Blob 存储或常规用途 v2 帐户上的 AccessTierChangeTime 元素。仅当已设置块 Blob 上的层时，才会返回此值。有关详细信息，请参阅标头中的日期/时间值的表示形式。

对于版本 2017-07-29 及更高版本，当此操作包含 include={deleted} 参数时，将显示 Deleted、DeletedTime和 RemainingRetentionDays。如果未删除此 Blob，则不会显示这些元素。启用软删除功能时，这些元素适用于使用 DELETE 操作删除的 blob 或快照。 Deleted 元素设置为软删除的 blob 和快照 true。 Deleted-Time 对应于删除 blob 的时间。 RemainingRetentionDays 指示软删除 Blob 永久删除后的天数。

对于版本 2017-11-09 及更高版本，Creation-Time 返回创建此 blob 的时间。

对于版本 2019-02-02 及更高版本，如果 blob 使用客户提供的密钥进行加密，则 List Blobs 返回 CustomerProvidedKeySha256 元素。该值将设置为用于加密 Blob 的密钥的 SHA-256 哈希。此外，如果操作包括 include={metadata} 参数，并且使用客户提供的密钥加密的 Blob 上存在应用程序元数据，则 Metadata 元素将具有 Encrypted="true" 属性。此属性指示 blob 的元数据不能作为 List Blobs 操作的一部分进行解密。若要访问这些 blob 的元数据，请使用客户提供的密钥调用获取 Blob 属性或获取 Blob 元数据。

对于版本 2019-02-02 及更高版本，如果 blob 使用加密范围加密，List Blobs 返回 EncryptionScope 元素。该值将设置为用于加密 Blob 的加密范围的名称。如果该操作包括 include={metadata} 参数，则 blob 上的应用程序元数据将透明解密，并在 Metadata 元素中可用。

对于版本 2019-12-12 及更高版本，如果对象处于 rehydrate pending 状态，List Blobs 返回 Blob 存储或常规用途 v2 帐户上的 RehydratePriority 元素。有效值为 High 和 Standard。

对于版本 2019-12-12 及更高版本，List Blobs 在帐户上启用版本控制时返回 blob 和生成的 blob 版本的 VersionId 元素。

对于版本 2019-12-12 及更高版本，List Blobs 返回 blob 当前版本的 IsCurrentVersion 元素。该值设置为 true。通过此元素，可以将当前版本与只读自动生成的版本区分开来。

对于版本 2019-12-12 及更高版本，List Blobs 返回具有任何标记的 blob TagCount 元素。仅当此操作包含 include={tags} 参数时，才会显示 Tags 元素。如果没有 Blob 上的标记，则不会显示这些元素。

对于版本 2019-12-12 及更高版本，List Blobs 返回追加 blob 的 Sealed 元素。仅当追加 blob 已密封时，才会显示 Sealed 元素。如果未密封追加 blob，则不会显示这些元素。

对于版本 2020-02-10 及更高版本，List Blobs 返回 LastAccessTime 元素。该元素根据存储帐户的上次访问时间跟踪策略显示 Blob 数据上次访问的时间。如果存储帐户没有此策略或禁用策略，则不会返回该元素。有关设置帐户上次访问时间跟踪策略的信息，请参阅 Blob 服务 API。 LastAccessTime 元素不会跟踪上次访问 blob 元数据的时间。

对于版本 2020-06-12 及更高版本，List Blobs 在此操作包括 include={immutabilitypolicy} 参数时返回 ImmutabilityPolicyUntilDate 和 ImmutabilityPolicyMode 元素。

对于版本 2020-06-12 及更高版本，List Blobs 在此操作包含 include={legalhold} 参数时返回 LegalHold 元素。

对于版本 2020-06-12 及更高版本，对于启用了分层命名空间的帐户，List Blobs 返回 Owner、Group、Permissions和 Acl 元素。请求必须包含 include={permissions} 参数。请注意，Acl 元素是文件或目录上设置的访问和默认访问控制列表的组合列表。

对于版本 2020-06-12 及更高版本，对于启用了分层命名空间的帐户，使用分隔符 List Blobs 返回 BlobPrefix 元素中的 Properties 元素。这与目录上的属性相对应。

对于版本 2020-08-04 及更高版本，对于启用了分层命名空间的帐户，List Blobs 返回已删除 blob 的 DeletionId 元素。 DeletionId 是一个无符号的 64 位标识符。该元素唯一标识软删除的路径，以将其与具有相同路径的其他已删除 Blob 区分开来。

对于版本 2020-10-02 及更高版本，对于启用了分层命名空间的帐户，List Blobs 返回路径的 ResourceType 属性元素。这可以是 file，也可以是 directory。

对于版本 2021-02-12 及更高版本，List Blobs 将按 RFC 2396 进行百分比编码（每个 RFC 2396），BlobName 或 BlobPrefixName 元素值。具体而言，对于那些在 XML 中无效的字符（U+FFFE 或 U+FFFF）的值，它将这样做。如果编码，Name 元素将包含 Encoded=true 属性。请注意，这只发生在包含 XML 中无效字符的 Name 元素值，而不是响应中的其余 Name 元素。

对于版本 2021-06-08 及更高版本，对于启用了分层命名空间的帐户，List Blobs 返回 Placeholder properties 元素。当列出带分隔符的已删除 blob 时，它会在占位符目录的 BlobPrefix 元素中返回此元素。这些占位符目录的存在有助于导航到软删除的 Blob。

对于版本 2021-06-08 及更高版本，对于启用了分层命名空间的帐户，List Blobs 返回 EncryptionContext 元素。如果设置加密上下文属性值，它将返回设置值。

对于版本 2020-02-10 及更高版本，对于启用了分层命名空间的帐户，List Blobs 返回已删除 blob 的 Expiry-Time 元素。 Expiry-Time 是文件过期的时间，如果在同一时间设置到期，则会返回该文件。

<?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>  
      <VersionId>date-time-vlue</VersionId>
      <IsCurrentVersion>true</IsCurrentVersion>
      <Deleted>true</Deleted>
      <Properties> 
        <Creation-Time>date-time-value</Creation-Time>
        <Last-Modified>date-time-value</Last-Modified>  
        <Etag>etag</Etag>
        <Owner>owner user id</Owner>
        <Group>owning group id</Group>
        <Permissions>permission string</Permissions>
        <Acl>access control list</Acl>
        <ResourceType>file | directory</ResourceType>
        <Placeholder>true</Placeholder>
        <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|AppendBlob</BlobType>  
        <AccessTier>tier</AccessTier>  
        <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>  
        <ServerEncrypted>true</ServerEncrypted> 
        <CustomerProvidedKeySha256>encryption-key-sha256</CustomerProvidedKeySha256>
        <EncryptionContext>encryption-context<EncryptionContext>
        <EncryptionScope>encryption-scope-name</EncryptionScope>
        <IncrementalCopy>true</IncrementalCopy>
        <AccessTierInferred>true</AccessTierInferred>
        <AccessTierChangeTime>datetime</AccessTierChangeTime>
        <DeletedTime>datetime</DeletedTime>
        <RemainingRetentionDays>no-of-days</RemainingRetentionDays>
        <TagCount>number of tags between 1 to 10</TagCount>
        <RehydratePriority>rehydrate priority</RehydratePriority>
        <Expiry-Time>date-time-value</Expiry-Time>
      </Properties>  
      <Metadata>     
        <Name>value</Name>  
      </Metadata>  
      <Tags>
          <TagSet>
              <Tag>
                  <Key>TagName</Key>
                  <Value>TagValue</Value>
              </Tag>
          </TagSet>
      </Tags>
      <OrMetadata />
    </Blob>  
    <BlobPrefix>  
      <Name>blob-prefix</Name>  
    </BlobPrefix>  
  </Blobs>  
  <NextMarker />  
</EnumerationResults>

示例响应

有关示例响应，请参阅枚举 blob 资源。

授权

在 Azure 存储中调用任何数据访问操作时，需要授权。可以按如下所述授权 List Blobs 操作。

重要

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 用户、组、托管标识或服务主体调用 List Blobs 操作所需的 RBAC 操作，以及包含此操作的最小特权内置 Azure RBAC 角色：

Azure RBAC 操作：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
最低特权内置角色：存储 Blob 数据读取者

如果指定 include=tags：

Azure RBAC 操作：Microsoft.Storage/storageAccounts/blobServices/containers/blobs/tags/read
最低特权内置角色：存储 Blob 数据所有者

若要详细了解如何使用 Azure RBAC 分配角色，请参阅分配 Azure 角色以访问 blob 数据。

共享访问签名（SAS）提供对存储帐户中资源的安全委派访问权限。使用 SAS，可以精细控制客户端如何访问数据。可以指定客户端可以访问哪些资源、这些资源具有哪些权限，以及 SAS 的有效时间。

List Blobs 操作支持三种类型的共享访问签名：用户委托 SAS、服务 SAS，以及帐户 SAS。

作为安全最佳做法，我们建议使用 Microsoft Entra 凭据，而不是存储帐户密钥，这可能会更容易受到威胁。如果应用程序设计需要共享访问签名，请尽可能使用 Microsoft Entra 凭据创建用户委托 SAS。

不允许对存储帐户进行共享密钥访问时，不允许对 Blob 存储的请求使用服务 SAS 令牌或帐户 SAS 令牌。若要了解详细信息，请参阅了解禁止共享密钥如何影响 SAS 令牌。

用户委派 SAS

用户委托 SAS 使用 Microsoft Entra 凭据以及为 SAS 指定的权限进行保护。

使用委托给容器资源的 SAS 令牌调用 List Blobs 操作需要 列表（l） 权限作为用户委派 SAS 令牌的一部分。

若要了解有关用户委派 SAS 的详细信息，请参阅创建用户委派 SAS。

服务 SAS

使用存储帐户密钥保护服务 SAS。服务 SAS 委托对单个 Azure 存储服务（例如 Blob 存储）中的资源的访问权限。

使用委托给容器资源的 SAS 令牌调用 List Blobs 操作需要 列表（l） 权限作为服务 SAS 令牌的一部分。

若要了解有关服务 SAS 的详细信息，请参阅创建服务 SAS。

帐户 SAS

帐户 SAS 使用存储帐户密钥进行保护。帐户 SAS 委托对一个或多个存储服务中的资源的访问权限。通过服务或用户委托 SAS 提供的所有操作也通过帐户 SAS 提供。

下表指示委派访问时要指定的已签名资源类型和已签名权限：

操作	已签名的服务	已签名的资源类型	已签名权限
列出 Blob	Blob （b）	容器（c）	列表（l）

若要了解有关帐户 SAS 的详细信息，请参阅创建帐户 SAS。

言论

响应中的 Blob 属性

如果已请求在枚举中包含未提交的 Blob，请注意，在提交 Blob 之前不会设置某些属性。某些属性可能不会在响应中返回。

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

仅为块 blob 返回 OrMetadata 元素。

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

仅当已使用版本 2009-09-19 或更高版本在 Blob 上设置该元素时，Content-MD5 元素才会显示在响应正文中。可以在创建 blob 时设置 Content-MD5 属性，也可以通过调用设置 Blob 属性。在版本 2012-02-12 及更高版本中，Put Blob 设置块 blob 的 MD5 值，即使 Put Blob 请求不包含 MD5 标头也是如此。

响应中的元数据

仅当在 URI 上指定了 include=metadata 参数时，Metadata 元素才存在。在 Metadata 元素中，每个名称/值对的值列在对应于对名称的元素中。

请注意，使用此参数请求的元数据必须按照 Blob 存储的 2009-09-19 版本施加的命名限制进行存储。从此版本开始，所有元数据名称必须遵循 C# 标识符的命名约定。

如果元数据名称值对违反这些命名限制，响应正文指示 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=tags 参数，并且 blob 上存在标记时，才会显示 Tags 元素。在 TagSet 元素中，最多返回 10 个 Tag 元素，每个元素包含用户定义的 blob 索引标记 key 和 value。响应中不能保证标记的排序。

如果没有 Blob 上的标记，则不会返回 Tags 和 TagCount 元素。

存储服务保持 Blob 与其标记之间的强一致性，但辅助索引最终保持一致。标记可以在响应 List Blobs 中可见，然后才能 Find Blobs by Tags 操作。

响应中的快照

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

使用服务版本 2021-06-08 及更高版本，可以使用分隔符调用 List Blobs，并在枚举中包含快照。对于 2021-06-08 之前的服务版本，包含两者的请求都返回 InvalidQueryParameter 错误（HTTP 状态代码 400 – 错误请求）。

响应中未提交的 Blob

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

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

响应中已删除的 Blob

仅当在 URI 上指定了 include=deleted 参数时，才会在响应中列出已删除的 blob。响应中列出的已删除 blob 不包括租约元素，因为已删除的 blob 不能有活动租约。

如果在 URI 上指定了 include=deleted,snapshot，则列表响应中包含已删除的快照。

响应中的对象复制元数据

在 Blob 上评估对象复制策略并且使用版本 2019-12-12 或更高版本进行 List Blobs 调用时，会出现 OrMetadata 元素。在 OrMetadata 元素中，每个名称/值对的值列在对应于对名称的元素中。名称的格式为 or-{policy-id}_{rule-id}，其中 {policy-id} 是表示存储帐户上的对象复制策略标识符的 GUID。 {rule-id} 是表示存储容器上的规则标识符的 GUID。有效值为 complete 或 failed。

  
…  
<OrMetadata>  
  <or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>complete</or-e524bba7-4323-4b93-91f8-d09d5d0b7057_d86c51de-ef02-4264-bdcf-dcd389a6c7ac>  
  <or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>failed</or-2b302b5d-fcd5-44d6-a5ed-455bf27e17ea_4a398ff5-2a89-4090-879b-10248f23428e>  
</OrMetadata>  
…

响应中的不可变性策略

仅当 URI 上指定了 include=immutabilitypolicy 参数时，才会显示 ImmutabilityPolicyUntilDate 和 ImmutabilityPolicyMode 元素。

<Properties> 
   <ImmutabilityPolicyUntilDate>date-time-value</ImmutabilityPolicyUntilDate>   
   <ImmutabilityPolicyMode>unlocked | locked </ImmutabilityPolicyMode>  
</Properties>

响应中的法定保留

仅当在 URI 上指定了 include=legalhold 参数时，LegalHold 元素才存在。

<Properties> 
  <LegalHold>true | false </LegalHold>  
</Properties>

使用标记值返回结果集

如果为 maxresults 参数指定一个值，并且要返回的 blob 数超过此值，或超过 maxresults的默认值，响应正文将包含 NextMarker 元素。此元素指示在后续请求中返回的下一个 Blob。在某些情况下，服务可能会返回 NextMarker 元素，即使返回的结果数小于 maxresults的值。

若要返回下一组项，请将 NextMarker 的值指定为后续请求 URI 上的标记参数。请注意，应将 NextMarker 的值视为不透明。

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

delimiter 参数使调用方能够使用用户配置的分隔符遍历 Blob 命名空间。通过这种方式，可以遍历 Blob 的虚拟层次结构，就像它是文件系统一样。分隔符可以是单个字符或字符串。

当请求包含此参数时，该操作将返回 BlobPrefix 元素。返回 BlobPrefix 元素，代替名称以相同子字符串开头的所有 blob，最多返回分隔符字符的外观。 BlobPrefix 元素的值是 子字符串+分隔符，其中 子字符串 是开始一个或多个 blob 名称的常见子字符串，分隔符 是 delimiter 参数的值。

可以使用 BlobPrefix 的值进行后续调用，以列出以此前缀开头的 blob。为此，请在请求 URI 上指定 prefix 参数的 BlobPrefix 值。

请注意，每个 BlobPrefix 元素返回的计数为最大结果，就像每个 Blob 元素一样。

Blob 按字母顺序在响应正文中列出，并首先列出大写字母。

复制状态说明中的复制错误

CopyStatusDescription 包含有关 Copy Blob 失败的详细信息。

复制尝试失败时，如果 Blob 存储仍在重试操作，CopyStatus 将设置为 pending。 CopyStatusDescription 文本描述上次复制尝试期间可能发生的失败。
当 CopyStatus 设置为 failed时，CopyStatusDescription 文本描述导致复制操作失败的错误。

下表描述了每个 CopyStatusDescription 值的字段。

元件	描述
HTTP 状态代码	指定失败的标准三位数整数。
错误代码	描述错误的关键字。 Azure 在 <ErrorCode> 元素中提供。如果未显示 <ErrorCode> 元素，服务将返回一个关键字，该关键字包含与 HTTP 规范中的三位数 HTTP 状态代码关联的标准错误文本。有关详细信息，请参阅常见 REST API 错误代码。
信息	失败的详细说明，以引号为单位。

下表介绍了常见故障方案的 CopyStatus 和 CopyStatusDescription 值。

重要

此处显示的说明文本无需警告即可更改，即使没有版本更改也是如此。不要依赖于匹配此确切文本。

场景	复制状态值	复制状态说明值
复制操作成功完成。	成功	空
用户在完成复制操作之前中止了复制操作。	中止	空
在复制操作期间从源 Blob 读取时发生失败。将重试该操作。	待定	502 BadGateway “读取源时遇到可重试错误。将重试。失败时间：<时间>”
写入复制操作的目标 Blob 时发生失败。将重试该操作。	待定	500 InternalServerError “遇到可重试的错误。将重试。失败时间：<时间>”
从复制操作的源 Blob 读取时发生不可恢复的失败。	失败	404 ResourceNotFound “读取源时复制失败”。当服务报告此基础错误时，它会在 <ErrorCode> 元素中返回 `ResourceNotFound`。如果未在响应中显示 <ErrorCode> 元素，则会显示 HTTP 状态的标准字符串表示形式（如 `NotFound`）。
限制所有复制操作已用的超时期限。（目前超时期限为两周。	失败	500 OperationCancelled “副本超出了允许的最大时间”。
从源读取时复制操作失败，并且未达到尝试成功次数的最小比率。（此超时可防止在失败前两周内重试非常糟糕的源）。	失败	500 OperationCancelled “读取源时复制失败。

计费

定价请求可能源自使用 Blob 存储 API 的客户端，可以直接通过 Blob 存储 REST API 或 Azure 存储客户端库。这些请求按事务产生费用。事务类型会影响帐户的计费方式。例如，读取事务累算到与写入事务不同的计费类别。下表显示了基于存储帐户类型的 List Blobs 请求的计费类别：

操作	存储帐户类型	计费类别
列出 Blob	高级块 blob 标准常规用途 v2 标准常规用途 v1	列出和创建容器操作

若要了解指定计费类别的定价，请参阅 Azure Blob 存储定价。

另请参阅

状态和错误代码
 Blob 存储错误代码

通过