製品アップデート情報
製品のお知らせ
リスト機能の概要
リストとは
リストとは、ユーザーによるバケット内のオブジェクト管理を支援する機能の一種であり、COSの同期的List API操作を計画的に代替することができます。Cloud Object Storage（COS）は、ユーザーのインベントリタスク設定に基づき、毎日、毎週、または毎月、ユーザーのバケット内の指定されたオブジェクトまたは同一オブジェクトプレフィックスを持つオブジェクトを定期的にスキャンし、インベントリレポートをCSV形式のファイルとしてユーザーが指定したバケットに出力します。また、1回限りのインベントリタスクを開始し、即座にインベントリレポートを生成することもサポートしています。ファイルには、保存されているオブジェクトとそのメタデータが一覧表示され、ユーザーの設定情報に基づいて必要なオブジェクト属性情報が記録されます。
リスト機能を使用すると、次の基本用途が実現できますが、用途はこれらのみに限定されません。
オブジェクトのコピーおよび暗号化状態を審査し、報告します。
業務のワークフローおよびビッグデータ作業を簡略化し、スピーディーに行えます。
注意：
ユーザーは1つのバケット内に複数のリストタスクを設定することができます。リストタスクは、オブジェクトの内容を直接読み取るのではなく、オブジェクトのメタデータなどのプロパティ情報のスキャンのみを行います。
現在、金融クラウドリージョンはサポートされていません。
サブアカウントを使用してインベントリを設定する場合、そのサブアカウントにルートアカウントから
cos:PutBucketInventory および cos:PutObject の操作権限を付与されていることを確認してください。リストのパラメータ
ユーザーがあるリストタスクを設定すると、COSは設定に応じて、ユーザーがバケット内で指定したオブジェクトを一定の時刻にスキャンし、リストレポートを出力します。リストレポートのファイル形式はCSVをサポートしています。現在、COSのリストレポートには次の情報を記録することができます。
リスト情報 | 説明 |
AppID | アカウントのID |
Bucket | リストタスクを実行するバケット名 |
fileFormat | ファイル形式 |
listObjectCount | |
listStorageSize | リストアップされたオブジェクトのサイズ |
filterObjectCount | フィルタリングされたオブジェクト数 |
filterStorageSize | フィルタリングされたオブジェクトのサイズ |
Key | バケット内のオブジェクトファイルの名称です。CSVファイル形式を使用する場合、オブジェクトファイル名にはURLエンコード形式が用いられているため、デコードして使用する必要があります |
VersionId | オブジェクトのバージョンIDです。バケット上でバージョン管理を有効にすると、COSはバケットに追加されたオブジェクトにバージョン番号を割り当てます。リストがオブジェクトの現在のバージョンのみを対象としている場合は、このフィールドは含まれません |
IsLatest | オブジェクトのバージョンが最新の場合はTrueに設定します。リストがオブジェクトの現在のバージョンのみを対象としている場合は、このフィールドは含まれません |
IsDeleteMarker | オブジェクトが削除マーカーの場合はTrueに設定します。リストがオブジェクトの現在のバージョンのみを対象としている場合は、このフィールドは含まれません |
Size | オブジェクトサイズ（バイトByte単位） |
LastModifiedDate | オブジェクトの直近の変更日（日付の遅い方に準じる） |
ETag | エンティティタグとはオブジェクトのハッシュです。ETagはオブジェクトの内容への変更のみを反映し、オブジェクトのメタデータへの変更は反映しません。ETagは、オブジェクトデータのMD5ダイジェストである場合も、そうではない場合もあります。どちらであるかは、オブジェクトの作成方法と暗号化方法によって決まります |
StorageClass | |
IsMultipartUploaded | |
Replicationstatus | オブジェクトのコピーにおいてソースファイルとレプリカファイルの状態をマークするために使用します。ソースファイルのマーカーはPENDING（コピー保留中）、COMPLETED（コピー完了）、FAILED（コピー失敗）、レプリカファイルのマーカーはREPLICA（コピー完了、レプリカファイル生成済み）となります。その他の情報に関しては、コピーアクションの説明をご参照ください |
Tag | オブジェクトのタグ |
Crc64 | オブジェクトのCRC64情報。 |
x-cos-meta-* | オブジェクトのカスタムメタデータ情報、例えば x-cos-meta-testheader。インベントリは対応するオブジェクトメタデータを出力し、オブジェクトに該当メタデータが含まれていない場合は空になります。 |
定期的なインベントリと1回限りのインベントリ
インベントリは、定期的なインベントリと1回限りのインベントリの2種類をサポートしています。
定期的なインベントリ：ユーザーがインベントリルールを設定した後、月次、週次、または日次でインベントリレポートを生成します。月次の場合は生成日（1〜28日で設定可能）を指定する必要があり、週次の場合はルールを設定した曜日と同じ曜日に生成が継続されます。
1回限りのインベントリ：1回限りのインベントリタスクを開始し、一度だけレポートを生成します。現在、COSは1回限りのインベントリタスクの記録照会をサポートしていないため、今後レポートを検索できるよう、タスク開始時のルールIDやインベントリの保存パスなどの情報を控えておくようにしてください。
リストの設定方法
リストを設定する前に、2つの概念をご理解いただく必要があります。
ソースバケット：リスト機能をアクティブ化したいバケットです。
リストにリストアップされるオブジェクトが含まれます。
リストの設定が含まれます。
ターゲットバケット：リストを保存するバケットです。
リストファイルが含まれます。
リストファイルの位置を記述したManifestファイルが含まれます。
リスト設定の手順は主に次のように分けられます。
ソースバケット内の分析対象のオブジェクト情報を指定する
どのオブジェクト情報を分析したいかをCOSに伝える必要があります。そのため、リスト機能を設定する際に、ソースバケットで次の情報を設定する必要があります。
選択するオブジェクトのバージョン：すべてのオブジェクトのバージョンをリストアップするか、または現在のバージョンのみをリストアップするかを選択します。すべてのオブジェクトのバージョンを選択した場合、COSは同名のオブジェクトのすべての過去バージョンをリストレポートに含めます。現在のバージョンのみを選択した場合、COSは最新バージョンのオブジェクトのみを記録します。
分析したいオブジェクトのプロパティの設定：オブジェクトのプロパティのうち、どの情報をリストレポートに記録させたいかをCOSに伝える必要があります。現在サポートしているオブジェクトのプロパティには、アカウントID、ソースバケット名、オブジェクトファイル名、オブジェクトバージョンID、最新バージョンかどうか、削除マーカーかどうか、オブジェクトサイズ、オブジェクトの最終変更日、ETag、オブジェクトのストレージクラス、地域間コピーマーカー、マルチパートアップロードファイルに該当するかどうかが含まれます。
リストレポートのストレージ情報の設定
どのような頻度でリストレポートをエクスポートするか、リストレポートをどのバケットに保存するかをCOSに伝えるとともに、リストレポートを暗号化するかどうかを決定する必要があります。設定する必要がある情報は次のとおりです。
リストのエクスポート頻度の選択：每日または毎週から選択できます。この設定によって、どの頻度でリスト機能を実行するかをCOSに伝えることができます。
リストの暗号化の選択：暗号化なしとSSE-COS暗号化から選択できます。SSE-COS暗号化を選択した場合、生成されるリストレポートは暗号化されます。
リストの出力位置の設定：リストレポートを保存したいバケットを設定する必要があります。
注意：
ターゲットバケットは必ずソースバケットと同一のリージョンになければなりません。これらは同一のバケットとすることもできます。
利用方法
コンソールでのインベントリ設定
定期的なインベントリの追加
1. COSコンソールにログインします。
2. 左側のナビゲーションメニューで、バケットリストをクリックします。
3. インベントリ機能を有効にしたいバケット（ソースバケット）をクリックして移動します。
4. 左側のナビゲーションメニューで、基本設定>インベントリ設定を選択し、インベントリを追加をクリックします。
5. 設定ページで、以下の設定が可能です。
5.1 基本情報
ルールステータス：現在のインベントリルールを有効にするかどうか。有効/無効を選択できます。
インベントリ名：インベントリ名を入力します。
ターゲットバケット：インベントリを保存するバケットです。初期設定ではソースバケットがターゲットバケットとして設定されており、ターゲットバケットはソースバケットと同一リージョンにある必要があります。
インベントリレポートプレフィックス（任意）：ターゲットバケットに保存するレポートのプレフィックスを入力します。共通の場所に保存されるインベントリファイルをグループ化できます。初期設定はデフォルト値です。
インベントリレポートの生成パス：インベントリレポートが生成されるパスです。
5.2 フィルタリング条件
ファイル範囲：インベントリオブジェクトの範囲を選択します。バケット全体、または同一プレフィックスを持つ一部のファイルを選択できます。例えば、バケット内のfolderパス配下にあるdocパスのすべてのファイルを選択する場合、ファイルプレフィックスとして
folder/docを指定します。オブジェクトのバージョン：インベントリにオブジェクトのすべてのバージョンを含めるか、現在のバージョンのみを含めるかを選択します。選択しない場合、デフォルトで現在のバージョンのみが保持されます。
タグによるフィルタリング（任意）：フィルタリングを実行して、同一のタグを持つオブジェクトをインベントリに含めます。入力しない場合、デフォルトではフィルタリングを行いません
時間によるフィルタリング（任意）：フィルタリングを実行して、最終更新日時が特定の日時以降、または特定の期間内であるオブジェクトをインベントリに含めます。設定しない場合、デフォルトではフィルタリングを行いません。
ストレージタイプによるフィルタリング（任意）：フィルタリングを実行して、指定されたストレージタイプのオブジェクトをインベントリに含めます。ストレージタイプの概要については、ストレージタイプの概要をご参照ください。設定しない場合、デフォルトではフィルタリングを行いません。
カスタムヘッダーの出力（任意）：インベントリレポートにオブジェクトのカスタムヘッダーを含めたい場合、出力したいカスタムヘッダーを入力できます。x-cos-meta-* ヘッダーのみ出力可能です。入力しない場合、デフォルトではカスタムヘッダーは出力されません。
インベントリ情報：インベントリレポートに含めるオブジェクトの対応する情報を選択します。オプションにはには、サイズ、ストレージタイプ、ETag、バケットレプリケーションステータス、チャンクアップロードステータス、最終更新日、タグ、CRC64があります。選択しない場合、デフォルトですべて選択されます。
説明：
ETag（エンティティタグ）はオブジェクトのハッシュ値であり、オブジェクトのメタデータの変更ではなく、コンテンツの変更のみを反映します。ETagは、オブジェクトの作成方法や暗号化方式によっては、必ずしもオブジェクトデータのMD5ダイジェストであるとは限りません。
生成されるインベントリの内容には、デフォルトでAppid、Bucket、Key、LastModifiedTimeフィールドが含まれます。
バケットでバージョニングが有効になっている場合、生成されるインベントリの内容にVersionId、IsLatest、IsDeleteMarkerフィールドが追加されます。
5.3 出力フォーマット
出力フォーマット：出力されるインベントリファイルは、GZIPで圧縮されたCSVファイルです
生成サイクル：毎日/毎週/毎月から生成サイクルを選択できます。デフォルトは毎日です。インベントリの具体的な生成時間はデータ量によって異なります。設定の説明は以下の通りです。
毎日：例えば、その日の午後3時にリストが追加された場合、リストファイルは通常、翌日の午前6時までに（予想時間）生成され、対象のストレージバケットに配信されます。データ量が多い場合、生成時間が遅れる可能性があります。週ごとまたは月ごとのリスト生成を選択することをお勧めします。
毎週：デフォルトで7日間を1サイクルとしてインベントリを生成します。例えば9月1日にインベントリを有効にした場合、最初のレポートは9月2日に生成され、その後は9月9日、9月16日、9月23日…と、7日間周期で生成されます。
毎月：毎月1日〜28日の任意の日を指定してインベントリを生成できます。生成ロジックは以下の通りです。
インベントリ作成日が指定日より前の場合、当月の指定日に生成されます。
例えば、9月8日にインベントリを有効にし、毎月25日に生成するよう指定した場合、最初のレポートは9月25日に生成され、その後は10月25日、11月25日、12月25日…と、月次周期で生成されます。
インベントリ作成日が指定日以降の場合、翌月の指定日に生成されます。
例えば、9月8日にインベントリを有効にし、毎月3日に生成するよう指定した場合、最初のレポートは10月3日に生成され、その後は11月3日、12月3日…と、月次周期で生成されます。
インベントリ暗号化：インベントリをサーバーサイドで暗号化するかどうかを選択します。以下から選択できます。
暗号化しない：インベントリを暗号化しません。これがデフォルトです。
SSE-COS：COSキーを使用したサーバー側の暗号化を使用してレポートを暗号化します。詳細については、オブジェクトストレージ開発者ガイドのSSE-COS暗号化をご参照ください。
アクセス許可：デフォルトでオフです。アクセス許可をオンにすると、次の操作に進むことができます。
5.4 情報確認
5.5 バケットのインベントリ設定情報をクリックします。変更が必要な場合は、前へをクリックしてください。
6. 設定情報に誤りがないことを確認後、確定をクリックします。その後、COSは、指定されたサイクルに基づいてインベントリファイルを自動的に生成し、設定したターゲットバケットに配信します。
説明：
7. 作成後、インベントリは指定されたパス、つまり5.1のインベントリレポート生成パスに配信されます。詳細については、インベントリレポートの保存パスをご参照ください。
即時インベントリの生成
説明：
作成済みのインベントリルールをすぐに実行したい場合は、即時インベントリの生成を選択できます。
1. COSコンソールにログインします。
2. 左側のナビゲーションメニューで、バケットリストをクリックし、作成済みのリストルールがあるバケット（ソースバケット）に移動します。
3. 左側の基本設定>インベントリ設定をクリックし、対応するインベントリルールを見つけて、右側のその他 > すぐに実行をクリックすると、迅速にインベントリを生成できます。
4. 作成後、即時インベントリは指定されたパス、つまり現在の定期インベントリールールで設定されているレポート生成パスに配信されます。
インベントリのプレビュー
1. COSコンソールにログインします。
2. 左側のナビゲーションメニューで、バケットリストをクリックし、作成済みのリストルールがあるバケット（ソースバケット）に移動します。
3. 左側の基本設定>インベントリ設定をクリックし、対応するインベントリルールを見つけ、その他 > リストをプレビューをクリックすると、インベントリ結果を簡単に確認できます。
4. インベントリのプレビューページには、現在のルールで生成されたすべてのインベントリ（定期的および即時）が表示されます。インベントリディレクトリへの移動や結果の確認がワンクリックで行え、日付やインベントリタイプによるフィルタリングもサポートしています。
注意：
インベントリタスク開始後、結果は段階的に更新されます。インベントリディレクトリ配下にmanifest.jsonファイルが生成された後、結果が完全に生成されます。
5. 日付を選択後、インベントリディレクトリ名の列で特定のディレクトリをクリックすると、そのディレクトリに直接移動し、生成されたインベントリ内容を確認できます。詳細については、リストレポートの保存パスをご参照ください。
6. インベントリ結果を直接確認したい場合は、操作列のインベントリ結果を表示をクリックすると、設定したフィルタリング条件に該当するオブジェクトの総数と合計サイズを確認できます。さらに詳細な情報については、ダウンロードをクリックしてファイルを展開し、確認してください。
7. ダウンロードしたCSVファイルに対応するフィールド名は、manifest.jsonファイルの「fileSchema」で確認できます。その他のフィールドの意味と説明については、インベントリパラメータをご参照ください。
APIによるリスト設定
APIを使用して、指定のバケットでリスト機能を有効化する場合は、次の手順をご参照ください。
1. COSロールを作成します。
2. COSロールに権限をバインドします。
3. リスト機能を有効化します。
1. COSロールの作成
COSロールを作成します。具体的なインターフェースの情報については、CreateRoleをご参照ください。
このうち、roleNameは必ずCOS_QcsRoleとします。
policyDocumentは次のとおりです。
{"version": "2.0","statement": [{"action": "name/sts:AssumeRole","effect": "allow","principal":{"service": "cos.cloud.tencent.com"}}]}
2. COSロールへの権限のバインド
ロール権限に権限をバインドします。具体的なインターフェースの情報については、AttachRolePolicyをご参照ください。
このうち、policyNameはQcloudCOSFullAccessとします。roleNameは手順1のCOS_QcsRoleとします。roleNameの作成時に返されたroleIDを使用することもできます。
3. リスト機能の有効化
インベントリファイルを保存するターゲットバケットとソースバケットは、同一リージョンにある必要があります。APIを呼び出してインベントリ機能を有効にする際の具体的なインターフェース情報は以下の通りです。
定期的なインベントリ
定期的なインベントリの設定：PUT Bucket inventory
定期的なインベントリルールの表示：GET Bucket Inventory
定期的なインベントリルールの削除：DELETE Bucket Inventory
定期的なインベントリルールの一覧表示：LIST Bucket Inventory
一回限りのインベントリタスクの開始： POST Bucket Inventory
インベントリレポートの保存パス
インベントリレポートおよび関連するManifestファイルは、ターゲットバケットに出力されます。そのうち、インベントリレポートは以下のパスに出力されます：
destination-prefix/appid/source-bucket/config-ID/Manifest関連ファイルは、ターゲットバケットの以下のパスに出力されます：
destination-prefix/appid/source-bucket/config-ID/YYYYMMDD/manifest.jsondestination-prefix/appid/source-bucket/config-ID/YYYYMMDD/manifest.checksum注意：
インベントリタスク開始後、結果は段階的に更新されます。インベントリディレクトリ配下にmanifest.jsonファイルが生成された後、結果が完全に生成されます。
パスの表す意味は次のとおりです。
destination-prefix：ユーザーがリストを設定する際に設定する「ターゲットプレフィックス」です。ターゲットバケット内のパブリックな位置にあるすべてのリストレポートのグループ化に用いることができます。
source-bucket：リストレポートに対応するソースバケット名です。このフォルダを追加するのは、複数のソースバケットがそれぞれのリストレポートを同一のターゲットバケットに送信する際に競合が発生しないようにするためです。
config-ID：ユーザーがリストを設定する際に設定する「リスト名」です。同一のソースバケットに複数のリストレポートを設定し、それらを同一のターゲットバケットに送信する際、config-IDを使用して異なるリストレポートを区別することができます。
YYYYMMDD：タイムスタンプです。リストレポートの生成時にバケットスキャンを開始した時間および日付が含まれます。
manifest.json：Manifestファイルを指します。
manifest.checksum：manifest.jsonファイル内容のMD5です。
このうち、Manifest関連ファイルにはmanifest.jsonとmanifest.checksumの2つのファイルが含まれます。
説明：
Manifestファイルに関する説明は次のとおりです。
manifest.jsonとmanifest.checksumはどちらもManifestファイルです。manifest.jsonはリストレポートの位置を記述するもので、manifest.checksumはmanifest.jsonのファイル内容のMD5です。新しいリストレポートが発行される際、それには毎回新しいManifestファイルのセットが付属します。
manifest.jsonに含まれる各Manifestにはすべて、リストに関連するメタデータおよびその他の基本情報が記載されています。これらの情報には次が含まれます。
ソースバケット名。
ターゲットバケット名。
リストのバージョン。
タイムスタンプ。リストレポートの生成時にバケットのスキャンを開始した日付および時間が含まれます。
リストファイルの形式とアーキテクチャ。
ターゲットバケット内のリストレポートのオブジェクトキー、サイズ、md5Checksum。
CSV形式のリストのmanifest.jsonファイルにおけるManifestの例は次のとおりです。
{"sourceAppid": "1250000000","sourceBucket": "example-source-bucket","destinationAppid": "1250000000","destinationBucket": "example-inventory-destination-bucket","fileFormat": "CSV","listObjectCount": "13","listStorageSize": "7212835","filterObjectCount": "13","filterStorageSize": "7212835","fileSchema": "Appid, Bucket, Key, Size, LastModifiedDate, ETag, StorageClass, IsMultipartUploaded, ReplicationStatus","files": [{"key": "cos_bucket_inventory/1250000000/examplebucket/inventory01/04d73d9debc73d9f0bf85af461abde6c.csv.gz","size": "502","md5Checksum": "7d40288a09c25b302ad6cb5fced54f35"}]}
リストの整合性
COSのリストレポートでは、新たなオブジェクトと上書きしたPUTの最終的な整合性、ならびにDELETEの最終的な整合性が示されます。このため、リストレポートには最近追加または削除されたオブジェクトが含まれない可能性があります。例えば、COSがユーザーの設定したリストタスクのプロセスを実行中に、ユーザーがオブジェクトのアップロードまたは削除操作を実行した場合、これらの操作はリストレポートに反映されない可能性があります。
オブジェクトの操作を実行する前にオブジェクトの状態を検証したい場合は、HEAD ObjectAPIを使用してオブジェクトメタデータを検索するか、またはCOSコンソールでオブジェクトのプロパティをチェックすることをお勧めします。
フィードバック