Ad Manager 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"）。単一引用符を使用して文字列リテラルを囲むことはできません。
論理演算子
Ad Manager API は、バイナリ演算子 AND と OR をサポートしています。
| 演算子 | 例 | 意味 |
|---|---|---|
AND |
a AND b |
a と b が true の場合、true を返します。 |
OR |
a OR b OR c |
a、b、c のいずれかが true の場合、true。 |
否定演算子
Ad Manager API には、単項演算子 NOT と - が用意されています。これらは互換性があります。
| 演算子 | 例 | 意味 |
|---|---|---|
NOT |
NOT a |
a が true でない場合、true。 |
- |
-a |
a が true でない場合、true。 |
比較演算子
Ad Manager 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 オフセットがサポートされています。
ワイルドカード
文字列の等価性を比較する場合、Ad Manager API は * 文字を使用したワイルドカードをサポートしています。
| 例 | 意味 |
|---|---|
a = "*.foo" |
a が「.foo」で終わる場合は true。 |
走査演算子
Ad Manager API は、メッセージ、マップ、構造体を走査する . 演算子をサポートしています。
| 例 | 意味 |
|---|---|
a.b = true |
a に true のブール値 b フィールドがある場合、true。 |
a.b > 42 |
a に 42 より大きい数値の b フィールドがある場合、true。 |
a.b.c = "foo" |
a.b に「foo」という文字列 c フィールドがある場合、true。 |
トラバーサルは、リソースのフィールド名を使用して記述されます。個々のサービスは、走査でサポートされるフィールドのサブセットを指定できます。
オペレーターあり
Ad Manager API は、: 演算子（「has」を意味する）をサポートしています。コレクション（繰り返しフィールドまたはマップ）、メッセージ、文字列で使用できます。動作はケースによって若干異なります。
文字列フィールドのクエリ。文字列に一致する部分文字列が含まれているかどうかを確認します。
| 例 | 意味 |
|---|---|
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。 |
メッセージを走査する場合、フィールドはデフォルト以外の値が設定されている場合にのみ存在すると見なされます。
制限事項
個々のサービスでは、ここで定義されているものに加えて、フィルタクエリの構造や制限を指定できます。
注文
ほとんどのリソースは、List メソッドでの並べ替えをサポートしています。リソースの正確な動作と、並べ替えにサポートされているフィールドについては、List メソッドのドキュメントをご覧ください。
orderBy フィールドの構文は、フィールド名のカンマ区切りのリストです。例: "foo,bar"
デフォルトの並べ替え順序は昇順です。フィールドに対して降順を指定するには、接尾辞 " desc" を追加します。例: "foo desc, bar"。
構文内の余分な空白文字は無視されます。"foo, bar
desc"、" foo , bar desc "、"foo,bar desc" の値はすべて同義です。
サブフィールドは、走査演算子で指定します。例: foo.bar や address.street。