文档

存储空间清单

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

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

警告

为避免影响OSS-HDFS服务的正常使用或者引发数据污染的风险,在开通了OSS-HDFS服务的Bucket设置清单报告规则时,禁止将清单报告目录填写为.dlsdata/

计费说明

  • 使用Bucket清单功能会产生一定的费用,公测期间仅收取API请求费用和清单文件存储费用,暂不收取功能使用费用。

  • 在您删除清单规则前,OSS会按照清单规则一直生成清单文件,会产生一定的存储费用。为避免产生不必要的费用,请及时清理不再需要的清单文件。

使用限制

  • 对于单个Bucket,通过SDK或者命令行工具ossutil最多可配置1000条清单规则,通过OSS管理控制台最多可配置10条清单规则。

  • 配置清单的源Bucket与存放清单文件的目标Bucket可以相同也可以不同,但是必须属于同一账号下的相同地域。

  • 金融云地域不支持配置存储空间清单。

  • 无地域属性Bucket不支持配置存储空间清单。

权限说明

使用Bucket清单功能时,涉及创建清单规则以及向目标Bucket写入清单结果文件的操作。创建清单规则的操作由用户完成,向目标Bucket写入清单结果文件的操作是OSS服务通过扮演用户创建的RAM角色来完成。

您可以通过以下步骤为RAM用户授权,创建RAM角色并为RAM角色授权。授权完成后,您可以创建清单规则。具体操作,请参见创建清单规则

重要

考虑到授予RAM用户创建CreateRoleGetRoles等角色相关的权限风险较大,您可以通过RAM用户关联的阿里云账号创建RAM角色并为相应的RAM角色完成授权。授权完成后,RAM用户可以直接复用阿里云账号创建的RAM角色。

  • RAM用户授权

    按如下步骤授予RAM用户拥有创建Role以及配置清单规则的权限。

    1. 通过脚本编辑模式创建以下自定义策略。具体操作,请参见创建自定义权限策略

      说明

      以下授权策略中,仅在通过控制台的方式访问时,需要授予RAM用户oss:ListBuckets的Action。通过SDK或者ossutil等方式访问时,不需要授予RAM用户oss:ListBuckets的Action。

      {
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "oss:PutBucketInventory",
                      "oss:GetBucketInventory",
                      "oss:DeleteBucketInventory",
                      "oss:ListBuckets",
                      "ram:CreateRole",
                      "ram:AttachPolicyToRole",
                      "ram:GetRole",
                      "ram:ListPoliciesForRole"
                  ],
                  "Resource": "*"
              }
          ],
          "Version": "1"
      }
      重要

      如果当前账号下已创建包含AliyunOSSFullAccess系统权限的RAM用户,由于AliyunOSSFullAccess包含了所有操作OSS资源的权限,则只需要为RAM用户授予以下与Role相关的权限。

      {
          "Statement": [
              {
                  "Effect": "Allow",
                  "Action": [
                      "ram:CreateRole",
                      "ram:AttachPolicyToRole",
                      "ram:GetRole",
                      "ram:ListPoliciesForRole"
                  ],
                  "Resource": "*"
              }
          ],
          "Version": "1"
      }
    2. 为RAM用户授予已创建的自定义策略。具体操作,请参见为RAM用户授权

      完成RAM用户授权后,RAM用户具备创建RAM角色以及为RAM角色授权的权限,请参见后续步骤完成RAM角色授权。

  • 创建RAM角色并为RAM角色授权

    重要

    如果您希望使用KMS密钥加密清单文件,您还需要为创建的RAM角色授予AliyunKMSFullAccess(管理密钥管理服务KMS的权限)。

    • 自动创建的RAM角色AliyunOSSRole

      通过控制台配置清单规则时,RAM控制台会自动创建RAM角色AliyunOSSRole,该角色默认拥有向目标Bucket写入清单结果文件的权限。

      重要

      使用自动创建的RAM角色AliyunOSSRole可以避免额外的授权操作,但是该角色默认拥有管理OSS的权限,权限范围较大。基于权限范围考虑,您还可以选择创建自定义RAM角色,并授予RAM角色最小权限。

    • 自定义RAM角色

      如果您需要使用自定义RAM角色向目标Bucket写入清单结果文件,请执行以下步骤创建RAM角色并为该角色授予权限策略:

      1. 创建普通服务角色。

        创建普通服务角色过程中,受信服务选择对象存储。其他参数的配置信息,请参见创建可信实体为阿里云服务的RAM角色

      2. 通过可视化编辑模式创建自定义权限策略。

        创建自定义权限策略过程中,您需要按照以下说明配置权限策略。其他参数的配置信息,请参见创建自定义权限策略

        参数

        说明

        效果

        选中允许

        服务

        选中对象存储

        操作

        选中指定操作,然后选中写操作下的oss:PutObject

        资源

        选中全部资源

        该权限策略对应的JSON格式如下:

        {
          "Version": "1",
          "Statement": [
            {
              "Effect": "Allow",
              "Action": "oss:PutObject",
              "Resource": "*"
            }
          ]
        }
      3. 为角色授予自定义权限策略。

        具体操作,请参见为RAM角色授权

操作步骤

使用OSS控制台

  1. 登录OSS管理控制台

  2. 单击Bucket 列表,然后单击目标Bucket名称。

  3. 在左侧导航栏,选择数据管理 > Bucket 清单

  4. Bucket 清单页面,单击创建清单

  5. 设置清单报告规则面板,按以下说明配置各项参数。

    参数

    说明

    状态

    设置清单任务的状态。可以选择启动禁用

    规则名称

    设置清单任务的名称。只能包含小写字母、数字、短划线(-),且不能以短划线(-)开头或结尾。

    存储清单 Bucket

    选择存储清单文件的Bucket。

    配置清单的源Bucket与存放清单文件的目标Bucket可以相同也可以不同,但是必须属于同一账号下的相同地域。

    清单报告存储路径

    设置清单报告存储路径。

    • 如果要将清单报告保存在Bucket根目录下,请将此项置空。

    • 如果要将清单报告保存在Bucket非根目录下,请填写不包含Bucket名称在内的完整路径。

      例如,当您需要将清单报告保存在存储空间examplebucket的exampledir1路径下,则填写为exampledir1。当您需要将清单报告保存在存储空间examplebucket的exampledir1/exampledir2路径下,则填写为exampledir1/exampledir2

    说明

    如果Bucket中不存在指定的清单报告存储路径,OSS会根据填写的清单报告存储路径自动创建对应的路径。

    清单报告导出周期

    设置清单报告的生成周期。可选择每周每天

    • 当文件数量小于100亿时,您可以根据自己的业务需要,设置按周或按天导出清单。

    • 当文件数量大于100亿时,建议设置以周为单位导出清单。

    清单报告加密选项

    是否加密清单文件。

    • :不加密。

    • AES256:使用AES256加密算法加密清单文件。

    • KMS:使用KMS密钥加密清单文件。

      您可以选择使用OSS托管的KMS密钥或在KMS平台创建一个与目标Bucket相同地域的KMS密钥。KMS密钥配置步骤,请参见创建密钥

      说明

      使用KMS密钥功能时会产生少量的KMS密钥API调用费用,费用详情请参考KMS计费标准

    清单内容

    选择您希望导出的文件信息,包括Object大小存储类型最后更新时间ETag分片上传状态加密状态Object ACL标签个数文件类型Crc64

    按前缀匹配

    设置清单规则扫描Object的前缀。

    • 如果要扫描整个Bucket内的所有Object,请将此项置空。

    • 如果要扫描Bucket某个路径下的所有Object,请填写不包含Bucket名称在内的完整路径。

      例如,当您需要扫描存储空间examplebucket的exampledir1路径下的所有Object,则填写为exampledir1/。如果您需要扫描examplebucket的exampledir1/exampledir2路径下的所有Object,则填写为exampledir1/exampledir2/

    说明

    如果设置的前缀没有匹配Bucket内的任意Object,则不生成清单文件。

    配置高级筛选功能

    如果您需要根据文件大小、存储类型等条件过滤导出的文件,需要打开配置高级筛选功能开关。支持的过滤选项说明如下:

    重要

    仅华北1(青岛)、华北5(呼和浩特)、德国(法兰克福)以及澳大利亚(悉尼)地域支持配置以下过滤选项。

    • 时间范围:设置待导出文件最后一次修改的起始日期和结束日期,时间精确到秒。

    • 文件大小范围:设置待导出文件的文件大小最小值和最大值。

      重要

      设置文件大小范围时,确保文件大小的最小值以及最大值均大于0 B,且最大值不超过48.8 TB。

    • 存储类型:设置待导出哪些存储类型的文件。您可以选择导出标准存储、低频访问存储、归档存储以及冷归档存储的文件。

    对象版本

    选择清单扫描的文件版本。

    如果Bucket已开启版本控制,可选择导出目标文件的当前版本所有版本。更多信息,请参见版本控制概述

    如果Bucket未开启版本控制,默认导出所有文件。

  6. 选中我知晓并同意授予阿里云 OSS 服务访问 Bucket 资源的权限,然后单击确定

    涉及Object较多时,生成清单文件需要一定的时间。您可以通过两种方式判断是否已生成清单文件,详情请参见如何判断是否已生成清单文件?

使用阿里云SDK

以下仅列举常见SDK配置Bucket清单的代码示例。关于其他SDK的配置Bucket清单代码示例,请参见SDK简介

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;
import java.util.ArrayList;
import java.util.List;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Endpoint以华东1(杭州)为例,其它Region请按实际情况填写。
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // 填写Bucket名称,例如examplebucket。
        String bucketName = "examplebucket";
        // 填写存放清单结果的Bucket名称。
        String destBucketName ="yourDestinationBucketName";
        // 填写Bucket所有者授予的账户ID。
        String accountId ="yourDestinationBucketAccountId";
        // 填写具有读取源Bucket所有文件和向目标Bucket写入文件权限的角色名称。
        String roleArn ="yourDestinationBucketRoleArn";

        // 创建OSSClient实例。
        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            // 创建清单配置。
            InventoryConfiguration inventoryConfiguration = new InventoryConfiguration();

            // 设置清单规则名称。
            String inventoryId = "testid";
            inventoryConfiguration.setInventoryId(inventoryId);

            // 设置清单中包含的Object属性。
            List<String> fields = new ArrayList<String>();
            fields.add(InventoryOptionalFields.Size);
            fields.add(InventoryOptionalFields.LastModifiedDate);
            fields.add(InventoryOptionalFields.IsMultipartUploaded);
            fields.add(InventoryOptionalFields.StorageClass);
            fields.add(InventoryOptionalFields.ETag);
            fields.add(InventoryOptionalFields.EncryptionStatus);
            inventoryConfiguration.setOptionalFields(fields);

            // 设置清单的生成计划,以下示例为每周一次。其中,Weekly表示每周一次,Daily表示每天一次。
            inventoryConfiguration.setSchedule(new InventorySchedule().withFrequency(InventoryFrequency.Weekly));

            // 设置清单中包含的Object的版本为当前版本。如果设置为InventoryIncludedObjectVersions.All则表示Object的所有版本在版本控制状态下生效。
            inventoryConfiguration.setIncludedObjectVersions(InventoryIncludedObjectVersions.Current);

            // 清单配置是否启用的标识,取值为true或者false,设置为true表示启用清单配置,设置为false表示关闭清单配置。
            inventoryConfiguration.setEnabled(true);

            // 设置清单筛选规则,指定筛选Object的前缀。
            InventoryFilter inventoryFilter = new InventoryFilter().withPrefix("obj-prefix");
            inventoryConfiguration.setInventoryFilter(inventoryFilter);

            // 创建存放清单结果的目标Bucket配置。
            InventoryOSSBucketDestination ossInvDest = new InventoryOSSBucketDestination();
            // 设置存放清单结果的存储路径前缀。
            ossInvDest.setPrefix("destination-prefix");
            // 设置清单格式。
            ossInvDest.setFormat(InventoryFormat.CSV);
            // 设置目标Bucket的用户accountId。
            ossInvDest.setAccountId(accountId);
            // 设置目标Bucket的roleArn。
            ossInvDest.setRoleArn(roleArn);
            // 设置目标Bucket的名称。
            ossInvDest.setBucket(destBucketName);

            // 如果需要使用KMS加密清单,请参考如下设置。
            // InventoryEncryption inventoryEncryption = new InventoryEncryption();
            // InventoryServerSideEncryptionKMS serverSideKmsEncryption = new InventoryServerSideEncryptionKMS().withKeyId("test-kms-id");
            // inventoryEncryption.setServerSideKmsEncryption(serverSideKmsEncryption);
            // ossInvDest.setEncryption(inventoryEncryption);

            // 如果需要使用OSS服务端加密清单,请参考如下设置。
            // InventoryEncryption inventoryEncryption = new InventoryEncryption();
            // inventoryEncryption.setServerSideOssEncryption(new InventoryServerSideEncryptionOSS());
            // ossInvDest.setEncryption(inventoryEncryption);

            // 设置清单的目的地。
            InventoryDestination destination = new InventoryDestination();
            destination.setOssBucketDestination(ossInvDest);
            inventoryConfiguration.setDestination(destination);

            // 上传清单配置。
            ossClient.setBucketInventoryConfiguration(bucketName, inventoryConfiguration);
        } catch (OSSException oe) {
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
                    + "but was rejected with an error response for some reason.");
            System.out.println("Error Message:" + oe.getErrorMessage());
            System.out.println("Error Code:" + oe.getErrorCode());
            System.out.println("Request ID:" + oe.getRequestId());
            System.out.println("Host ID:" + oe.getHostId());
        } catch (ClientException ce) {
            System.out.println("Caught an ClientException, which means the client encountered "
                    + "a serious internal problem while trying to communicate with OSS, "
                    + "such as not being able to access the network.");
            System.out.println("Error Message:" + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}
const OSS = require('ali-oss');

const client = new OSS({
  // yourregion填写Bucket所在地域。以华东1(杭州)为例,Region填写为oss-cn-hangzhou。
  region: 'yourregion',
  // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // 填写存储空间名称。
  bucket: 'yourbucketname'
});

const inventory = {
  // 设置清单配置ID。
  id: 'default', 
  // 清单配置是否启用的标识,取值为true或false。
  isEnabled: false, 
  //(可选)设置清单筛选规则,指定筛选object的前缀。
  prefix: 'ttt',
  OSSBucketDestination: {
     // 设置清单格式。
    format: 'CSV',
   // 目标Bucket拥有者的账号ID。
    accountId: '<Your AccountId>', 
   // 目标Bucket的角色名称。
    rolename: 'AliyunOSSRole',
    // 目标Bucket的名称。
    bucket: '<Your BucketName>',
    //(可选)清单结果的存储路径前缀。
    prefix: '<Your Prefix>',
    // 如果需要使用SSE-OSS加密清单,请参考以下代码。
    //encryption: {'SSE-OSS': ''},
    // 如果需要使用SSE-KMS加密清单,请参考以下代码。
           /*
            encryption: {
      'SSE-KMS': {
        keyId: 'test-kms-id',
      };, 
    */
  },
  // 设置清单的生成计划,WEEKLY对应每周一次,DAILY对应每天一次。
  frequency: 'Daily', 
  // 设置清单结果中包含了Object的所有版本, 如果设置为Current,则表示仅包含Object的当前版本。
  includedObjectVersions: 'All', 
  optionalFields: {
    //(可选)设置清单中包含的Object属性。
    field: ["Size", "LastModifiedDate", "ETag", "StorageClass", "IsMultipartUploaded", "EncryptionStatus"]
  },
}

async function putInventory(){
  // 需要添加清单配置的Bucket名称。
  const bucket = '<Your BucketName>'; 
        try {
    await client.putBucketInventory(bucket, inventory);
    console.log('清单配置添加成功')
  } catch(err) {
    console.log('清单配置添加失败: ', err);
  }
}

putInventory()
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from oss2.models import (InventoryConfiguration,
                         InventoryFilter,
                         InventorySchedule,
                         InventoryDestination,
                         InventoryBucketDestination,
                         INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
                         INVENTORY_FREQUENCY_DAILY,
                         INVENTORY_FORMAT_CSV,
                         FIELD_SIZE,
                         FIELD_LAST_MODIFIED_DATE,
                         FIELD_STORAG_CLASS,
                         FIELD_ETAG,
                         FIELD_IS_MULTIPART_UPLOADED,
                         FIELD_ENCRYPTION_STATUS)

# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# 填写Bucket名称,例如examplebucket。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# 填写Bucket所有者授予的账户ID。例如:1283641033516515
account_id = 'yourtBucketDestinationAccountId'
# 填写具有读取源Bucket所有文件和向目标Bucket写入文件权限的角色名称。例如:acs:ram::1283641033516515:role/AliyunOSSRole
role_arn = 'yourBucketDestinationRoleArn'
# 填写存放清单结果的Bucket名称。
dest_bucket_name = 'yourDestinationBucketName'

# 设置清单规则名称。
inventory_id = "inventory1"

# 设置清单结果中包含的Object属性。
optional_fields = [FIELD_SIZE, FIELD_LAST_MODIFIED_DATE, FIELD_STORAG_CLASS,
                   FIELD_ETAG, FIELD_IS_MULTIPART_UPLOADED, FIELD_ENCRYPTION_STATUS]

# 创建存放清单文件的目标Bucket配置。
bucket_destination = InventoryBucketDestination(
    # 目标Bucket的用户accountId。
    account_id=account_id,
    # 目标Bucket的roleArn。
    role_arn=role_arn,
    # 目标Bucket的名称。
    bucket=dest_bucket_name,
    # 指定清单格式。
    inventory_format=INVENTORY_FORMAT_CSV,
    # 清单结果的存储路径前缀。
    prefix='destination-prefix',
    # 如果需要使用KMS加密清单,请参考如下设置。
    # sse_kms_encryption=InventoryServerSideEncryptionKMS("test-kms-id"),
    # 如果需要使用OSS服务端加密清单,请参考如下设置。
    # sse_oss_encryption=InventoryServerSideEncryptionOSS()
)

# 创建清单配置。
inventory_configuration = InventoryConfiguration(
    # 设置清单的配置id。
    inventory_id=inventory_id,
    # 清单配置是否启用的标识, true或false。
    is_enabled=True,
    # 设置清单的生成计划,以下示例为每天一次。其中,WEEKLY对应每周一次,DAILY对应每天一次。
    inventory_schedule=InventorySchedule(frequency=INVENTORY_FREQUENCY_DAILY),
    # 设置清单中包含的object的版本为当前版本。如果设置为INVENTORY_INCLUDED_OBJECT_VERSIONS_ALL则表示object的所有版本,在版本控制状态下生效。
    included_object_versions=INVENTORY_INCLUDED_OBJECT_VERSIONS_CURRENT,
    # 设置清单清筛选object的前缀。
    # inventory_filter=InventoryFilter(prefix="obj-prefix"),
    # 设置清单清筛选条件。假如筛选文件最后修改时间的起始时间戳为1637883649,
    inventory_filter=InventoryFilter(
        # 筛选规则的匹配前缀。
        "obj-prefix",
        # 筛选文件最后修改时间的起始时间戳,单位为秒。
        1637883649,
        # 筛选文件最后修改时间的终止时间戳,单位为秒。
        1638347592,
        # 筛选文件的最小大小,单位为B。
        1024,
        # 筛选文件的最大大小,单位为B。
        1048576,
        # 筛选文件的存储类型,支持指定多种存储类型。
        'Standard,IA'),
    # 设置清单中包含的object属性。
    optional_fields=optional_fields,    
    inventory_destination=InventoryDestination(bucket_destination=bucket_destination))

# 上传清单配置。
result = bucket.put_bucket_inventory_configuration(inventory_configuration)
print(result.status)
using Aliyun.OSS;
using Aliyun.OSS.Common;

// yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
var endpoint = "yourEndpoint";
// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
var accessKeyId = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_ID");
var accessKeySecret = Environment.GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET");
// 填写Bucket名称。
var bucketName = "examplebucket";
// 填写Bucket所有者授予的账户ID。
var accountId ="yourDestinationBucketAccountId";
// 填写具有读取源Bucket所有文件和向目标Bucket写入文件权限的角色名称。
var roleArn ="yourDestinationBucketRoleArn";
// 填写存放清单结果的Bucket名称。
var destBucketName ="yourDestinationBucketName";
// 创建OssClient实例。
var client = new OssClient(endpoint, accessKeyId, accessKeySecret);
try
{
    // 添加Bucket清单。
    var config = new InventoryConfiguration();
    // 设置清单规则名称。
    config.Id = "report1";
    // 清单配置是否启用的标识,取值为true或false。设置为true,表示启用清单配置。
    config.IsEnabled = true;
    // 设置清单筛选规则,指定筛选Object的前缀。
    config.Filter = new InventoryFilter("filterPrefix");
    // 创建清单的bucket目的地配置。
    config.Destination = new InventoryDestination();
    config.Destination.OSSBucketDestination = new InventoryOSSBucketDestination();
    // 设置清单格式。
    config.Destination.OSSBucketDestination.Format = InventoryFormat.CSV;
    // 存放清单结果的目标Bucket的用户accountId。
    config.Destination.OSSBucketDestination.AccountId = accountId;
    // 存放清单结果的目标Bucket的roleArn。
    config.Destination.OSSBucketDestination.RoleArn = roleArn;
    // 存放清单结果的目标Bucket名称。
    config.Destination.OSSBucketDestination.Bucket = destBucketName;
    // 设置存放清单结果的存储路径前缀。
    config.Destination.OSSBucketDestination.Prefix = "prefix1";
    
    // 设置清单的生成计划,以下示例为每周一次。其中,Weekly对应每周一次,Daily对应每天一次。
    config.Schedule = new InventorySchedule(InventoryFrequency.Daily);
    // 设置清单中包含的object的版本为当前版本。如果设置为InventoryIncludedObjectVersions.All则表示object的所有版本,在版本控制状态下生效。
    config.IncludedObjectVersions = InventoryIncludedObjectVersions.All;
    
    // 设置清单中包含的Object属性。
    config.OptionalFields.Add(InventoryOptionalField.Size);
    config.OptionalFields.Add(InventoryOptionalField.LastModifiedDate);
    config.OptionalFields.Add(InventoryOptionalField.StorageClass);
    config.OptionalFields.Add(InventoryOptionalField.IsMultipartUploaded);
    config.OptionalFields.Add(InventoryOptionalField.EncryptionStatus);
    config.OptionalFields.Add(InventoryOptionalField.ETag);
    var req = new SetBucketInventoryConfigurationRequest(bucketName, config);
    client.SetBucketInventoryConfiguration(req);
    Console.WriteLine("Set bucket:{0} InventoryConfiguration succeeded", bucketName);
}
catch (OssException ex)
{
    Console.WriteLine("Failed with error code: {0}; Error info: {1}. \nRequestID:{2}\tHostID:{3}",
        ex.ErrorCode, ex.Message, ex.RequestId, ex.HostId);
}
package main

import (
	"fmt"
	"github.com/aliyun/aliyun-oss-go-sdk/oss"
	"os"
)

func main() {
	/// 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	// 创建OSSClient实例。
	// yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
	client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}

	IsEnabled := true

	// 如果需要使用KMS加密清单,请参考如下设置。
	//var invEncryption oss.InvEncryption
	//var invSseOss oss.InvSseOss
	//var invSseKms oss.InvSseKms
	//invSseKms.KmsId = "<yourKmsId>" // 填写KMS密钥ID。
	//invEncryption.SseOss = &invSseOss // 使用OSS完全托管加密(SSE-OSS)方式进行加密。
	//invEncryption.SseKms = &invSseKms // 使用KMS托管密钥(SSE-KMS)的方式进行加密。

	invConfig := oss.InventoryConfiguration{
		// 由用户指定的清单名称,清单名称在当前Bucket下必须全局唯一。
		Id: "yourInventoryId2",
		// 启用清单配置。
		IsEnabled: &IsEnabled,

		// 设置清单筛选规则,指定筛选Object的前缀。
		Prefix: "yourFilterPrefix",
		OSSBucketDestination: oss.OSSBucketDestination{
			// 导出清单文件的文件格式。
			Format: "CSV",

			// 存储空间所有者授予的账户ID,例如109885487000****。
			AccountId: "yourGrantAccountId",

			// 存储空间所有者授予操作权限的角色名,比如acs:ram::109885487000****:role/ram-test。
			RoleArn: "yourRoleArn",

			// 存放导出的清单结果的Bucket名称。
			Bucket: "acs:oss:::" + "yourDestBucketName",

			// 存放清单结果的存储路径前缀。
			Prefix: "yourDestPrefix",

			// 如果清单需要加密,请参考以下代码。
			//Encryption:     &invEncryption,
		},

		// 清单文件导出的周期。
		Frequency: "Daily",

		// 是否在清单中包含Object的所有版本信息。
		IncludedObjectVersions: "All",

		OptionalFields: oss.OptionalFields{
			// 清单结果中包含的配置项。
			Field: []string{
				"Size", "LastModifiedDate", "ETag", "StorageClass", "IsMultipartUploaded", "EncryptionStatus",
			},
		},
	}
	// yourBucketName填写待配置清单规则的Bucket名称。
	err = client.SetBucketInventory("yourBucketName", invConfig)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
}
#include <alibabacloud/oss/OssClient.h>
using namespace AlibabaCloud::OSS;

int main(void)
{
    /* 初始化OSS账号信息。*/
            
    /* yourEndpoint填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。*/
    std::string Endpoint = "yourEndpoint";
    /* 填写Bucket名称,例如examplebucket。*/
    std::string BucketName = "examplebucket";

    /* 初始化网络等资源。*/
    InitializeSdk();

    ClientConfiguration conf;
    /* 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。*/
    auto credentialsProvider = std::make_shared<EnvironmentVariableCredentialsProvider>();
    OssClient client(Endpoint, credentialsProvider, conf);

    InventoryConfiguration inventoryConf;
    /* 指定清单规则名称,该名称在当前Bucket下必须全局唯一。*/
    inventoryConf.setId("inventoryId");

    /* 清单配置是否启用的标识,可选值为true或false。*/
    inventoryConf.setIsEnabled(true);

    /* (可选)清单筛选的前缀。指定前缀后,清单将筛选出符合前缀的Object。*/
    inventoryConf.setFilter(InventoryFilter("objectPrefix"));

    InventoryOSSBucketDestination dest;
    /* 导出清单文件的文件格式。*/
    dest.setFormat(InventoryFormat::CSV);
    /* 存储空间拥有者的账户UID。*/
    dest.setAccountId("10988548********");
    /* 指定角色名称,该角色需要拥有读取源存储空间所有文件以及向目标存储空间写入文件的权限,格式为acs:ram::uid:role/rolename。*/
    dest.setRoleArn("acs:ram::10988548********:role/inventory-test");
    /* 存放导出的清单文件的存储空间。*/
    dest.setBucket("yourDstBucketName");
    /* 清单文件的存储路径前缀。*/
    dest.setPrefix("yourPrefix");
    /* (可选)清单文件的加密方式, 可选SSEOSS或者SSEKMS方式加密。*/
    //dest.setEncryption(InventoryEncryption(InventorySSEOSS()));
    //dest.setEncryption(InventoryEncryption(InventorySSEKMS("yourKmskeyId")));
    inventoryConf.setDestination(dest);

    /* 清单文件导出的周期, 可选为Daily或者Weekly。*/
    inventoryConf.setSchedule(InventoryFrequency::Daily);

    /* 是否在清单中包含Object版本信息, 可选为All或者Current。*/
    inventoryConf.setIncludedObjectVersions(InventoryIncludedObjectVersions::All);

    /* (可选)设置清单结果中应包含的配置项, 请按需配置。*/
    InventoryOptionalFields field { 
        InventoryOptionalField::Size, InventoryOptionalField::LastModifiedDate, 
        InventoryOptionalField::ETag, InventoryOptionalField::StorageClass, 
        InventoryOptionalField::IsMultipartUploaded, InventoryOptionalField::EncryptionStatus
    };
    inventoryConf.setOptionalFields(field);

    /* 设置清单配置。*/
    auto outcome = client.SetBucketInventoryConfiguration(
        SetBucketInventoryConfigurationRequest(BucketName, inventoryConf));

    if (!outcome.isSuccess()) {
        /* 异常处理。*/
        std::cout << "Set Bucket Inventory fail" <<
        ",code:" << outcome.error().Code() <<
        ",message:" << outcome.error().Message() <<
        ",requestId:" << outcome.error().RequestId() << std::endl;
        return -1;
    }

    /* 释放网络等资源。*/
    ShutdownSdk();
    return 0;
}

使用命令行工具ossutil

关于使用ossutil配置Bucket清单的具体操作, 请参见inventory(清单)

使用REST API

如果您的程序自定义要求较高,您可以直接发起REST API请求。直接发起REST API请求需要手动编写代码计算签名。更多信息,请参见PutBucketInventory

清单文件

清单任务配置完成后,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/

该目录根据清单任务的规则名称生成。

YYYY-MM-DDTHH-MMZ/

该目录是标准的格林威治时间戳,表示开始扫描Bucket的时间,例如2020-05-17T16-00Z。该目录下包含了manifest.jsonmanifest.checksum文件。

data/

该目录下存放了包含源Bucket中的对象列表以及每个对象的元数据的清单文件,清单文件格式为使用GZIP压缩的CSV文件。

重要
  • 当导出的源Bucket中Object数量较多时,为方便用户下载和处理数据,程序会自动将清单文件切分成多个CSV压缩文件。CSV压缩文件按照uuid.csv.gzuuid-1.csv.gzuuid-2.csv.gz的顺序依次递增。您可以从manifest.json文件中获取CSV文件列表,然后按照以上顺序依次解压CSV文件并读取清单数据。

  • Object的单条记录信息仅出现在一个清单文件内,不会分布到不同的清单文件。

清单功能生成的具体文件说明如下:

manifest文件

manifest文件包含manifest.jsonmanifest.checksum,详细说明如下:

  • manifest.json:提供了有关清单的元数据和其他基本信息。

    {
        "creationTimestamp": "1642994594",
        "destinationBucket": "destbucket",
        "fileFormat": "CSV",
        "fileSchema": "Bucket, Key, VersionId, IsLatest, IsDeleteMarker, Size, StorageClass, LastModifiedDate, ETag, IsMultipartUploaded, EncryptionStatus, ObjectAcl, TaggingCount, ObjectType, Crc64",
        "files": [{
                "MD5checksum": "F77449179760C3B13F1E76110F07****",
                "key": "destbucket/inventory0124/data/a1574226-b5e5-40ee-91df-356845777c04.csv.gz",
                "size": 2046}],
        "sourceBucket": "srcbucket",
        "version": "2019-09-01"}

    各字段详细说明如下:

    字段名称

    说明

    creationTimestamp

    以纪元日期格式创建的时间戳,显示开始扫描源Bucket的时间。

    destinationBucket

    存放清单文件的目标Bucket。

    fileFormat

    清单文件的格式。

    fileSchema

    清单文件包含的字段,分为固定字段和可选字段。其中,固定字段的顺序是固定的,可选字段的排列顺序取决于您配置清单规则时清单内容字段的排列顺序(控制台配置时以字段的勾选先后顺序为准)。 因此,建议您以fileSchema中的字段顺序去解析csv.gz中的数据列,避免出现列和属性对应错误的情况。

    • 配置清单规则时如果对象版本选择了当前版本,则fileSchema中,先排列固定字段Bucket, Key,后续为可选字段。

    • 配置清单规则时如果对象版本选择了所有版本,则fileSchema中,先排列固定字段Bucket, Key, VersionId, IsLatest, IsDeleteMarker,后续为可选字段。

    files

    包含清单文件的MD5值、文件名完整路径及文件大小。

    sourceBucket

    配置清单规则的源Bucket。

    version

    清单版本号。

  • manifest.checksum:包含manifest.json文件的MD5值,例如8420A430CBD6B659A1C0DFC1C11A****

清单报告

清单报告存储在data/目录中,包含清单功能导出的文件信息。清单报告示例如下:

DCDD87B7-7499-4D22-B684-8B25B6F1C232.png

清单报告具体的字段顺序取决于您配置清单规则时的清单内容字段排列顺序。以上清单报告示例中,各字段按从左到右的顺序说明如下。

字段名称

说明

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值是基于一定计算规则生成的唯一值,但不是其内容的MD5值。

IsMultipartUploaded

Object是否通过分片上传生成。如果是,则该字段值为True,否则为False

EncryptionStatus

Object是否已加密。若Object已加密,则该字段值为True,否则为False

ObjectAcl

Object的读写权限。更多信息,请参见Object ACL

TaggingCount

Object的标签个数。

ObjectType

Object类型。更多信息,请参见Object类型

Crc64

Object的CRC64。

注意事项

配置数量

存储空间清单支持按天或按周导出清单文件。

Bucket内的文件数量

导出建议

<100亿

按需配置按天或按周导出

100亿~500亿

按周导出

≥500亿

  • 按前缀匹配分批导出

  • 通过提交工单提升导出Bucket文件数量的限制

流量带宽说明

为保障较快的清单文件列表导出速度,在清单文件列表导出到目标Bucket的过程中,可能会占用一定的Bucket与用户级别带宽。如果存放清单文件列表的目标Bucket与配置清单任务的源Bucket相同,且源Bucket存在流量较大带宽紧张的情况,建议新建一个目标Bucket用于存放清单结果文件。

异常说明

  • 如果源Bucket没有任何文件,或清单任务设置的前缀没有匹配到任何文件,则不会生成清单文件。

  • 导出清单文件的过程中,由于Object的创建、删除或覆盖等操作,可能会导致最终输出的清单列表中不一定包含所有的Object。最后修改时间早于manifest.json文件中createTimeStamp字段显示时间的Object会出现在清单文件中;最后修改时间晚于createTimeStamp字段显示时间的Object可能不会出现在清单文件中。建议您对清单列表中的Object进行操作之前,先使用HeadObject接口检查Object的属性。更多信息,请参见HeadObject

清理清单文件

在删除清单规则前,OSS会根据清单规则中的设置,以天或周为单位持续导出清单文件。为避免持续导出不必要的清单文件,您可以及时删除不再需要的清单规则。对于已导出且不再需要的存量清单文件,也可以及时清理。

常见问题

  • 本页导读 (1)
文档反馈