リストの回答をフィルタ

ディスプレイ＆ビデオ 360 API のほとんどのサービスには、リソースを一括取得するための LIST メソッドが用意されています。通常、これらの LIST メソッドは、filter クエリ パラメータによる結果のフィルタリングをサポートしています。このパラメータを使用すると、必要なデータのみを取得して API の使用量を最適化できます。

このガイドでは、filter パラメータを効果的に使用する方法について説明します。

フィルタ構造

filter パラメータ値は、AND 演算子または OR 演算子と組み合わせて使用できる制限事項を 1 つ以上含む文字列で、括弧を使用してグループ化できます。

制限の形式は {field} {operator} {value} です。次の例をご覧ください。

entityStatus="ENTITY_STATUS_ACTIVE"

フィルタ文字列の長さは 500 文字以内にする必要があります。フィルタ文字列が 500 文字を超える場合は、次のいずれかを行います。

  • ロジックを複数のフィルタ文字列に分割し、個別の LIST リクエストを使用してリソースを取得します。
  • フィルタ文字列から一部のロジックを削除し、取得したリソースをローカルでフィルタするために使用します。

制限値を引用符で囲んで、ロジックが正しく適用されるようにします。

クライアント ライブラリを使用せずに LIST 呼び出しを直接行う場合は、フィルタ文字列を URL エンコードします。

クエリの形式設定の詳細については、制限間のロジックをご覧ください。

フィルタリング可能なフィールド

各 LIST メソッドのフィルタ可能なフィールドは、メソッドの filter パラメータの説明に記載されています。ほとんどの場合、リソースの標準フィールドのサブセットでフィルタできます。まれに、フィルタ専用に使用できる追加のフィールドがあります。

パラメータの説明の各フィールドは、次の比較演算子の少なくとも 1 つをサポートしています。

比較演算子
EQUALS (=) リソース フィールドの値が指定された値と等しい。

例: entityStatus="ENTITY_STATUS_ACTIVE"
LESS THAN OR EQUAL TO (<=) リソース フィールドの値が指定された値以下です。日付または日時を比較する場合によく使用されます。

例: updateTime<="2023-04-01T12:00:00Z"
GREATER THAN OR EQUAL TO (>=) リソース フィールドの値が指定された値以上である。日付または日時を比較する場合によく使用されます。

例: updateTime>="2023-03-01T12:00:00Z"
HAS (:) リソース フィールドの値には、指定された値が含まれます。リソース フィールドが文字列の場合、指定された値が既存の部分文字列かどうかを確認します。リソース フィールドが配列の場合、配列に指定された値が含まれているかどうかを確認します。

例: lineItemIds:"1234"

パラメータの説明でフィールドに演算子が指定されていない場合は、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")