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 のブール値の b フィールドが true の場合は 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。 |
メッセージを走査するときに、フィールドが存在すると見なされるのは、デフォルト以外の値が設定されている場合のみです。
制限事項
個々のサービスでは、ここで定義されているものに加えて、フィルタクエリの構造や制限を指定できます。
注文
Ad Manager API では、List メソッドでの順序指定がサポートされています。orderBy フィールドの構文は、フィールド名のカンマ区切りのリストです。例: "foo,bar"。
デフォルトの並べ替え順序は昇順です。フィールドに降順を指定するには、接尾辞 " desc" を追加します。例: "foo desc, bar"。
構文内の冗長なスペース文字は無視されます。"foo, bar desc"、" foo , bar desc "、"foo,bar desc" の値はすべて同義です。
サブフィールドは、走査演算子で指定します。例: foo.bar、address.street。