全部產品
Search
文件中心

Object Storage Service:PutBucketInventory

更新時間:Nov 13, 2024

調用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:Archive Storage

  • ColdArchive:冷Archive Storage

  • 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

請求的清單規則已存在。