バケットのインベントリルールを設定するには、putbucketinventory を呼び出します - Object Storage Service

PutBucketInventory API を呼び出して、バケットのインベントリルールを設定できます。

注意事項

インベントリは、バケット内のオブジェクトに関する情報を提供します（例：オブジェクト数、サイズ、ストレージクラス、暗号化ステータスなど）。インベントリルールを設定する際は、以下の点にご注意ください。

バケットのインベントリを設定する前に、RAM ロールを作成する必要があります。この RAM ロールには、ソースバケットからすべてのオブジェクトを読み取る権限および宛先バケットへオブジェクトを書き込む権限が必要です。初めてバケットインベントリ機能を利用する場合は、OSS コンソールでインベントリを設定することを推奨します。設定後に、OSS リソースに対するすべての操作を実行できる権限を持つ RAM ロールを取得できます。インベントリルール設定時に必要な RAM ロールの権限については、「バケットインベントリ」をご参照ください。
1 つのバケットでは、最大 1,000 個のインベントリルールを設定できます。
インベントリのソースバケットと、エクスポートされたインベントリファイルの宛先バケットは、同一リージョン内に存在する必要があります。
増分インベントリ機能を利用するには、テクニカルサポートへお問い合わせのうえ、申請してください。この機能は現在、メキシコ (メキシコシティ) リージョンでのみご利用いただけます。

権限

デフォルトでは、Alibaba Cloud アカウントはすべての権限を持ちます。一方、Alibaba Cloud アカウント配下の RAM ユーザーおよび RAM ロールは、デフォルトで権限を持ちません。Alibaba Cloud アカウントまたはアカウント管理者が、RAM ポリシーまたはバケットポリシーを使用して操作権限を付与する必要があります。

API	Action	説明
PutBucketInventory	oss:PutBucketInventory	バケットのインベントリを設定します。

リクエスト構文

重要

リクエストヘッダー内の inventoryId パラメーターは必須です。その値は、リクエストパラメーター Id の値と一致している必要があります。
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	カスタムインベントリ名です。以下の要件を満たす必要があります。インベントリ名は、対象のバケット内でグローバルに一意である必要があります。インベントリ名は 192 文字を超えてはいけません。
IsEnabled	ブール値	はい	true	インベントリ機能が有効かどうかを示します。有効値： true：インベントリ機能を有効化します。 false：インベントリ機能を無効化します。
Filter	コンテナー	いいえ	N/A	インベントリでフィルタリングするオブジェクトのプレフィックスです。プレフィックスを指定すると、該当するプレフィックスに一致するオブジェクトがフィルタリングされます。
Prefix	文字列	いいえ	Pics/	フィルタリングルールのプレフィックスです。親ノード：Filter
LastModifyBeginTimeStamp	文字列	いいえ	1637883649	フィルタリング対象ファイルの最終更新時刻の開始 UNIX タイムスタンプ（秒単位）です。有効範囲：[1262275200, 253402271999]
LastModifyEndTimeStamp	文字列	いいえ	1638347592	フィルタリング対象ファイルの最終更新時刻の終了 UNIX タイムスタンプ（秒単位）です。有効範囲：[1262275200, 253402271999]
LowerSizeBound	文字列	いいえ	1024	フィルタリング対象ファイルの最小サイズ（バイト単位）です。有効範囲：0 B ～ 48.8 TB。
UpperSizeBound	文字列	いいえ	1048576	フィルタリング対象ファイルの最大サイズ（バイト単位）です。有効範囲：0 B より大きい値～ 48.8 TB。
StorageClass	文字列	いいえ	Standard,IA	フィルタリング対象ファイルのストレージクラスです。複数のストレージクラスを指定できます。有効値： Standard：標準ストレージ IA：低頻度アクセス Archive：アーカイブストレージ ColdArchive：コールドアーカイブ All（デフォルト）：すべてのストレージクラス
Destination	コンテナー	はい	N/A	チェックリスト結果を格納します。
OSSBucketDestination	コンテナー	はい	N/A	エクスポートされたインベントリ結果を格納するバケットに関する情報です。親ノード：Destination
Format	文字列	はい	CSV	インベントリファイルのファイル形式です。エクスポートされたインベントリファイルは、GZIP で圧縮された CSV ファイルです。有効値：CSV 親ノード：OSSBucketDestination
AccountId	文字列	はい	100000000000000	バケット所有者によって付与された AccountId です。親ノード：OSSBucketDestination
RoleArn	文字列	はい	acs:ram::100000000000000:role/AliyunOSSRole	ソースバケットからすべてのファイルを読み取り、宛先バケットへファイルを書き込む権限を持つロールの名前です。形式： `acs:ram::uid:role/rolename`。親ノード：OSSBucketDestination
Bucket	文字列	はい	acs:oss:::bucket_0001	エクスポートされたインベントリファイルを格納するバケットです。親ノード：OSSBucketDestination
Prefix	文字列	いいえ	prefix1/	インベントリファイルの保存パスのプレフィックスです。親ノード：OSSBucketDestination
Encryption	コンテナー	いいえ	N/A	インベントリファイルの暗号化方式です。有効値： SSE-OSS：OSS 管理のキーを使用した暗号化および復号。 SSE-KMS：KMS が管理するデフォルトのカスタマーマスターキー（CMK）または指定した CMK を使用した暗号化および復号。親ノード：OSSBucketDestination 詳細については、「サーバー側暗号化」をご参照ください。
SSE-OSS	コンテナー	いいえ	N/A	SSE-OSS 暗号化方式のコンテナーです。親ノード：Encryption
SSE-KMS	コンテナー	いいえ	N/A	SSE-KMS 暗号化キーのコンテナーです。親ノード：Encryption
KeyId	文字列	いいえ	keyId	KMS キー ID です。親ノード：SSE-KMS
Schedule	コンテナー	はい	N/A	インベントリエクスポート頻度情報を格納するコンテナーです。
Frequency	文字列	はい	Daily	インベントリファイルのエクスポート頻度です。有効値： Daily：毎日インベントリファイルをエクスポートします。 Weekly：毎週インベントリファイルをエクスポートします。親ノード：Schedule
IncludedObjectVersions	文字列	はい	All	インベントリにオブジェクトのバージョン情報が含まれるかどうかを指定します。有効値： All：すべてのオブジェクトバージョン情報をエクスポートします。 Current：現在のオブジェクトバージョン情報のみをエクスポートします。
OptionalFields	コンテナー	いいえ	N/A	インベントリ結果に含める項目を設定します。
Field	文字列	いいえ	Size	インベントリ結果に含める設定項目です。 Key：バケット内のオブジェクト名（URL エンコード済み）。 VersionId：オブジェクトのバージョン ID。このフィールドは、インベントリルールが「すべてのバージョン」をエクスポートするように設定されている場合にのみ表示されます。インベントリルールを設定するバケットでバージョン管理が有効になっていない場合、このフィールドは空になります。インベントリルールを設定するバケットでバージョン管理が有効になっている場合、このフィールドにはオブジェクトの VersionId が表示されます。 IsDeleteMarker：オブジェクトバージョンが削除マーカーであるかどうかを示します。このフィールドは、インベントリルールが「すべてのバージョン」をエクスポートするように設定されている場合にのみ表示されます。インベントリルールを設定するバケットでバージョン管理が有効になっていない場合、このフィールドのデフォルト値は false です。インベントリルールを設定するバケットでバージョン管理が有効になっており、オブジェクトが削除マーカーである場合、このフィールドには true が表示されます。オブジェクトが削除マーカーでない場合は、false が表示されます。 Size：オブジェクトのサイズ。 StorageClass：オブジェクトのストレージクラス。 TransitionTime：ライフサイクルルールにより、オブジェクトのストレージクラスがコールドアーカイブまたはディープコールドアーカイブに変更された時刻。 LastModifiedDate：オブジェクトの最終更新時刻。 ETag：オブジェクトの内容を識別する ETag 値。ETag は、オブジェクト生成時にその内容を識別するために作成されます。 PutObject API を使用して作成されたオブジェクトの場合、ETag 値はそのコンテンツの MD5 ハッシュです。他の方法で作成されたオブジェクトの場合、ETag 値は特定の計算規則に基づいて生成された一意の値ですが、コンテンツの MD5 ハッシュではありません。 IsMultipartUploaded：オブジェクトがフラグメントアップロード（マルチパートアップロード）でアップロードされたかどうかを示します。 ObjectType：オブジェクトタイプ。 ObjectAcl：オブジェクトのアクセス制御リスト（ACL）。 Crc64：オブジェクトの CRC-64。 EncryptionStatus：オブジェクトが暗号化されているかどうかを示します。 TaggingCount：タグの数。
IncrementalInventory	コンテナー	いいえ	N/A	増分インベントリの設定コンテナーです。
IsEnabled	ブール値	はい	true	増分インベントリを有効にするかどうかを指定します。有効値： true：有効化します。 false：無効化します。 InventoryConfiguration/IsEnabled が false であっても、true に設定すると、増分インベントリが有効になります。親ノード：IncrementalInventory
Schedule	コンテナー	はい	N/A	増分インベントリのエクスポート頻度情報を格納するコンテナーです。親ノード：IncrementalInventory
Frequency	正の整数	はい	600	増分インベントリのエクスポート頻度（秒単位）です。システムでは現在、固定期間として 600 秒が使用されています。各期間ごとに、自動的にディレクトリプレフィックスが作成され、その期間に対応するマニフェストファイルおよび複数の CSV ファイルが生成されます。カスタムの頻度設定はサポートされていません。親ノード：Schedule
OptionalFields	コンテナー	いいえ	N/A	増分インベントリファイルのプロパティを設定するコンテナーです。親ノード：IncrementalInventory
Field	文字列	いいえ	Size	増分インベントリに含める設定項目です。親ノード：OptionalFields SequenceNumber：シリアル番号。各レコードには一意の SequenceNumber があります。同じバケットおよびオブジェクトの下にあるレコードは、SequenceNumber で並べ替えることができ、通常は時系列順を保証します。 RecordType：イベントタイプ（CREATE、UPDATE_METADATA、DELETE）。 CREATE：選択したプレフィックス下で発生するすべてのアップロード方法（Put／Post／Append／マルチパートアップロード／Copy など）。 UPDATE_METADATA：選択したプレフィックス下で行われるすべてのメタデータ更新が、このタイプで記録されます。 DELETE：選択したプレフィックス下のファイルに対するすべての削除方法（DeleteObject／DeleteMultipleObjects、バージョン管理有効化後の DeleteMarker 生成、ライフサイクルによる削除など）。削除には DeleteMarker および完全削除が含まれます。完全削除レコードでは、`Bucket`、`Key`、`SequenceNumber`、`RecordType`、`RecordTimestamp`、`VersionId` の 6 つのコアフィールドのみが保持され、それ以外のカラムは null になります。 RecordTimestamp：タイムスタンプ（例："2024-08-25 18:08:01.024"）、GMT（グリニッジ標準時）でミリ秒精度。 Requester：リクエスターの Alibaba Cloud ID または Principal ID。 RequestId：リクエストの一意の ID。 SourceIp：リクエスターのソース IP アドレス。 Key：バケット内のオブジェクト名（URL エンコード済み）。 VersionId：オブジェクトのバージョン ID。このフィールドは、インベントリルールが「すべてのバージョン」をエクスポートするように設定されている場合にのみ表示されます。インベントリルールを設定するバケットでバージョン管理が有効になっていない場合、このフィールドは空になります。インベントリルールを設定するバケットでバージョン管理が有効になっている場合、このフィールドにはオブジェクトの VersionId が表示されます。 IsDeleteMarker：オブジェクトバージョンが削除マーカーであるかどうかを示します。このフィールドは、インベントリルールが「すべてのバージョン」をエクスポートするように設定されている場合にのみ表示されます。インベントリルールを設定するバケットでバージョン管理が有効になっていない場合、このフィールドのデフォルト値は false です。インベントリルールを設定するバケットでバージョン管理が有効になっており、オブジェクトが削除マーカーである場合、このフィールドには true が表示されます。オブジェクトが削除マーカーでない場合は、false が表示されます。 Size：オブジェクトのサイズ。 StorageClass：オブジェクトのストレージクラス。 LastModifiedDate：オブジェクトの最終更新時刻。 ETag：オブジェクトの内容を識別する ETag 値。ETag は、オブジェクト生成時にその内容を識別するために作成されます。 PutObject API を使用して作成されたオブジェクトの場合、ETag 値はそのコンテンツの MD5 ハッシュです。他の方法で作成されたオブジェクトの場合、ETag 値は特定の計算規則に基づいて生成された一意の値ですが、コンテンツの MD5 ハッシュではありません。 IsMultipartUploaded：オブジェクトがフラグメントアップロード（マルチパートアップロード）でアップロードされたかどうかを示します。 ObjectType：オブジェクトタイプ。 ObjectAcl：オブジェクトのアクセス制御リスト（ACL）。 Crc64：オブジェクトの CRC-64。 EncryptionStatus：オブジェクトが暗号化されているかどうかを示します。

レスポンス要素

この操作は、Content-Length や Date などの共通レスポンスヘッダーのみを返します。詳細については、「共通レスポンスヘッダー」をご参照ください。

サンプル

インベントリルールの設定

リクエストのサンプル

  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

この API は、以下の SDK で利用可能です。

ossutil

この操作に対応する ossutil コマンドの詳細については、「put-bucket-inventory」をご参照ください。

エラーコード

エラーコード	HTTP ステータスコード	説明
InvalidArgument	400	無効なパラメーターが渡されました。
InventoryExceedLimit	400	インベントリ構成ルールの数が上限を超えています。
AccessDenied	403	PutBucketInventory リクエストを開始する際に、ユーザー認証情報が提供されていません。ユーザーに操作権限がありません。
InventoryAlreadyExist	409	要求されたインベントリルールは既に存在します。