Ad Manager REST API は、List メソッドによるフィルタリングをサポートしています。フィルタ文字列の構文は、EBNF 文法で正式に定義されています。
まずは、一般的なユースケースの例をいくつか紹介します。
| 例 | 意味 |
|---|---|
orders.updateTime > "2024-01-01T00:00:00-5:00" |
東部標準時タイムゾーンで 2024 年 1 月 1 日以降に updateTime の注文を一覧表示します |
lineItems.targeting.geoTargeting.targetedGeoIds:2840 |
地域ターゲティングに米国（地域ターゲティング ID 2480）が含まれる広告申込情報を一覧表示します |
lineItems.displayName = "*_interstitial" |
表示名が文字列 _interstitial で終わる広告申込情報を一覧表示します。 |
orders.displayName = "*video*" |
表示名に文字列 video を含む注文を一覧表示します。 |
displayName:"video" |
表示名に文字列 video を含む注文を一覧表示します（代替構文） |
リテラル
単なるリテラル値（例: 42、Hugo）は、照合対象となる値です。単独で表示されるリテラルは、リソースでサポートされているすべてのフィールドに対してファジー照合されます。リソースには、list メソッドでの照合の対象とするフィールドが記載されています。この機能はアド マネージャー管理画面のユニバーサル検索に相当しますが、対象が 1 つのリソースタイプです。
スペースを含む文字列リテラルは、二重引用符で囲む必要があります（例: "Foo bar"）。一重引用符を使用して文字列リテラルを囲むことはできません。
論理演算子
アド マネージャー REST API では、バイナリ演算子 AND と OR がサポートされています。
| 演算子 | 例 | 意味 |
|---|---|---|
AND |
a AND b |
a と b が true の場合は true。 |
OR |
a OR b OR c |
a、b、c のいずれかが true の場合は true。 |
否定演算子
アド マネージャー REST API には、単項演算子 NOT と - が用意されています。
これらは同じ意味でも使用できます。
| 演算子 | 例 | 意味 |
|---|---|---|
NOT |
NOT a |
a が true でない場合は true に設定します。 |
- |
-a |
a が true でない場合は true に設定します。 |
比較演算子
アド マネージャー REST API では、文字列、数値、タイムスタンプ、期間の各フィールドで、バイナリ比較演算子 =、!=、<、>、<=、>= がサポートされています。
| 演算子 | 例 | 意味 |
|---|---|---|
= |
a = true |
a が true の場合は true。 |
!= |
a != 42 |
a が 42 と等しい場合を除き、true。 |
< |
a < 42 |
a が 42 未満の数値の場合は true。 |
> |
a > "foo" |
a が「foo」の後に語彙順に並べられる場合は true。 |
<= |
a <= "foo" |
a が「foo」であるか、語彙単位でその前のものである場合は true。 |
>= |
a >= 42 |
a が 42 以上の数値の場合は true。 |
フィルタはクエリ文字列として受け入れられるため、文字列を厳密に型指定された適切な値に変換するために型変換が行われます。
- 文字列には二重引用符が必要です。（例:
"Foo bar"）。 - 列挙型では、列挙型の文字列表現が想定されます（大文字と小文字は区別されます）。
- ブール値は、
trueとfalseのリテラル値を想定します。 - 数値は、標準の整数または浮動小数点数で表現します。浮動小数点数の場合、指数がサポートされます。（例:
2.997e9）。 - 持続時間には、数値表現の後に
s接尾辞（秒）を続ける必要があります。例:"20s"、"1.2s"。 - タイムスタンプは、RFC-3339 形式の文字列を想定しています。（例:
"2012-04-21T11:30:00-04:00"）。UTC オフセットがサポートされています。
ワイルドカード
文字列が等価かどうかを比較する際、アド マネージャー REST API では、* 文字を使用したワイルドカードを使用できます。
| 例 | 意味 |
|---|---|
a = "*.foo" |
a が「.foo」で終わる場合は true。 |
走査演算子
アド マネージャー REST API では、メッセージ、マップ、構造体の走査を示す . 演算子がサポートされています。
| 例 | 意味 |
|---|---|
a.b = true |
a のブール値 b フィールドが true の場合は true。 |
a.b > 42 |
a に 42 より大きい数値 b フィールドがある場合は true。 |
a.b.c = "foo" |
a.b に「foo」の文字列 c フィールドがある場合は true。 |
走査はリソースのフィールド名を使用して記述されます。個々のサービスで、走査でサポートされているフィールドのサブセットを指定できます。
演算子あり
アド マネージャー REST API では、: 演算子がサポートされています。これは「has」を意味します。
これは、コレクション（繰り返しフィールドまたはマップ）、メッセージ、文字列で使用でき、それぞれの場合でわずかに異なる動作をします。
String フィールドは、文字列に一致する部分文字列が含まれているかどうかを照会します。
| 例 | 意味 |
|---|---|
r.displayName:"_250x250" |
文字列フィールド r.displayName に部分文字列 _250x250 が含まれている場合は true。 |
繰り返しフィールドは、繰り返し構造に一致する要素が含まれているかどうかを照会します。
| 例 | 意味 |
|---|---|
r:42 |
r に 42 が含まれている場合は true。 |
r.foo:42 |
r に e.foo = 42 のような要素 e が含まれている場合は true。 |
マップ、構造体、メッセージでは、マップにフィールドが存在するかどうか、または特定の値があるかどうかをクエリできます。
| 例 | 意味 |
|---|---|
m:foo |
m にキー「foo」が含まれている場合は true です。 |
m.foo:* |
m にキー「foo」が含まれている場合は true です。 |
m.foo:42 |
m.foo が 42 の場合は true。 |
メッセージを走査する際、フィールドはデフォルト値以外の値を持つ場合にのみ存在するとみなされます。
制限事項
ここで定義されているものに加えて、個々のサービスでフィルタクエリの構造や制限を指定できます。
注文
Ad Manager REST API は、List メソッドの順序付けをサポートしています。orderBy フィールドの構文は、フィールド名のカンマ区切りリストです。例: "foo,bar"。
デフォルトの並べ替え順は昇順です。フィールドを降順を指定するには、" desc" 接尾辞を追加します。例: "foo desc, bar"。
構文に重複する空白文字は無視されます。値 "foo, bar desc"、" foo , bar desc "、"foo,bar desc" はすべて同じです。
サブフィールドは走査演算子で指定します。たとえば、foo.bar や address.street などです。