Display & Video 360 API のほとんどのサービスでは、リソースを一括取得するための LIST メソッドが用意されています。これらの LIST メソッドは通常、filter クエリ パラメータによる結果のフィルタリングをサポートしています。このパラメータを使用すると、必要なもののみを取得することで API の使用を最適化できます。
このガイドでは、filter パラメータの効果的な使用方法について説明します。
フィルタ構造
filter パラメータ値は 1 つ以上の制限で構成される文字列です。AND または OR 演算子と組み合わせて、丸かっこでグループ化できます。
制限の形式は {field} {operator} {value} です。次の例をご覧ください。
entityStatus="ENTITY_STATUS_ACTIVE"
フィルタ文字列の長さは 500 文字以内にしてください。フィルタ文字列が 500 文字を超える場合は、次のいずれかを行います。
- ロジックを複数のフィルタ文字列に分割し、個別の
LISTリクエストを使用してリソースを取得します。 - フィルタ文字列から一部のロジックを削除し、取得したリソースをローカルでフィルタするために使用します。
ロジックが適切に適用されるよう、制限値を引用符で囲みます。
クライアント ライブラリを使用せずに LIST を直接呼び出す場合は、フィルタ文字列を URL エンコードします。
クエリのフォーマットについて詳しくは、制限間のロジックをご覧ください。
フィルタリング可能なフィールド
各 LIST メソッドのフィルタ可能なフィールドは、メソッドの filter パラメータの説明に記載されています。ほとんどの場合、リソースの標準フィールドのサブセットでフィルタリングできます。まれに、フィルタリングでのみ使用できる追加のフィールドが存在することがあります。
パラメータの説明の各フィールドでは、次の対応する演算子の少なくとも 1 つがサポートされています。
| 同等の演算子 | ||
|---|---|---|
EQUALS (=)
|
リソース フィールド値が、指定された値と等しくなります。
例: |
|
LESS THAN OR EQUAL TO (<=)
|
リソース フィールド値が指定された値以下です。通常は、日付や日時を比較するときに使用されます。 例: |
|
GREATER THAN OR EQUAL TO (>=)
|
リソース フィールド値が指定された値以上です。通常は、日付や日時を比較するときに使用されます。 例: |
|
HAS (:)
|
リソース フィールド値には指定された値が含まれます。リソース フィールドが文字列の場合、指定された値が既存の部分文字列であるかどうかをチェックします。リソース フィールドが配列の場合、配列に指定された値が含まれているかどうかをチェックします。
例: |
|
パラメータの説明のフィールドに演算子が指定されていない場合、使用できる演算子は EQUALS (=) のみです。一部のフィールドでは複数の演算子を使用できます。
日時のフィールドなど、フィルタ可能な一部のフィールドでは、比較可能な値が特定の形式に従う必要があります。形式は、filter パラメータの説明のフィールドの横に指定されます。
制限間のロジック
複数の制限を組み合わせて、LIST リクエストからのレスポンスを絞り込んだり、広げたりできます。
通常、論理演算子 AND と OR で複数の制限を組み合わせることができます。各 LIST メソッドには、サポートする演算子を指定します。一部のメソッドでは、filter パラメータで指定できる制限は 1 つだけです。
論理演算子 AND または OR を使用してフィルタ文字列を作成する場合は、次の制限を考慮してください。
ANDは、異なるフィールドをフィルタするか、同じフィールドを異なる方法でフィルタする、制限または制限のグループ間で使用する必要があります。次に例を示します。updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE"updateTime>="2023-03-01T12:00:00Z" AND updateTime<="2023-04-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED")
ORは、同じフィールドでフィルタリングする個々の制限間で使用する必要があります。次に例を示します。(entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED") AND (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" OR lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT")
ORを使用して 2 つの制限グループを組み合わせることはできません。代わりに、フィルタ値が異なる複数のLISTリクエストを使用してください。たとえば、次のLISTリクエストを個別に使用します。(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")(lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")
演算子を
OR演算子で結合しないでください。(lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123") OR (lineItemType="LINE_ITEM_TYPE_VIDEO_DEFAULT" AND insertionOrderId="456")フィルタ文字列の制限をグループ化するためにかっこを使用しない場合は、かっこが暗黙的に指定されることがあります。たとえば、次のフィルタ文字列があるとします。
updateTime>="2023-03-01T12:00:00Z" AND entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT"これは、次のように解釈されます。
updateTime>="2023-03-01T12:00:00Z" AND (entityStatus="ENTITY_STATUS_ACTIVE" OR entityStatus="ENTITY_STATUS_PAUSED" OR entityStatus="ENTITY_STATUS_DRAFT")