DoMetaQuery - Object Storage Service - Alibaba Cloud ドキュメントセンター

指定された条件を満たすオブジェクトを照会し、指定されたフィールドとソート方法に基づいてオブジェクトに関する情報を一覧表示します。ネストされたクエリを使用して複雑なクエリを実装し、集計操作を実行してさまざまなフィールドの値を収集および分析することもできます。

使用上の注意

指定された条件を満たすオブジェクトをクエリするには、oss:DoMetaQuery権限が必要です。詳細については、「RAMユーザーへのカスタムポリシーのアタッチ」をご参照ください。

リクエスト構文

POST /?metaQuery&comp=クエリHTTP/1.1
ホスト: BucketName.oss-cn-hangzhou.aliyuncs.com
日付: GMT日付
権限付与: SignatureValue
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <NextToken></NextToken>
  <MaxResults>5</MaxResults>
  <Query>{"Field": "Size","Value": "1048576","Operation": "gt"}</Query>
  <並べ替え> サイズ </並べ替え>
  <注文> asc</注文>
  <集約>
    <集約>
      <フィールド> サイズ </フィールド>
      <操作> 合計 </操作>
    </集約>
    <集約>
      <フィールド> サイズ </フィールド>
      <操作> max</操作>
    </集約>
  </集約>
</MetaQuery>

リクエストヘッダー

このリクエストには、共通リクエストヘッダーのみが含まれます。詳細については、「共通HTTPヘッダー」をご参照ください。

リクエスト要素

要素	データ型	必須	例	説明
メタクエリ	Container	必須	N/A	クエリ条件のコンテナー。The container for query conditions. 子ノード: NextToken、MaxResults、Query、Sort、Order、およびAggregations
NextToken	String	任意	MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw ****	オブジェクトの総数がMaxResultsの値を超えたときに次のクエリに使用されるトークン。オブジェクト情報は、NextTokenの値からアルファベット順に返されます。この操作が初めて呼び出されるときは、このフィールドをnullに設定します。親ノード: MetaQuery
MaxResults	整数	任意	5	返されるオブジェクトの最大数。有効値: 0~100。このパラメーターが設定されていないか、0に設定されている場合、100のオブジェクトが返されます。親ノード: MetaQuery
クエリ	String	必須	{"フィールド": "サイズ","値": "1048576","操作": "gt"}	クエリ条件。オプション：操作: オペレーター。有効値: eq (equal to) 、gt (greater than) 、gte (greater than or equal to) 、lt (less than) 、lte (less than or equal to) 、match (ファジークエリ) 、prefix (prefix query) 、および (and) 、または (or) 、およびnot (NOT) 。フィールド: フィールド。サポートされるフィールドとサポートされる演算子の詳細については、「付録: サポートされるフィールドと演算子」をご参照ください。値: フィールドの値。 SubQueries: サブクエリ条件。この要素に含まれるオプションは、単純なクエリのオプションと同じです。 OperationがAND、OR、またはNOTに設定されている場合にのみ、サブクエリ条件を設定する必要があります。詳細については、「クエリ例」をご参照ください。親ノード: MetaQuery
ソート	String	任意	サイズ	結果のソートに基づくフィールド。ソートできるフィールドの詳細については、「付録: サポートされるフィールドと演算子」をご参照ください。親ノード: MetaQuery
Order	String	任意	asc	クエリされたデータを並べ替える順序。デフォルト値：desc (降順)。有効な値： asc: データは昇順でソートされます desc: データは降順でソートされます。親ノード: MetaQuery
集約	Container	任意	N/A	集計操作に関する情報のコンテナー。子ノード: Aggregation 親ノード: MetaQuery
集約	Container	任意	N/A	単一の集計操作に関する情報のコンテナー。子ノード: フィールドと操作親ノード: 集計
フィールド	String	任意	サイズ	フィールドの名前を設定します。サポートされるフィールドとサポートされる演算子の詳細については、「付録: サポートされるフィールドと演算子」をご参照ください。親ノード: Aggregation
操作	String	任意	sum	集計操作の演算子。有効な値： min max 平均 sum 集計 distinct group 親ノード: Aggregation

レスポンスヘッダー

このリクエストには、共通のレスポンスヘッダーのみが含まれます。詳細については、「共通HTTPヘッダー」をご参照ください。

レスポンス要素

要素	データ型	例	説明
メタクエリ	Container	N/A	クエリ結果のコンテナー。The container for the query result. 子ノード: NextToken、Files、およびAggregions
NextToken	String	MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw ****	オブジェクトの総数がMaxResultsの値を超えたときに次のクエリに使用されるトークン。 NextTokenの値は、次のクエリで未返さの結果を返すために使用されます。このパラメーターは、すべてのオブジェクトが返されない場合にのみ値を持ちます。親ノード: MetaQuery
ファイル	Container	N/A	オブジェクトに関する情報のコンテナー。子ノード: ファイル親ノード: MetaQuery
ファイル	Container	N/A	単一のオブジェクトに関する情報のコンテナー。子ノード: Filename、Size、FileModifiedTime、OSSOobjectType、OSSStorageClass、ObjectACL、ETag、OSSTaggingCount、OSSTagging、OSSUserMeta、OSSCRC64、およびServerSideEncryption 親ノード: ファイル
ファイル名	String	exampleobject.txt	オブジェクトのフルパス。The full path of the object. 親ノード: ファイル
サイズ	Integer	120	オブジェクトのサイズ。単位：バイト親ノード: ファイル
FileModifiedTime	String	2021-06-29T15:04:05.000000000Z07:00	オブジェクトが最後に変更された時刻。値はRFC 3339の形式に従います。親ノード: ファイル
OSSObjectType	String	正常	オブジェクトのタイプです。有効な値： Normal: オブジェクトはPutObject操作を呼び出してアップロードされたか、CreateDirectory操作を呼び出して作成されました。 Appendable: オブジェクトはAppendObject操作を呼び出してアップロードされました。 Multipart: オブジェクトはMultipartUpload操作を呼び出してアップロードされました。 Symlink: シンボリックリンクは、PutSymlink操作を呼び出すことによって作成されました。親ノード: ファイル
OSSStorageClass	String	標準	オブジェクトのストレージクラス。有効な値： Standard: Standardストレージクラスは、頻繁なデータアクセスを処理できる、信頼性が高く、可用性が高く、パフォーマンスの高いオブジェクトストレージサービスを提供します。 IA: 低頻度アクセス (IA) ストレージクラスは、アクセス頻度の低いデータの長期保存に適しています。月に1回または2回アクセスされるデータは、このクラスに分類されます。 Archive: Archiveストレージクラスは、アクセス頻度の低いデータの長期保存に適しています。少なくとも6か月間保存するデータは、このクラスに分類されます。データを読み取るには、復元に最大1分かかります。 ColdArchive: Cold Archiveストレージクラスは、めったにアクセスされないデータの長期保存に適しています。親ノード: ファイル
ObjectACL	String	default	オブジェクトのアクセス制御リスト (ACL) 。有効な値： default: オブジェクトのACLは、オブジェクトが格納されているバケットのACLと同じです。 private: オブジェクトのACLがprivateです。オブジェクトに対する読み取りおよび書き込み権限を持つのは、オブジェクトの所有者および許可されたユーザーのみです。 public-read: オブジェクトのACLはpublic readです。オブジェクトに対する読み取りおよび書き込み権限を持つのは、オブジェクトの所有者および許可されたユーザーのみです。他のユーザーはオブジェクトを読むことしかできません。オブジェクトACLをこの値に設定する場合は注意してください。 public-read-write: オブジェクトのACLはpublic read/writeです。すべてのユーザーがオブジェクトに対する読み取りおよび書き込み権限を持っています。オブジェクトACLをこの値に設定する場合は注意してください。親ノード: ファイル
ETag	String	"fba9dede5f27731c9771645a3986 ****"	オブジェクトの作成時に生成されたETag。 ETagは、オブジェクトのコンテンツを識別するために使用されます。 PutObject操作を呼び出してオブジェクトが作成された場合、オブジェクトのETag値はオブジェクトコンテンツのMD5ハッシュになります。オブジェクトが別のメソッドを使用して作成された場合、ETag値はオブジェクトコンテンツのMD5ハッシュではなく、特定のルールに基づいて計算された一意の値になります。説明オブジェクトのETag値を使用して、オブジェクトの内容が変更されているかどうかを確認できます。データの整合性を確認するには、ETag値ではなくオブジェクトのMD5ハッシュを使用することをお勧めします。親ノード: ファイル
OSSTaggingCount	Integer	2	オブジェクトのタグの数。親ノード: ファイル
OSSTagging	Container	N/A	タグに関する情報のコンテナー。子ノード: タグ付け親ノード: ファイル
タギング	Container	N/A	単一のタグに関する情報のコンテナー。子ノード: キーと値。親ノード: OSSTagging
Key	String	owner	タグまたはユーザーメタデータのキー。ユーザーメタデータの先頭に`x-oss-meta-` を付ける必要があります。親ノード: タグ付けとUserMeta
値	String	John	タグまたはユーザーメタデータの値。親ノード: タグ付けとUserMeta
OSSUserMeta	Container	N/A	ユーザーメタデータのコンテナー。The container for user metadata. 子ノード: UserMeta 親ノード: ファイル
UserMeta	Container	N/A	単一のユーザーのメタデータのコンテナー。子ノード: キーと値。親ノード: OSSUserMeta
OSSCRC64	String	4858A48BD1466884	オブジェクトのCRC-64値。この値は、ECMA-182 標準に基づいて計算されます。
ServerSideEncryption	String	AES256	Object Storage Service (OSS) がオブジェクトを作成したときに使用されるサーバー側暗号化アルゴリズム。有効値は AES256 です。親ノード: ファイル
ServerSideEncryptionCustomerAlgorithm	String	SM4	ローカルクライアントでオブジェクトを暗号化するために使用されるアルゴリズム。親ノード: ファイル
集約	Container	N/A	集計操作に関する情報のコンテナー。子ノード: フィールド、操作、値、およびグループ親ノード: MetaQuery
フィールド	String	サイズ	フィールドの名前を設定します。親ノード: 集計
操作	String	sum	集計操作の演算子。親ノード: 集計
値	浮く	200	集計操作の結果。親ノード: 集計
Groups	Container	N/A	グループごとに実行された集計操作の結果リスト。子ノード: 値とカウント親ノード: 集計
値	String	100	グループごとに実行された集計操作の結果。親ノード: グループ
集計	Integer	5	グループごとに実行された集計操作の数。親ノード: グループ

例

POST /?metaQuery&comp=クエリHTTP/1.1のサンプルリクエスト


ホスト: oss-example.oss-cn-hangzhou.aliyuncs.com
日付: 7月26日月曜日2021 13:08:38 GMT
権限付与: OSS qn6qrrqxo2oawuk53otf ****:ceOEyZavKY4QcjoUWYSpYbJ3 ****
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <NextToken>MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw ****</NextToken>
  <MaxResults>5</MaxResults>
  <Query>{"Field": "Size","Value": "1048576","Operation": "gt"}</Query>
  <並べ替え> サイズ </並べ替え>
  <注文> asc</注文>
  <集約>
    <集約>
      <フィールド> サイズ </フィールド>
      <操作> 合計 </操作>
    </集約>
    <集約>
      <フィールド> サイズ </フィールド>
      <操作> max</操作>
    </集約>
  </集約>
</MetaQuery>

HTTP/1.1 200のサンプル応答

OK
x-oss-request-id: 5C1B138A109F4E405B2D ****
日付: 7月26日月曜日2021 13:08:38 GMT
コンテンツ-長さ: 118
Content-Type: application/xml
接続: キープアライブ
サーバー: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<MetaQuery>
  <NextToken>MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpw ****</NextToken>
  <ファイル>
    <ファイル>
      <Filename>exampleobject.txt</Filename>
      <サイズ> 120</サイズ>
      <FileModifiedTime>2021-06-29T15:04:05.000000000Z07:00</FileModifiedTime>
      <OSSObjectType> ノーマル </OSSObjectType>
      <OSSStorageClass> 標準 </OSSStorageClass>
      <ObjectACL> デフォルト </ObjectACL>
      <ETag>"fba9dede5f27731c9771645a3986 ****"</ETag>
      <OSSCRC64>4858A48BD1466884</OSSCRC64>
      <OSSTaggingCount>2</OSSTaggingCount>
      <OSSTagging>
        <タグ付け>
          <キー> 所有者 </キー>
          <値> ジョン </値>
        </タグ付け>
        <タグ付け>
          <キー> タイプ </キー>
          <Value> ドキュメント </Value>
        </タグ付け>
      </OSSTagging>
      <OSSUserMeta>
        <UserMeta>
          <キー> x-oss-meta-location</キー>
          <値> 杭州 </値>
        </UserMeta>
      </OSSUserMeta>
    </ファイル>
  </ファイル>
</MetaQuery>

クエリの例

クエリはネストできます。ネストされたクエリを使用して、複雑なクエリと完全一致を実装できます。次の例は、ネストされたクエリの実行方法を示しています。

名前がexampleobject.txtで、サイズが1,000バイト未満のオブジェクトをクエリする場合は、次の例に示すようにクエリを設定できます

。{
  "SubQueries":[
    {
      "フィールド":"ファイル名" 、
      "値": "exampleobject.txt" 、
      "操作":"eq"
    },         
    {
      "フィールド":"サイズ" 、
      "値":"1000" 、
      "操作":"lt"
    }
  ],
  "操作":"と"
}

プレフィックスがexampledir/ で、type=documentまたはowner=Johnタグを含み、サイズが10 MBを超えるオブジェクトをクエリする場合は、次の例に示すようにクエリを設定できます。


{
  "SubQueries": [
    {
      "フィールド": "ファイル名" 、
      "Value": "exampledir/" 、
      "操作": "プレフィックス"
    },
    {
      "フィールド": "サイズ" 、
      "値": "1048576" 、
      "操作": "gt"
    },
    {
      "SubQueries": [
        {
          "フィールド": "OSSTagging.type" 、
          "値": "ドキュメント" 、
          "操作": "eq"
        },
        {
          "フィールド": "OSSTagging.owner" 、
          "値": "ジョン" 、
          "操作": "eq"
        }
      ],
      "操作": "または"
    }
  ],
  "操作": "と"
}

集計操作を実行して、上記の検索条件に基づいてさまざまなデータを収集および分析することもできます。たとえば、クエリ条件を満たすすべてのオブジェクトの合計、カウント、平均値、または最大値を計算できます。クエリ条件を満たす画像のサイズ分布を計算することもできます。

エラーコード

エラーコード	HTTPステータスコード	説明
MetaQueryNotExist	400	メタデータインデックスライブラリがバケットに存在しない場合に返されるエラーメッセージ。バケットのメタデータ管理機能が有効になっていることを確認し、メタデータインデックスライブラリの作成後に再試行してください。
EntityTooLarge	400	queryパラメーターで指定されたクエリ条件で許可されている最大文字列サイズを超えた場合に返されるエラーメッセージ。クエリ条件を変更して、もう一度お試しください。
InvalidArgument	400	指定された引数の値が無効な場合に返されるエラーメッセージ。有効な引数を指定します。
InvalidParameter	400	指定されたパラメーター値が無効な場合に返されるエラーメッセージ。有効なパラメーター値を指定します。
MissingParameter	400	リクエストに必要なパラメーターが指定されていない場合に返されるエラーメッセージ。必要なすべてのパラメーターを指定します。
Throttling.Api	403	スロットリングによりリクエストが拒否された場合に返されるエラーメッセージ。リクエストの1秒あたりのクエリ数 (QPS) を減らして、もう一度お試しください。操作を複数回試行してもエラーが発生しない場合は、チケットを起票してください。
Throttling.User	403	スロットリングによりリクエストが拒否された場合に返されるエラーメッセージ。リクエストの1秒あたりのクエリ数 (QPS) を減らして、もう一度お試しください。操作を複数回行ってもエラーが発生しない場合は、チケットを起票してください。
AccessDenied	403	バケットにアクセスする権限がない場合に返されるエラーメッセージ。 RAMユーザーにバケットへのアクセス権限が付与されていることを確認します。
NoSuchBucket	404	宛先バケットが存在しない場合に返されるエラーメッセージ。有効なバケット名を指定します。
InternalServerError	500	内部エラーが発生した場合に返されるエラーメッセージ。操作を複数回試行してもエラーが発生しない場合は、チケットを起票してください。