調用PutBucketInventory為Bucket配置清單規則 - Object Storage Service

調用PutBucketInventory介面用於為某個儲存空間（Bucket）配置清單（Inventory）規則。

注意事項

您可以通過清單擷取Bucket中Object的各類資訊，包括Object的數量、大小、儲存類型、加密狀態等。配置清單規則時，有如下注意事項：

配置清單規則前需產生一個RAM角色，該角色需要擁有讀取源Bucket所有檔案和向目標Bucket寫入檔案的許可權。首次使用清單功能時，建議您通過OSS控制台進行配置。清單規則配置完成後，您可以擷取擁有所有許可權的RAM角色。有關配置清單規則中RAM角色的許可權說明，請參見儲存空間清單。
單個Bucket最多隻能配置1000條清單規則。
配置清單的源Bucket與存放匯出的資訊清單檔所在的目標Bucket必須位於同一個Region。
如需使用增量清單功能，請聯絡支援人員申請，當前僅支援墨西哥地區。

許可權說明

阿里雲帳號預設擁有全部許可權。阿里雲帳號下的RAM使用者或RAM角色預設沒有任何許可權，需要阿里雲帳號或帳號管理員通過RAM Policy或Bucket Policy授予操作許可權。

API	Action	說明
PutBucketInventory	oss:PutBucketInventory	配置Bucket的清單（Inventory）規則。

請求文法

重要

要求標頭中的inventoryId為必選參數，取值與請求參數中的Id保持一致。
僅華北1（青島）、華北5（呼和浩特）、德國（法蘭克福）地區支援使用LastModifyBeginTimeStamp、LastModifyEndTimeStamp、LowerSizeBound、UpperSizeBound以及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>
     <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>TransistionTime</Field>        
        <Field>ETag</Field>
        <Field>StorageClass</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>EncryptionStatus</Field>
     </OptionalFields>
     <IncrementalInventory>
      <IsEnabled>true</IsEnabled>
      <Schedule>
        <Frequency>600</Frequency>
      </Schedule>
      <OptionalFields>
        <Field>SequenceNumber</Field>
        <Field>RecordType</Field>
        <Field>RecordTimestamp</Field>
        <Field>Requester</Field>
        <Field>RequestId</Field>
        <Field>SourceIp</Field>
        <Field>Size</Field>
        <Field>StorageClass</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ObjectType</Field>
        <Field>ObjectAcl</Field>
        <Field>Crc64</Field>
        <Field>EncryptionStatus</Field>
      </OptionalFields>
    </IncrementalInventory>
  </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	清單結果中包含的配置項。 Key：Bucket 中 Object 的名稱，採用URL編碼。 VersionId：Object的版本ID。僅當配置的清單規則為匯出所有版本時出現此欄位。如果配置清單規則的Bucket未開啟版本控制，則該欄位顯示為空白。如果配置清單規則的Bucket已開啟版本控制，則該欄位顯示為Object的VersionId。 IsDeleteMarker：Object版本是否為刪除標記。僅當配置的清單規則為匯出所有版本時出現此欄位。如果配置清單規則的Bucket未開啟版本控制，則該欄位預設顯示為false。如果配置清單規則的Bucket已開啟版本控制，且Object為刪除標記時，則該欄位顯示為true。如果Object不是刪除標記，則該欄位顯示為false。 Size：Object的大小。 StorageClass：Object的儲存類型。 TransitionTime：Object通過生命週期規則轉儲為冷歸檔或者深度冷Archive Storage類型的時間。 LastModifiedDate：Object的最後修改時間。 ETag：Object的ETag值，用於標識Object的內容。Object產生時會建立相應的ETag，用於標識一個Object的內容。通過PutObject介面建立的Object，ETag值是其內容的MD5值。通過其他方式建立的Object，ETag值是基於一定計算規則產生的唯一值，但不是其內容的MD5值。 IsMultipartUploaded：是否為通過分區上傳方式上傳的Object。 ObjectType：Object類型。 ObjectAcl：Object的讀寫權限。 Crc64：Object的CRC64。 EncryptionStatus：Object是否加密。 TaggingCount：標籤個數。
IncrementalInventory	容器	否	不涉及	增量清單的配置容器。
IsEnabled	布爾	是	true	是否開啟增量清單。取值： true：開啟 false：關閉當取值為 true 時，增量清單啟用，即使清單功能開關InventoryConfiguration/IsEnabled=false，增量清單仍會生效。父節點：IncrementalInventory
Schedule	容器	是	不涉及	增量清單匯出周期資訊的容器。父節點：IncrementalInventory
Frequency	正整數	是	600	增量清單的匯出頻率，單位為秒。系統當前以 600 秒為固定周期，每個周期自動建立一個目錄首碼，並產生對應的 manifest 檔案及該周期內產生的多份 CSV 檔案。暫不支援自訂頻率設定。父節點：Schedule
OptionalFields	容器	否	不涉及	差異清查檔案屬性的配置容器。父節點：IncrementalInventory
Field	字串	否	Size	增量清單中包含的配置項。父節點：OptionalFields SequenceNumber：序號，每條記錄的SequenceNumber唯一，同Bucket同Object下的記錄，可按照SequenceNumber排序，通常保證排序後的記錄遵循時間邏輯順序。 RecordType：事件類型：CREATE、UPDATE_METADATA、DELETE CREATE：所選首碼下發生的所有上傳方式，如 Put/Post/Append/MultipartUpload/Copy UPDATE_METADATA：所選首碼下所有中繼資料的更新都記錄在該類型中 DELETE：所選首碼下的檔案的所有刪除方式，如 DeleteObject/DeleteMultipleObjects、開啟多版本後產生 DeleteMarker、生命週期刪除。刪除有DeleteMarker和永久刪除，其中，永久刪除記錄僅保留 `Bucket`、`Key`、`SequenceNumber`、`RecordType`、`RecordTimestamp` 和 `VersionId` 核心欄位，其餘列均為空白（null）。 RecordTimestamp：時間戳記 ( 樣本： "2024-08-25 18:08:01.024")，採用格林威治時區，精度到毫秒。 Requester：要求者的阿里雲 ID 或者 Principal ID。 RequestId：請求的唯一標識。 SourceIp：要求者源 IP。 Key：Bucket 中 Object 的名稱，採用URL編碼。 VersionId：Object的版本ID。僅當配置的清單規則為匯出所有版本時出現此欄位。如果配置清單規則的Bucket未開啟版本控制，則該欄位顯示為空白。如果配置清單規則的Bucket已開啟版本控制，則該欄位顯示為Object的VersionId。 IsDeleteMarker：Object版本是否為刪除標記。僅當配置的清單規則為匯出所有版本時出現此欄位。如果配置清單規則的Bucket未開啟版本控制，則該欄位預設顯示為false。如果配置清單規則的Bucket已開啟版本控制，且Object為刪除標記時，則該欄位顯示為true。如果Object不是刪除標記，則該欄位顯示為false。 Size：Object的大小。 StorageClass：Object的儲存類型。 LastModifiedDate：Object的最後修改時間。 ETag：Object的ETag值，用於標識Object的內容。Object產生時會建立相應的ETag，用於標識一個Object的內容。通過PutObject介面建立的Object，ETag值是其內容的MD5值。通過其他方式建立的Object，ETag值是基於一定計算規則產生的唯一值，但不是其內容的MD5值。 IsMultipartUploaded：是否為通過分區上傳方式上傳的Object。 ObjectType：Object類型。 ObjectAcl：Object的讀寫權限。 Crc64：Object的CRC64。 EncryptionStatus：Object是否加密。

響應元素

此介面僅涉及公用回應標頭，例如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>TransistionTime</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

配置增量清單規則

請求樣本

  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>Report-1</Id>
    <IsEnabled>true</IsEnabled>
    <Filter>
      <Prefix>test</Prefix>
    </Filter>
    <Destination>
      <OSSBucketDestination>
        <Format>CSV</Format>
        <AccountId>12xxxxxx29</AccountId>
        <RoleArn>acs:ram::12xxxxxx29:role/bucket-inventory-role</RoleArn>
        <Bucket>acs:oss:::test-inc-bi-bj</Bucket>
        <Prefix>Report-1</Prefix>
      </OSSBucketDestination>
    </Destination>
    <Schedule>
      <Frequency>Weekly</Frequency>
    </Schedule>
    <IncludedObjectVersions>All</IncludedObjectVersions>
    <OptionalFields>
      <Field>Size</Field>
      <Field>LastModifiedDate</Field>
      <Field>ETag</Field>
      <Field>StorageClass</Field>
    </OptionalFields>
    <IncrementalInventory>
      <IsEnabled>true</IsEnabled>
      <Schedule>
        <Frequency>600</Frequency>
      </Schedule>
      <OptionalFields>
        <Field>SequenceNumber</Field>
        <Field>RecordType</Field>
        <Field>RecordTimestamp</Field>
        <Field>Requester</Field>
        <Field>RequestId</Field>
        <Field>SourceIp</Field>
        <Field>Size</Field>
        <Field>StorageClass</Field>
        <Field>LastModifiedDate</Field>
        <Field>ETag</Field>
        <Field>IsMultipartUploaded</Field>
        <Field>ObjectType</Field>
        <Field>ObjectAcl</Field>
        <Field>Crc64</Field>
        <Field>EncryptionStatus</Field>
      </OptionalFields>
    </IncrementalInventory>
  </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

SDK

此介面所對應的各語言SDK如下：

命令列工具ossutil

PutBucketInventory介面所對應的ossutil命令，請參見put-bucket-inventory。

錯誤碼

錯誤碼	HTTP狀態代碼	描述
InvalidArgument	400	傳入非法參數。
InventoryExceedLimit	400	超出清單配置規則的數量限制。
AccessDenied	403	發起PutBucketInventory請求時，沒有傳入使用者驗證資訊。使用者無操作許可權。
InventoryAlreadyExist	409	請求的清單規則已存在。