您可以使用对象存储OSS的清单功能获取存储空间(Bucket)中指定文件(Object)的数量、大小、存储类型、加密状态等信息。相对于GetBucket (ListObjects)接口,在海量Object的列举场景中,建议您优先使用清单功能。

功能说明

清单任务配置完成后,OSS会按清单规则指定的导出周期生成清单报告。清单文件的存储目录树结构如下:
dest_bucket
 └──destination-prefix/
     └──src_bucket/
         └──inventory_id/
             ├──YYYY-MM-DDTHH-MMZ/
             │   ├──manifest.json
             │   └──manifest.checksum
             └──data/
                 └──745a29e3-bfaa-490d-9109-47086afcc8f2.csv.gz
目录结构 说明
destination-prefix/ 该目录根据设置的清单报告名前缀生成,如果清单报告名前缀设置为空,将省略该目录。
src_bucket/ 该目录根据配置清单报告的源Bucket名生成。
inventory_id/ 该目录根据清单任务的规则名称生成。
YYY-MM-DDTHH-MMZ/ 该目录是标准的格林威治时间戳,表示开始扫描Bucket的时间,例如2020-05-17T16-00Z。该目录下包含了manifest.jsonmanifest.checksum文件。
data/ 该目录下存放了包含源Bucket中的对象列表以及每个对象的元数据的清单文件,清单文件格式为使用GZIP压缩的CSV文件。
清单功能生成的具体文件如下:
  • 清单文件
    清单文件存储在data/目录中,包含清单功能导出的文件信息。您可以通过manifest.json文件的fileSchema字段来获取清单文件的字段列信息。清单样例如下:清单
    清单文件的所有字段从左到右分别为:
    字段名称 描述
    Bucket 执行清单任务的源Bucket名称。
    Key Bucket中Object的名称。

    Object名称使用URL编码,您必须解码后查看。

    VersionId Object的版本ID。

    仅当Bucket已开启版本控制功能,且您配置的清单规则为导出所有版本时出现此字段。

    IsLatest Object版本是否为最新版本。当版本为最新版本时取值为True,否则取值为False

    仅当Bucket已开启版本控制功能,且您配置的清单规则为导出所有版本时出现此字段。

    IsDeleteMarker Object版本是否为删除标记。当版本为删除标记时取值为True,否则取值为False

    仅当Bucket已开启版本控制功能,且您配置的清单规则为导出所有版本时出现此字段。

    Size Object大小。
    StorageClass Object的存储类型。
    LastModifiedDate Object的最后修改时间。
    ETag Object的ETag。

    Object生成时会创建相应的ETag,用于标识一个Object的内容。

    • 通过PutObject接口创建的Object,ETag值是其内容的MD5值。
    • 通过其他方式创建的Object,ETag值是其内容的UUID。
    IsMultipartUploaded Object是否通过分片上传生成。如果是,则该字段值为True,否则为False
    EncryptionStatus Object是否已加密。若Object已加密,则该字段值为True,否则为False
  • manifest文件
    manifest文件包含manifest.jsonmanifest.checksum
    • manifest.json:提供了有关清单的元数据和其他基本信息,包括如下内容。
      字段名称 说明
      creationTimestamp 以纪元日期格式创建的时间戳,显示开始扫描源Bucket的时间。
      destinationBucket 存储清单文件的目标Bucket。
      fileFormat 清单文件的格式。
      fileSchema 清单文件包含的字段。
      files 包含清单文件的文件名、大小、MD5值。
      sourceBucket 创建清单文件的源Bucket。
      version 清单版本。
    • manifest.checksum:包含manifest.json文件的MD5值。

注意事项

  • 费用说明
    • 使用Bucket清单功能会产生一定的费用,公测期间仅收取API请求费用和清单文件存储费用,暂不收取功能使用费用。
    • 在您删除清单规则前,OSS会按照清单规则一直生成清单文件,会产生一定的存储费用。为避免产生不必要的费用,请及时清理不再需要的清单文件。
  • 权限说明
    使用RAM用户配置清单规则时,需具有以下权限:
    • 配置清单时,需调用PutBucketInventoryGetBucketInventoryListBucketInventoryDeleteBucketInventory接口,所以需要有对应接口的调用权限。
    • 配置清单规则前需生成一个RAM角色,该角色需要拥有读取源Bucket所有文件和向目标Bucket写入文件的权限。若阿里云账号没有这个角色,RAM用户需要有CreateRoleGetRole权限;若阿里云账号已有这个角色,则RAM用户需要有GetRole权限。

      配置角色的步骤,请参见创建可信实体为阿里云服务的RAM角色

  • 配置限制
    • 配置清单的源Bucket与存放清单文件的目标Bucket可以相同也可以不同,但是必须属于同一账号下的相同地域。
    • 单个Bucket最多只能配置1000条清单规则,通过OSS管理控制台最多可配置10条清单规则。
  • 配置建议

    建议您根据源Bucket内的文件数量配置清单任务:

    • 文件数量小于10亿,可以以天为单位生成清单文件。
    • 文件数量为小于100亿,可以以周为单位生成清单文件。
    • 文件数量大于100亿,建议以周为单位,并针对不同的文件前缀设置不同的清单任务,保证每个清单任务涉及的文件不超过100亿个。
  • 异常说明
    • 若源Bucket没有任何文件,或清单任务设置的前缀没有匹配到任何文件,则不会生成清单文件。
    • 导出清单文件的过程中,由于Object的创建、删除或覆盖等操作,可能会导致最终输出的清单列表中不一定包含所有的Object。最后修改时间早于manifest.json文件中createTimeStamp字段显示时间的Object会出现在清单文件中;最后修改时间晚于createTimeStamp字段显示时间的Object可能不会出现在清单文件中。建议您对清单列表中的Object进行操作之前,先使用HeadObject接口检查Object的属性。更多信息,请参见HeadObject

操作方式

操作方式 说明
控制台 Web应用程序,直观易用
命令行工具ossutil 命令行工具,性能好
Java SDK 丰富、完整的各类语言SDK demo
Python SDK
Go SDK
C++ SDK

常见问题

如何快速得知清单文件已生成?

涉及Object较多时,清单文件生成需要一定的时间。若您希望第一时间获知清单文件已生成,建议您在生成清单的目标Bucket中配置事件通知规则,将事件类型设置为PutObject。当清单生成之后,您会收到Object生成的提醒。配置事件通知方式,请参见设置事件通知规则