文档

PutBucketInventory

更新时间:

调用PutBucketInventory接口用于为某个存储空间(Bucket)配置清单(Inventory)规则。

注意事项

您可以通过清单获取Bucket中Object的各类信息,包括Object的数量、大小、存储类型、加密状态等。配置清单规则时,有如下注意事项:

  • 只有Bucket的拥有者以及被授予PutBucketInventory权限的用户才能发起配置清单规则的请求。

  • 配置清单规则前需生成一个RAM角色,该角色需要拥有读取源Bucket所有文件和向目标Bucket写入文件的权限。首次使用清单功能时,建议您通过OSS控制台进行配置。清单规则配置完成后,您可以获取拥有所有权限的RAM角色。有关配置清单规则中RAM角色的权限说明,请参见存储空间清单

  • 单个Bucket最多只能配置1000条清单规则。

  • 配置清单的源Bucket与存放导出的清单文件所在的目标Bucket必须位于同一个Region。

请求语法

重要
  • 请求头中的inventoryId为必选参数,取值与请求参数中的Id保持一致。

  • 仅华北1(青岛)、华北5(呼和浩特)、德国(法兰克福)以及澳大利亚(悉尼)地域支持使用LastModifyBeginTimeStampLastModifyEndTimeStampLowerSizeBoundUpperSizeBound以及StorageClass选项。

  PUT /?inventory&inventoryId=report1 HTTP/1.1
  Host: BucketName.oss-cn-hangzhou.aliyuncs.com
  Date: Mon, 31 Oct 2016 12:00:00 GMT
  Authorization: authorization string
  Content-Length: length

  <?xml version="1.0" encoding="UTF-8"?>
    <InventoryConfiguration>
     <Id>report1</Id>
     <IsEnabled>true</IsEnabled>
     <Filter>
           <Prefix>filterPrefix/</Prefix>
           <LastModifyBeginTimeStamp>1637883649</LastModifyBeginTimeStamp>
           <LastModifyEndTimeStamp>1638347592</LastModifyEndTimeStamp>
           <LowerSizeBound>1024</LowerSizeBound>
           <UpperSizeBound>1048576</UpperSizeBound>
           <StorageClass>Standard,IA</StorageClass>
     </Filter>
     <Destination>
        <OSSBucketDestination>
           <Format>CSV</Format>
           <AccountId>1000000000000000</AccountId>
           <RoleArn>acs:ram::1000000000000000:role/AliyunOSSRole</RoleArn>
           <Bucket>acs:oss:::destination-bucket</Bucket>
           <Prefix>prefix1</Prefix>
           <Encryption>
              <SSE-KMS>
                 <KeyId>keyId</KeyId>
              </SSE-KMS>
           </Encryption>
        </OSSBucketDestination>
     </Destination>
     <Schedule>
        <Frequency>Daily</Frequency>
     </Schedule>
     <IncludedObjectVersions>All</IncludedObjectVersions>
     <OptionalFields>
        <Field>Size</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>EncryptionStatus</Field>
     </OptionalFields>
  </InventoryConfiguration>

请求元素

名称

类型

是否必选

示例值

描述

Id

字符串

report1

自定义清单名称,要求如下:

  • 清单名称在当前Bucket下必须全局唯一。

  • 清单名称长度不能超过192个字符。

IsEnabled

布尔

true

清单功能是否启用的标识。

有效值:

  • true:启用清单功能。

  • false:不启用清单功能。

Filter

容器

不涉及

清单筛选的前缀。指定前缀后,清单将筛选出符合前缀设置的对象。

Prefix

字符串

Pics/

筛选规则的匹配前缀。

父节点:Filter

LastModifyBeginTimeStamp

字符串

1637883649

筛选文件最后修改时间的起始时间戳,单位为秒。

取值范围:[1262275200, 253402271999]

LastModifyEndTimeStamp

字符串

1638347592

筛选文件最后修改时间的终止时间戳,单位为秒。

取值范围:[1262275200, 253402271999]

LowerSizeBound

字符串

1024

筛选文件的最小大小,单位为B。

取值范围:大于等于0 B,小于等于48.8 TB。

UpperSizeBound

字符串

1048576

筛选文件的最大大小,单位为B。

取值范围:大于0 B,小于等于48.8 TB。

StorageClass

字符串

Standard,IA

筛选文件的存储类型,支持指定多种存储类型。

可选值:

  • Standard:标准存储

  • IA:低频访问

  • Archive:归档存储

  • ColdArchive:冷归档存储

  • All(默认值):所有存储类型

Destination

容器

不涉及

存放清单结果。

OSSBucketDestination

容器

不涉及

清单结果导出后存放的Bucket信息。

父节点:Destination

Format

字符串

CSV

清单文件的文件格式。 清单文件导出后的格式为使用GZIP压缩的CSV文件。

有效值:CSV

父节点:OSSBucketDestination

AccountId

字符串

100000000000000

Bucket所有者授予的账户ID。

父节点:OSSBucketDestination

RoleArn

字符串

acs:ram::100000000000000:role/AliyunOSSRole

具有读取源Bucket所有文件和向目标Bucket写入文件权限的角色名,格式为acs:ram::uid:role/rolename

父节点:OSSBucketDestination

Bucket

字符串

acs:oss:::bucket_0001

存放导出的清单文件的Bucket。

父节点:OSSBucketDestination

Prefix

字符串

prefix1/

清单文件的存储路径前缀。

父节点:OSSBucketDestination

Encryption

容器

不涉及

清单文件的加密方式。

有效值:

  • SSE-OSS:使用OSS完全托管密钥进行加解密。

  • SSE-KMS:使用KMS托管的默认CMK(Customer Master Key)或指定CMK进行加解密。

父节点:OSSBucketDestination

有关服务器端加密的更多信息,请参见服务器端加密

SSE-OSS

容器

不涉及

保存SSE-OSS加密方式的容器。

父节点:Encryption

SSE-KMS

容器

不涉及

保存SSE-KMS加密密钥的容器。

父节点:Encryption

KeyId

字符串

keyId

KMS密钥ID。

父节点:SSE-KMS

Schedule

容器

不涉及

存放清单导出周期信息的容器。

Frequency

字符串

Daily

清单文件导出的周期。

有效值:

  • Daily:按天导出清单文件。

  • Weekly:按周导出清单文件。

父节点:Schedule

IncludedObjectVersions

字符串

All

是否在清单中包含Object版本信息。

有效值:

  • All:导出Object的所有版本信息。

  • Current:导出Object的当前版本信息。

OptionalFields

容器

不涉及

设置清单结果中包含的配置项。

Field

字符串

Size

清单结果中包含的配置项。

  • Size:Object的大小。

  • LastModifiedDate:Object的最后修改时间。

  • ETag:Object的ETag值,用于标识Object的内容。

  • StorageClass:Object的存储类型。

  • IsMultipartUploaded:是否为通过分片上传方式上传的Object。

  • EncryptionStatus:Object是否加密。

  • ObjectAcl:Object的读写权限。

  • TaggingCount:标签个数。

  • ObjectType:Object类型。

  • Crc64:Object的CRC64。

响应元素

此接口仅涉及公共响应头,例如Content-Length、Date等。更多信息,请参见公共响应头(Common Response Headers)

示例

  • 请求示例

      PUT /?inventory&inventoryId=report1 HTTP/1.1
      Host: oss-example.oss-cn-hangzhou.aliyuncs.com
      Date: Mon, 31 Oct 2016 12:00:00 GMT
      Authorization: authorization string
      Content-Length: length
    
      <?xml version="1.0" encoding="UTF-8"?>
      <InventoryConfiguration>
         <Id>report1</Id>
         <IsEnabled>true</IsEnabled>
         <Filter>
             <Prefix>Pics/</Prefix>
             <LastModifyBeginTimeStamp>1637883649</LastModifyBeginTimeStamp>
             <LastModifyEndTimeStamp>1638347592</LastModifyEndTimeStamp>
             <LowerSizeBound>1024</LowerSizeBound>
             <UpperSizeBound>1048576</UpperSizeBound>
             <StorageClass>Standard,IA</StorageClass>
         </Filter>
         <Destination>
            <OSSBucketDestination>
              <Format>CSV</Format>
              <AccountId>100000000000000</AccountId>
              <RoleArn>acs:ram::100000000000000:role/AliyunOSSRole</RoleArn>
              <Bucket>acs:oss:::destbucket</Bucket>
              <Prefix>prefix1/</Prefix>
              <Encryption>
                 <SSE-KMS>
                    <KeyId>keyId</KeyId>
                 </SSE-KMS>
               </Encryption>
            </OSSBucketDestination>
         </Destination>
         <Schedule>
            <Frequency>Daily</Frequency>
         </Schedule>
         <IncludedObjectVersions>All</IncludedObjectVersions>
         <OptionalFields>
            <Field>Size</Field>
            <Field>LastModifiedDate</Field>
            <Field>ETag</Field>
            <Field>StorageClass</Field>
            <Field>IsMultipartUploaded</Field>
            <Field>EncryptionStatus</Field>
         </OptionalFields>
      </InventoryConfiguration>
  • 返回示例

      HTTP/1.1 200 OK
      x-oss-request-id: 56594298207FB3044385****
      Date: Mon, 31 Oct 2016 12:00:00 GMT
      Content-Length: 0
      Server: AliyunOSS

错误码

错误码

HTTP状态码

描述

InvalidArgument

400

传入非法参数。

InventoryExceedLimit

400

超出清单配置规则的数量限制。

AccessDenied

403

  • 发起PutBucketInventory请求时,没有传入用户验证信息。

  • 用户无操作权限。

InventoryAlreadyExist

409

请求的清单规则已存在。

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