filters クエリ文字列パラメータは AdSense Management API レポートで返されるデータを制限します。filters パラメータを使用する場合は、フィルタを適用するディメンションの後にフィルタ式を指定します。
フィルタされたクエリでは、結果に含める行が制限されます。結果の各行はフィルタに対してテストされます。フィルタが一致する場合は行が保持され、一致しない場合は行が削除されます。
- URL エンコード: クライアント ライブラリによってフィルタ演算子が自動的にエンコードされます。ただし、プロトコルに直接リクエストを送信する場合は、以下の表に示すように、フィルタ演算子を明示的にエンコードする必要があります。
- フィルタの優先度: フィルタはディメンションの集計前に行われるため、返される指標は該当するディメンションの合計を表します。
フィルタ構文
1 つのフィルタには次の形式を使用します。
name operator expression
この構文の説明は次のとおりです。
- name - フィルタを適用するディメンションの名前。たとえば、
AD_CLIENT_IDは広告クライアント ID でフィルタします。 - 演算子 - 使用するフィルタの一致の種類を定義します。
- 式 - 結果に含める値を記述します。
レポート対象の指標に適用されるすべてのディメンションは、日付関連のディメンション（DATE、WEEK、MONTH）を除き、フィルタとして使用できます。日付でフィルタするには、代わりにレポートの期間を指定します。
フィルタ演算子
フィルタ演算子は 2 つあります。演算子を URL クエリ文字列に含めるには URL エンコードを行う必要があります。
| 演算子 | 説明 | URL エンコード形式 | 例 |
|---|---|---|---|
== |
完全一致 | %3D%3D |
国名が Canada の指標の集計:
filters=COUNTRY_NAME%3D%3DCanada |
=@ |
文字列の一部に一致 | %3D@ |
国名に United が含まれる場合、米国および英国と一致する集計指標。例:
filters=COUNTRY_NAME%3D@United |
フィルタ式
フィルタ式にはいくつか重要な規則があります。
- URL 予約文字 -
&などの文字には、通常の方法で URL エンコードを行う必要があります。この処理はクライアント ライブラリが行うため、プロトコルを直接呼び出す場合のみ、このエンコードについて心配する必要はありません。 - 予約文字 - カンマとバックスラッシュを式に含める場合は、バックスラッシュでエスケープする必要があります。
- バックスラッシュ
\\ - カンマ
\,
- バックスラッシュ
注: 二重にエスケープされないように、カンマの前にバックスラッシュをエスケープしてください。
フィルタの組み合わせ
フィルタは、ブール論理 OR と AND を使用して組み合わせることができます。
OR 論理
OR ロジックは、フィルタ式内でカンマ（,）を使用して定義されます。
例: （いずれも URL エンコードする必要があります）
国コードが米国または英国のいずれかの場合:
COUNTRY_CODE==US,COUNTRY_CODE==UK
AND 論理
AND ロジックを実現するには、複数のフィルタ パラメータを指定します。これは、クライアント ライブラリ内にフィルタの配列を指定します。
例:
国コードが米国で、かつ商品コードが AFC の場合:
filters=COUNTRY_CODE%3D%3DUS&filters=PRODUCT_CODE%3D%3DAFC
AND 論理演算子と OR 論理演算子の組み合わせ
AND ロジックと OR ロジックを 1 つの式に組み合わせることができます。
注: 各フィルタは、すべてのフィルタが AND 論理式に結合される前に、個別に評価されます。
例:
国コードが US または UK で、かつ商品コードが AFC の場合:
filters=COUNTRY_CODE%3D%3DUS,COUNTRY_CODE%3D%3DUK&filters=PRODUCT_CODE%3D%3DAFC