リスト リクエストをフィルタ

list メソッドは、設定されたタイプの複数のリソースを取得します。filter クエリ パラメータを使用すると、取得するリソースが満たす必要のある条件を指定できます。

フィルタの構造

filter パラメータ値は文字列です。これらの文字列は、1 つ以上の条件で構成されます。条件は AND 演算子または OR 演算子で結合されます。

単一の条件の形式は {field} {operator} {value} です。次の例をご覧ください。

  entityStatus="ENTITY_STATUS_ACTIVE"

フィルタ文字列は 500 文字までに制限されています。文字列が長すぎる場合:

  • ロジックを個別の文字列に分割します。各フィルタ文字列で list 呼び出しを行います。結果を組み合わせて 1 つのリストにします。
  • フィルタ文字列から条件を削除します。削除された条件を使用して、取得したリソースをローカルでフィルタします。

条件の値を引用符で囲みます。

API 呼び出しを直接行う場合は、フィルタ文字列が URL で使用できるようにエンコードされていることを確認してください。

フィルタ文字列の構造について詳しくは、結合条件のセクションをご覧ください。

フィルタ条件

各リストメソッドは、特定のフィルタ条件をサポートしています。メソッドの 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 (=) のみがサポートされます。

特別な形式が必要な場合は、条件に記載されます。

結合条件

複数の条件を結合して、list レスポンスをさらに制限します。

論理演算子 AND と OR を使用して条件を結合します。各 list メソッドは、サポートされているものを指定します。一部のメソッドは、条件が 1 つのフィルタのみをサポートします。

複数の条件を使用する場合は、次の制限事項を考慮してください。

制限事項と例
AND は、異なるフィールドをフィルタする制限または制限のグループ、または同じフィールドを異なる方法でフィルタする制限を組み合わせる必要があります。 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 リクエストを使用してください。 次の 2 つのフィルタ文字列は別々のリクエストで使用する必要があり、OR 演算子を使用して組み合わせることはできません。
  • (lineItemType="LINE_ITEM_TYPE_DISPLAY_DEFAULT" AND insertionOrderId="123")
  • (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") として解釈されます。