すべてのプロダクト
Search
ドキュメントセンター

Object Storage Service:オブジェクトメタデータに基づくオブジェクトのフィルタリング

最終更新日:Oct 20, 2026

このトピックでは、ossutil 2.0 を使用してオブジェクトメタデータに基づいてオブジェクトをフィルタリングする方法について説明します。

シナリオ

大量のオブジェクトを含むバケット内のオブジェクトを直接参照または処理するには時間がかかります。このため、ossutil 2.0 は、メタデータに基づく一連の効率的なフィルタリングオプションを提供しており、特定のメタデータに基づいてオブジェクトを正確にフィルタリングできます。

前提条件

メタデータに基づくオブジェクトのフィルタリング

ossutil 2.0 では、オブジェクトメタデータに基づいてオブジェクトを詳細にフィルタリングできます。ほとんどの場合、この機能は、オブジェクトを一覧表示する ls、オブジェクトのアップロード、ダウンロード、コピーをする cp、オブジェクトを削除する rm などの複数の高度なコマンドに適用できます。オブジェクトタイプなどのオブジェクトメタデータに基づいてオブジェクトをフィルタリングすることで、フィルタリング効率を向上させることができます。

パラメーターの説明

パラメーター

タイプ

説明

--metadata-include

stringArray

オブジェクトを対象に含めるためのメタデータフィルタリングルールを指定します。これにより、メタデータルールを満たすオブジェクトのみが表示されます。

--metadata-exclude

stringArray

オブジェクトを対象から除外するためのメタデータフィルタリングルールを指定します。これにより、メタデータルールを満たすオブジェクトは表示されません。

--metadata-filter

stringArray

より柔軟なマッチングロジックをサポートするメタデータフィルタリングルールを直接指定します。

--metadata-filter-from

stringArray

複雑なメタデータルールの管理と再利用を容易にするため、外部ルールファイルからメタデータフィルタリングルールを読み込むように指定します。

  • --metadata-include パラメーターを使用する場合、リストの末尾に、他のタイプのオブジェクトを除外する - ** というルールが暗黙的に追加されます。

  • --metadata-filter "+ rule" パラメーターを使用する場合、除外ルールは自動的には追加されません。つまり、--metadata-include "rule" は --metadata-filter "+ rule" + --metadata-filter "- **" と同等です。たとえば、バケット内のすべての JPEG 画像オブジェクトを正確にフィルタリングするには、--metadata-filter "+ content-type=image/jpeg" --metadata-filter "- **" を指定する必要があります。

  • メタデータフィルタリングルールが格納された複数の外部ルールファイルを一度に処理する場合、外部ファイルは左から右へ、各ファイル内のルールは上から下へと実行されます。また、# または ; で始まる空白行とコメント行は無視されます。

  • 最初のオブジェクトメタデータルールが一致すると、後続のルールのチェックは停止されます。

サポートされているメタデータタイプ

  • ストレージクラス。ストレージクラスでオブジェクトをフィルタリングするには、x-oss-storage-class=value を指定します。value には、Standard (標準)、IA (低頻度アクセス)、Archive (アーカイブ)、ColdArchive (コールドアーカイブ)、または DeepColdArchive (ディープコールドアーカイブ) を指定できます。

  • オブジェクトタイプ。オブジェクトタイプでオブジェクトをフィルタリングするには、x-oss-object-type=value を指定します。value には、Normal (通常)、Multipart (マルチパート)、Appendable (アペンド可能)、または Symlink (シンボリックリンク) を指定できます。

  • 復元ステータス。復元ステータスでオブジェクトをフィルタリングするには、x-oss-restore=value を指定します。value には、実際の復元ステータスを指定します。

  • コンテンツタイプ。コンテンツタイプでオブジェクトをフィルタリングするには、content-type=value を指定します。value には、実際のコンテンツタイプを指定します。

  • ユーザーメタデータ。ユーザーメタデータでオブジェクトをフィルタリングするには、x-oss-meta-aaa=value を指定します。x-oss-meta- はユーザーメタデータの開始を示す固定プレフィックスです。aaa はカスタムキー名、value はビジネス要件に基づいて指定されたユーザーメタデータの値です。例: x-oss-meta-location:hangzhou。

例

特定ストレージクラスのオブジェクトのフィルタリング

  • 次の例では、examplebucket バケット内のストレージクラスが標準であるオブジェクトをフィルタリングする方法について説明します。

    ossutil ls oss://examplebucket --metadata-include "x-oss-storage-class=Standard"
  • 次の例では、examplebucket バケット内のストレージクラスがアーカイブ、コールドアーカイブ、およびディープコールドアーカイブであるオブジェクトをフィルタリングする方法について説明します。

    ossutil ls oss://examplebucket --metadata-include "x-oss-storage-class=*Archive"

復元済みまたは復元中のオブジェクトのフィルタリング

パラメーター

タイプ

例

説明

x-oss-restore

String

  • 復元中: ongoing-request="true"

  • 復元済み: ongoing-request="false", expiry-date="Thu, 04 Jan 2024 03:28:54 GMT"

HeadObject API を呼び出して、x-oss-restore レスポンスヘッダーに基づいてオブジェクトが復元されているかどうかを確認できます。

  • 復元操作が実行されていない場合、または復元操作がタイムアウトした場合、x-oss-restore レスポンスヘッダーは返されません。

  • 復元操作が進行中の場合、ongoing-request="true" が x-oss-restore レスポンスヘッダーの右側に表示されます。

  • 復元操作が完了している場合、ongoing-request="false" が x-oss-restore レスポンスヘッダーの右側に表示されます。この場合、expiry-date が x-oss-restore レスポンスヘッダーに含まれており、オブジェクトを読み取ることができなくなる時刻を示します。

  • 次の例では、examplebucket バケット内の復元中のオブジェクトをフィルタリングする方法について説明します。2つのアスタリスク (**) は、前の文字列に続く任意の文字列に一致するワイルドカードとして機能します。

    ossutil ls oss://examplebucket --metadata-include "x-oss-restore=ongoing-request=\"true\"**"
  • 次の例では、examplebucket バケット内の復元済みのオブジェクトをフィルタリングする方法について説明します。2つのアスタリスク (**) は、前の文字列に続く任意の文字列に一致するワイルドカードとして機能します。

    ossutil ls oss://examplebucket --metadata-include "x-oss-restore=ongoing-request=\"false\"**"

包含/除外ルールによる特定形式オブジェクトのフィルタリング

  • 次の例では、特定の操作やデータ分析のために、examplebucket バケット内のすべての JPEG 画像オブジェクトをフィルタリングする方法について説明します。

    ossutil ls oss://examplebucket --metadata-include "content-type=image/jpeg"
  • 次のコマンドは、examplebucket バケット内で content-type メタデータ属性に一致するすべてのプレーンテキストオブジェクトを一覧表示します。

    ossutil ls oss://examplebucket --metadata-include "content-type=text/plain"
    説明

    ワイルドカードパターンを使用してオブジェクト名でフィルタリングするには、--include を使用し、--metadata-include は使用しないでください。例: ossutil ls oss://examplebucket --include "*.txt"。

メタデータフィルタリングルールを直接指定した特定の形式のオブジェクトのフィルタリング

次の例では、examplebucket バケット内のすべての JPEG 画像オブジェクトをフィルタリングする方法について説明します。--metadata-filter パラメーターを指定してメタデータフィルタリングルールを直接指定し、プラス記号 (+) とマイナス記号 (-) を使用して包含/除外ルールを指定できます。Content-Type が image/jpeg である examplebucket バケット内のすべてのオブジェクトが一覧表示され、Content-Type が image/jpeg でないオブジェクトは除外されます。

ossutil ls oss://examplebucket --metadata-filter "+ content-type=image/jpeg" --metadata-filter "- **"

外部ルールファイルを使用したオブジェクトのフィルタリング

メタデータフィルタリングルールが複雑な場合、または複数の異なるメタデータフィルタリングルールを一度に適用する必要がある場合は、事前に外部ルールファイルを作成してオブジェクトをフィルタリングできます。

metadata_filters.txt という名前の外部ルールファイルを使用して、ストレージクラスが標準であるすべての JPEG 画像オブジェクトをフィルタリングするには、外部ルールファイルに次のサンプルコードを追加します。

# ルールファイル: metadata_filters.txt
+ content-type=image/jpeg
+ x-oss-storage-class=Standard
- **

--metadata-filter-from オプションを使用して外部ルールファイルを呼び出して、オブジェクトをフィルタリングします。

ossutil ls oss://examplebucket --metadata-filter-from metadata_filters.txt