tencent cloud

リストとは

リストとは、ユーザーによるバケット内のオブジェクト管理を支援する機能の一種であり、COSの同期的List API操作を計画的に代替することができます。Cloud Object Storage（COS）はユーザーのリストタスク設定に基づき、毎日または毎週一定の時刻にユーザーがバケット内で指定したオブジェクトまたは同一のオブジェクトプレフィックスを持つオブジェクトのスキャンを行い、リストレポートを出力して、CSV形式のファイルをユーザーが指定したバケットに保存することができます。ファイルには保存されているオブジェクトおよびそれに対応するメタデータを出力し、ユーザーの設定情報に基づいて、ユーザーが必要とするオブジェクトのプロパティ情報を記録します。

リスト機能を使用すると、次の基本用途が実現できますが、用途はこれらのみに限定されません。

• オブジェクトのコピーおよび暗号化状態を審査し、報告します。
• 業務のワークフローおよびビッグデータ作業を簡略化し、スピーディーに行えます。

注意：

• ユーザーは1つのバケット内に複数のリストタスクを設定することができます。リストタスクは、オブジェクトの内容を直接読み取るのではなく、オブジェクトのメタデータなどのプロパティ情報のスキャンのみを行います。

リストのパラメータ

ユーザーがあるリストタスクを設定すると、COSは設定に応じて、ユーザーがバケット内で指定したオブジェクトを一定の時刻にスキャンし、リストレポートを出力します。リストレポートのファイル形式はCSVをサポートしています。現在、COSのリストレポートには次の情報を記録することができます。

リスト情報	説明
AppID	アカウントのID
Bucket	リストタスクを実行するバケット名
fileFormat	ファイル形式
listObjectCount	リストアップされたオブジェクト数です。料金はこの項目に基づいて課金されます。詳細については、管理機能料金のリスト機能料金の説明をご確認ください
listStorageSize	リストアップされたオブジェクトのサイズ
filterObjectCount	フィルタリングされたオブジェクト数
filterStorageSize	フィルタリングされたオブジェクトのサイズ
Key	バケット内のオブジェクトファイルの名称です。CSVファイル形式を使用する場合、オブジェクトファイル名にはURLエンコード形式が用いられているため、デコードして使用する必要があります
VersionId	オブジェクトのバージョンIDです。バケット上でバージョン管理を有効にすると、COSはバケットに追加されたオブジェクトにバージョン番号を割り当てます。リストがオブジェクトの現在のバージョンのみを対象としている場合は、このフィールドは含まれません
IsLatest	オブジェクトのバージョンが最新の場合はTrueに設定します。リストがオブジェクトの現在のバージョンのみを対象としている場合は、このフィールドは含まれません
IsDeleteMarker	オブジェクトが削除マーカーの場合はTrueに設定します。リストがオブジェクトの現在のバージョンのみを対象としている場合は、このフィールドは含まれません
Size	オブジェクトのサイズ（単位はバイト）
LastModifiedDate	オブジェクトの直近の変更日（日付の遅い方に準じる）
ETag	エンティティタグとはオブジェクトのハッシュです。ETagはオブジェクトの内容への変更のみを反映し、オブジェクトのメタデータへの変更は反映しません。ETagは、オブジェクトデータのMD5ダイジェストである場合も、そうではない場合もあります。どちらであるかは、オブジェクトの作成方法と暗号化方法によって決まります
StorageClass	オブジェクトの保存に用いるストレージクラスです。その他の情報に関しては、ストレージタイプをご参照ください
IsMultipartUploaded	オブジェクトをマルチパートアップロード形式でアップロードする場合は、Trueに設定します。その他の情報に関しては、マルチパートアップロードをご参照ください
Replicationstatus	オブジェクトのコピーにおいてソースファイルとレプリカファイルの状態をマークするために使用します。ソースファイルのマーカーはPENDING（コピー保留中）、COMPLETED（コピー完了）、FAILED（コピー失敗）、レプリカファイルのマーカーはREPLICA（コピー完了、レプリカファイル生成済み）となります。その他の情報に関しては、コピーアクションの説明をご参照ください
Tag	オブジェクトのタグ

リストの設定方法

リストを設定する前に、2つの概念をご理解いただく必要があります。

• ソースバケット：リスト機能をアクティブ化したいバケットです。
  • リストにリストアップされるオブジェクトが含まれます。
  • リストの設定が含まれます。
• ターゲットバケット：リストを保存するバケットです。
  • リストファイルが含まれます。
  • リストファイルの位置を記述したManifestファイルが含まれます。

リスト設定の手順は主に次のように分けられます。

ソースバケット内の分析対象のオブジェクト情報を指定する

どのオブジェクト情報を分析したいかをCOSに伝える必要があります。そのため、リスト機能を設定する際に、ソースバケットで次の情報を設定する必要があります。

• 選択するオブジェクトのバージョン：すべてのオブジェクトのバージョンをリストアップするか、または現在のバージョンのみをリストアップするかを選択します。すべてのオブジェクトのバージョンを選択した場合、COSは同名のオブジェクトのすべての過去バージョンをリストレポートに含めます。現在のバージョンのみを選択した場合、COSは最新バージョンのオブジェクトのみを記録します。
• 分析したいオブジェクトのプロパティの設定：オブジェクトのプロパティのうち、どの情報をリストレポートに記録させたいかをCOSに伝える必要があります。現在サポートしているオブジェクトのプロパティには、アカウントID、ソースバケット名、オブジェクトファイル名、オブジェクトバージョンID、最新バージョンかどうか、削除マーカーかどうか、オブジェクトサイズ、オブジェクトの最終変更日、ETag、オブジェクトのストレージクラス、地域間コピーマーカー、マルチパートアップロードファイルに該当するかどうかが含まれます。

リストレポートのストレージ情報の設定

どのような頻度でリストレポートをエクスポートするか、リストレポートをどのバケットに保存するかをCOSに伝えるとともに、リストレポートを暗号化するかどうかを決定する必要があります。設定する必要がある情報は次のとおりです。

• リストのエクスポート頻度の選択：每日または毎週から選択できます。この設定によって、どの頻度でリスト機能を実行するかをCOSに伝えることができます。
• リストの暗号化の選択：暗号化なしとSSE-COS暗号化から選択できます。SSE-COS暗号化を選択した場合、生成されるリストレポートは暗号化されます。
• リストの出力位置の設定：リストレポートを保存したいバケットを設定する必要があります。

注意：

ターゲットバケットは必ずソースバケットと同一のリージョンになければなりません。これらは同一のバケットとすることもできます。

利用方法

コンソール上でのリスト設定

コンソール上でリスト機能の設定を行う方法について詳しくお知りになりたい場合は、リスト機能のアクティブ化コンソールドキュメントをご参照ください。

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. リスト機能の有効化

インターフェースを呼び出してリスト機能を有効化します。具体的なインターフェースの情報については、PUT Bucket inventoryをご参照ください。リストファイルを保存するターゲットバケットはソースバケットと同一のリージョンにあることが必要です。

リストレポートのストレージパス

リストレポートおよび関連するManifest関連ファイルはターゲットバケット内に発行されます。このうちリストレポートは次のパスに発行されます。

destination-prefix/appid/source-bucket/config-ID/

Manifest関連ファイルはターゲットバケットの次のパスに発行されます。

destination-prefix/appid/source-bucket/config-ID/YYYYMMDD/manifest.json
destination-prefix/appid/source-bucket/config-ID/YYYYMMDD/manifest.checksum

パスの表す意味は次のとおりです。

• desitination-prefix：ユーザーがリストを設定する際に設定する「ターゲットプレフィックス」です。ターゲットバケット内のパブリックな位置にあるすべてのリストレポートのグループ化に用いることができます。
• source-bucket：リストレポートに対応するソースバケット名です。このフォルダを追加するのは、複数のソースバケットがそれぞれのリストレポートを同一のターゲットバケットに送信する際に競合が発生しないようにするためです。
• config-ID：ユーザーがリストを設定する際に設定する「リスト名」です。同一のソースバケットに複数のリストレポートを設定し、それらを同一のターゲットバケットに送信する際、config-IDを使用して異なるリストレポートを区別することができます。
• YYYYMMDD：タイムスタンプです。リストレポートの生成時にバケットスキャンを開始した時間および日付が含まれます。
• manifest.json：Manifestファイルを指します。
• manifest.checksum：manifest.jsonファイル内容のMD5です。

このうち、Manifest関連ファイルにはmanifest.jsonとmanifest.checksumの2つのファイルが含まれます。

説明：

Mainfestファイルに関する説明は次のとおりです。

• manifest.jsonとmanifest.chenksumはどちらも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コンソールでオブジェクトのプロパティをチェックすることをお勧めします。