最后更新时间:2020-12-07 17:52:05

    简介

    本文档提供关于清单的 API 概览以及 SDK 示例代码。

    API 操作名 操作描述
    PUT Bucket inventory 设置清单任务 设置存储桶的清单任务
    GET Bucket inventory 查询清单任务 查询存储桶的清单任务
    DELETE Bucket inventory 删除清单任务 删除存储桶的清单任务

    设置清单任务

    功能说明

    PUT Bucket inventory 用于在存储桶中创建清单任务。

    方法原型

    public SetBucketInventoryConfigurationResult setBucketInventoryConfiguration(String bucketName, InventoryConfiguration inventoryConfiguration);
    public SetBucketInventoryConfigurationResult setBucketInventoryConfiguration(SetBucketInventoryConfigurationRequest setBucketInventoryConfigurationRequest);

    请求示例

    // bucket 名需包含 appid
    String bucketName = "examplebucket-1250000000";
    
    InventoryConfiguration inventoryConfiguration = new InventoryConfiguration();
    InventoryCosBucketDestination inventoryCosBucketDestination = new InventoryCosBucketDestination();
    // 设置清单的输出目标存储桶的格式和前缀等
    inventoryCosBucketDestination.setAccountId("2779643970");
    inventoryCosBucketDestination.setBucketArn("qcs::cos:ap-guangzhou::examplebucket-1250000000");
    inventoryCosBucketDestination.setEncryption(new ServerSideEncryptionCOS());
    inventoryCosBucketDestination.setFormat(InventoryFormat.CSV);
    inventoryCosBucketDestination.setPrefix("inventory-output");
    InventoryDestination inventoryDestination = new InventoryDestination();
    inventoryDestination.setCosBucketDestination(inventoryCosBucketDestination);
    inventoryConfiguration.setDestination(inventoryDestination);
    
    // 设置清单的调度周期,扫描前缀和 ID 等
    inventoryConfiguration.setEnabled(true);
    inventoryConfiguration.setId("1");
    InventorySchedule inventorySchedule = new InventorySchedule();
    inventorySchedule.setFrequency(InventoryFrequency.Daily);
    inventoryConfiguration.setSchedule(inventorySchedule);
    InventoryPrefixPredicate inventoryFilter = new InventoryPrefixPredicate("test/");
    inventoryConfiguration.setInventoryFilter(new InventoryFilter(inventoryFilter));
    inventoryConfiguration.setIncludedObjectVersions(InventoryIncludedObjectVersions.All);
    // 设置可选的输出字段
    List<String> optionalFields = new LinkedList<String>();
    optionalFields.add(InventoryOptionalField.Size.toString());
    optionalFields.add(InventoryOptionalField.LastModifiedDate.toString());
    inventoryConfiguration.setOptionalFields(optionalFields);
    SetBucketInventoryConfigurationRequest setBucketInventoryConfigurationRequest = new SetBucketInventoryConfigurationRequest();
    setBucketInventoryConfigurationRequest.setBucketName(bucketName);
    setBucketInventoryConfigurationRequest.setInventoryConfiguration(inventoryConfiguration);
    cosClient.setBucketInventoryConfiguration(setBucketInventoryConfigurationRequest);
    
    inventoryConfiguration.setId("2");
    inventorySchedule.setFrequency(InventoryFrequency.Weekly);
    cosClient.setBucketInventoryConfiguration(setBucketInventoryConfigurationRequest);

    参数说明

    参数名称 描述 类型
    setBucketInventoryConfigurationRequest 存储桶静态网站设置请求 SetBucketInventoryConfigurationRequest

    Request 成员说明 :

    Request 成员 设置方法 描述 类型
    bucketName 构造函数或 set 方法 设置清单任务的存储桶,格式为 BucketName-APPID ,详情请参见 命名规范 String
    inventoryConfiguration 构造函数或 set 方法 存储桶的清单配置 InventoryConfiguration

    InventoryConfiguration 成员说明:

    参数名称 描述 类型
    id 清单任务的名称,合法字符:a-z,A-Z,0-9,-,_,. String
    destination 清单结果导出后存放的存储桶信息 InventoryDestination
    isEnabled 清单是否启用的标识 Boolean
    inventoryFilter 筛选待分析对象。清单功能将分析符合 Filter 中设置的前缀的对象 InventoryFilter
    includedObjectVersions 是否在清单中包含对象版本
  • 如果设置为 All,清单中将会包含所有对象版本,并在清单中增加 VersionId,IsLatest,DeleteMarker 这几个字段
  • 如果设置为 Current,则清单中不包含对象版本信息
  • String
    optionalFields 清单结果中可选的字段名称 List
    schedule 配置清单任务周期 InventorySchedule

    InventoryDestination 成员说明:

    参数名称 描述 类型
    cosBucketDestination 清单结果导出后存放的存储桶信息 InventoryCosBucketDestination

    InventoryCosBucketDestination 成员说明:

    参数名称 描述 类型
    accountId 存储桶的所有者 ID String
    bucketArn 清单分析结果的存储桶名 String
    format 清单分析结果的文件形式,可选项为 CSV 格式 String
    prefix 清单分析结果的前缀 String
    encryption 为清单结果提供服务端加密的选项 InventoryEncryption

    InventoryFilter 成员说明:

    参数名称 描述 类型
    predicate 筛选待分析对象 InventoryFilterPredicate

    InventoryFilter 的一个实现类为 InventoryPrefixPredicate,成员说明如下:

    参数名称 描述 类型
    prefix 需要分析的对象的前缀 String

    InventorySchedule 成员说明:

    参数名称 描述 类型
    frequency 清单任务周期,可选项为按日或者按周,枚举值:Daily、Weekly String

    返回结果说明

    • 成功:无返回值。
    • 失败:发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

    错误码说明

    该请求可能会发生的一些常见的特殊错误如下:

    错误码 描述 状态码
    InvalidArgument 不合法的参数值 HTTP 400 Bad Request
    TooManyConfigurations 清单数量已经达到1000条的上限 HTTP 400 Bad Request
    AccessDenied 未授权的访问。您可能不具备访问该存储桶的权限 HTTP 403 Forbidden

    查询清单任务

    功能说明

    GET Bucket inventory 用于查询存储桶中用户的清单任务信息。

    方法原型

    public GetBucketInventoryConfigurationResult getBucketInventoryConfiguration(String bucketName, String id) throws CosClientException, CosServiceException;

    请求示例

    String bucketName = "examplebucket-1250000000";
    String id = "1";
    GetBucketInventoryConfigurationResult getBucketInventoryConfigurationResult = cosClient.getBucketInventoryConfiguration(bucketName, id);

    参数说明

    参数名称 描述 类型
    bucketName 查询清单任务的存储桶,格式为 BucketName-APPID ,详情请参见 命名规范 String
    id 清单任务的名称,合法字符:a-z,A-Z,0-9,-,_,. String

    返回结果说明

    • 成功:返回 GetBucketInventoryConfigurationResult,包含存储桶对应 id 清单的配置信息。
    • 失败:发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

    查询所有清单

    功能说明

    List Bucket Inventory Configurations 用于请求返回一个存储桶中的所有清单任务。

    方法原型

    public ListBucketInventoryConfigurationsResult listBucketInventoryConfigurations(ListBucketInventoryConfigurationsRequest listBucketInventoryConfigurationsRequest) throws CosClientException, CosServiceException;

    请求示例

    String bucketName = "examplebucket-1250000000";      
    ListBucketInventoryConfigurationsRequest listBucketInventoryConfigurationsRequest = new ListBucketInventoryConfigurationsRequest();
    listBucketInventoryConfigurationsRequest.setBucketName(bucketName);
    ListBucketInventoryConfigurationsResult listBucketInventoryConfigurationsResult = cosClient.listBucketInventoryConfigurations(listBucketInventoryConfigurationsRequest);

    参数说明

    参数名称 描述 类型
    bucketName 存放清单的目标存储桶,格式为 BucketName-APPID ,详情请参见 命名规范 String
    continuationToken 当 COS 响应体中 IsTruncated 为 true,且 NextContinuationToken 节点中存在参数值时,您可以将这个参数作为 continuation-token 参数值,以获取下一页的清单任务信息。 String

    返回结果说明

    • 成功:返回 ListBucketInventoryConfigurationsResult,包含存储桶对应 id 清单的配置信息。
    • 失败:发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理

    删除清单任务

    功能说明

    DELETE Bucket inventory 用于删除存储桶中指定的清单任务。

    方法原型

    public DeleteBucketInventoryConfigurationResult deleteBucketInventoryConfiguration(String bucketName, String id) throws CosClientException, CosServiceException;

    请求示例

    String bucketName = "examplebucket-1250000000";      
    String id = "1";
    cosClient.deleteBucketInventoryConfiguration(bucketName, id);

    参数说明

    参数名称 描述 类型
    bucketName 被删除清单任务的存储桶,格式为 BucketName-APPID ,详情请参见 命名规范 String
    id 清单任务的名称,合法字符:a-z,A-Z,0-9,-,_,. String

    返回结果说明

    • 成功:无返回值。
    • 失败:发生错误(如身份认证失败),抛出异常 CosClientException 或者 CosServiceException。详情请参见 异常处理