您可以使用对象存储OSS的清单功能获取存储空间(Bucket)中指定文件(Object)的数量、大小、存储类型、加密状态等信息。相对于GetBucket (ListObjects)接口,在海量Object的列举场景中,建议您优先使用清单功能。
功能说明
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.json和manifest.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大小。 LastModifiedDate Object的最后修改时间。 ETag Object的ETag。 Object生成时会创建相应的ETag,用于标识一个Object的内容。
- 通过PutObject接口创建的Object,ETag值是其内容的MD5值。
- 通过其他方式创建的Object,ETag值是其内容的UUID。
StorageClass Object的存储类型。 IsMultipartUploaded Object是否通过分片上传生成。如果是,则该字段值为True,否则为False。 EncryptionStatus Object是否已加密。若Object已加密,则该字段值为True,否则为False。 - manifest文件
manifest文件包含manifest.json和manifest.checksum:
- manifest.json:提供了有关清单的元数据和其他基本信息,包括如下内容。
字段名称 说明 creationTimestamp 以纪元日期格式创建的时间戳,显示开始扫描源Bucket的时间。 destinationBucket 存储清单文件的目标Bucket。 fileFormat 清单文件的格式。 fileSchema 清单文件包含的字段。 files 包含清单文件的文件名、大小、MD5值。 sourceBucket 创建清单文件的源Bucket。 version 清单版本。 - manifest.checksum:包含manifest.json文件的MD5值。
- manifest.json:提供了有关清单的元数据和其他基本信息,包括如下内容。
注意事项
- 费用说明
- 使用Bucket清单功能会产生一定的费用,公测期间仅收取API请求费用和清单文件存储费用,暂不收取功能使用费用。
- 在您删除清单规则前,OSS会按照清单规则一直生成清单文件,会产生一定的存储费用。为避免产生不必要的费用,请及时清理不再需要的清单文件。
- 权限说明
使用RAM用户配置清单规则时,需具有以下权限:
- 配置清单时,需调用PutBucketInventory、GetBucketInventory、ListBucketInventory、DeleteBucketInventory接口,所以需要有对应接口的调用权限。
- 配置清单规则前需生成一个RAM角色,该角色需要拥有读取源Bucket所有文件和向目标Bucket写入文件的权限。若阿里云账号没有这个角色,RAM用户需要有CreateRole和GetRole权限;若阿里云账号已有这个角色,则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生成的提醒。配置事件通知方式,请参见设置事件通知规则。