このガイドでは、リストフィルタの構文と、さまざまなリソースタイプをフィルタリングする方法について説明します。
一部の API メソッドでは、フィルタを使用して、レスポンスで返されるリソースを制限できます。
概要
このセクションでは、リストフィルタの構文構造について簡単に説明します。
フィルタは
expressionを含む文字列です。expressionは、比較を組み合わせたブール値です。expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )comparisonは、リソース フィールドを値と一致させます。一般的な比較演算子はすべて使用できます。comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"has演算子はコロン（:）で、文字列や繰り返しフィールドで使用できます。詳しくは、演算子ありをご覧ください。フィルタでは次の種類の値を使用できます。
- 数字
- 文字列
- かっこで囲まれた式
value = number| string | "*" | "(" expression ")"文字列は以下を表すことができます。
- 任意のテキスト
- ブール値
- 列挙値
- タイムスタンプ
ブール式
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
オペレーションは次の順序で行われます。
NOTORAND
たとえば、次の式は同じ意味になります。
a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)
比較の間の AND 演算子は省略できます。たとえば、次のフィルタは同じです。
c=d AND e=f
c=d e=f
NOT の代わりにハイフン（-）を使用することもできます。ハイフン（-）と次の比較の間にスペースを挿入することはできません。たとえば、次のフィルタは同じです。
NOT e=f
-e=f
比較
このセクションでは、次のような "name OP value" の比較について説明します。
comparison = name OP value
ここで
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"
比較の左側は API リソース フィールドのパス名です。
名前は、ピリオド（.）で連結された一連のリソース識別子で構成されます。各フィールド識別子の後に、そのフィールドの次のレベルの名前が続きます。たとえば、リソースに複雑なフィールド item があり、その中に別の複雑なフィールド tool があり、その中に shape というフィールドがあるとします。このリソースのフィルタでは、item.tool.shape という名前のシェイプを参照します。
通常、右側はフィールドの型に変換され、それと比較されるスカラー値です。詳細については、値リテラルのタイプをご覧ください。
比較の右側は、リテラル値のみを含むリテラル値またはブール値（NOT の有無にかかわらず）のかっこで囲まれたブール値の組み合わせとして表現することもできます。左側の名前と比較演算子が各値に適用されます。たとえば、次のフィルタは同じです。
deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"
次に、2 つの同等のフィルタを使用する複雑な例を示します。
deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))
(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")
値のリテラル型
比較演算子の右側の値は、数値リテラルと文字列リテラルに分類されます。
数値
このセクションでは、数値リテラルの表現について説明します。
| 種類 | 定義 | 例 |
|---|---|---|
| 二塁打 | 小数点を含む数値は、記号（-）の有無にかかわらず Double 型として扱われます。 |
|
| Integer | 小数点のない数値は、符号（-）の有無にかかわらず、整数として扱われます。 |
|
文字列
このセクションでは、フィルタ構文で文字列リテラルとして記述できる型について説明します。
| 種類 | 定義 | 例 |
|---|---|---|
| ブール値 | TRUE または FALSE（大文字と小文字は区別されません）。 |
|
| 列挙型 | 列挙型のリテラルの名前。列挙型では大文字と小文字が区別されます。 |
FINALIZED は Finalized とは異なる。
|
| 文字列 | UTF-8 でエンコードされたテキストまたは 7 ビット ASCII テキストを含む文字列。 埋め込み引用符はバックスラッシュでエスケープする必要があります。引用符で囲まれていない空白文字を含む文字列は、文字列を空白文字で区切った後、すべての単語の中で暗黙的に「AND」として扱われます。 |
|
| タイムスタンプ | ISO8601 標準形式の文字列。 |
"2014-10-02T15:01:23.045Z"
|
比較演算子
比較演算子は次のとおりです。
- 以下:
"<=" - 未満:
"<" - 以上:
">=" - 超える:
">" - 等しくない:
"!=" - 次と等しい:
"=" - 次を含む:
":"
これらの演算子は、Double、Integer、Boolean、Enum、Timestamp の値タイプに適用されます。
演算子あり
HAS 演算子（:）は、次のフィールドに対する特別な演算に使用できます。
- 部分文字列
HAS演算子を使用して文字列列の値を文字列と比較する場合、この演算子は部分文字列演算として機能します。たとえば、name:"abcd"は、nameが"abcd"を含む文字列であるすべてのインスタンスを返します。- 存在の確認
HAS演算子を特殊文字*とともに使用すると、HAS演算子は null 以外の値をチェックします。たとえば、name:*は、nameが null 以外、欠損、未定義のいずれでもないすべてのインスタンスを返します。HAS演算子を文字列以外の値で使用すると、EQUALS（=）演算子と同じように動作します。たとえば、isCompleted:trueはisCompleted = trueと同じように動作します。- 繰り返しフィールド
次の条件を満たす限り、
HAS（:）演算子を使用して繰り返し API リソース フィールドをフィルタリングできます。- フィールド識別子のパスに、繰り返しコンポーネントが 1 つだけ存在する
- フィールドパスの最後の識別子はスカラー型です。
ネストされた繰り返しフィールドでのフィルタリングはサポートされていません。
次の例をご覧ください。
itemのcolorsフィールドには、"red"、"blue"、"yellow"などの文字列値が格納されます。item.colors:("red")は、colorsフィールドの値が"red"のすべてのアイテムを返します。item.colors:("red" "yellow")は、colorsフィールドに"red"と"yellow"の両方を持つすべてのアイテムを返します。item.colors:("red" OR "yellow")は、colorsフィールドに"red"または"yellow"を含むすべてのアイテムを返します。
itemには繰り返しtoolsフィールドもあります。これは、スカラー フィールドshape（値は"square"または"round"）を持つ複合オブジェクトです。item.tools.shape:("square")は、"square"シェーピングされたツールを持つすべてのアイテムを返します。item.tools.shape:("square" "round")は、"square"形ツールと"round"形ツールの両方を持つすべてのアイテムを返します。item.tools.shape:("square" OR "round")は、"square"シェイプツールまたは"round"シェイプツールを持つすべてのアイテムを返します。
未入力のネストされたフィールド
ネストされたフィールドは、ルートレベル フィールドのサブフィールドです。たとえば、item.tools.shape の shape は items.tools のネストされたフィールドです。
ルートレベルのフィールドはデフォルトで false に設定されます。ネストされたフィールドはデフォルトで入力されません。
値が入力されていないネストされたフィールドを含むオブジェクトは、ネガティブ フィルタ（!=）では返されません。
次の例をご覧ください。
item.tools に size 列挙型があり、その値は "SMALL"、"MEDIUM"、または "LARGE" に設定できます。
該当するものがある場合:
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
},
{
"name": "item3"
}
ネガティブ フィルタ "tools.size != SMALL" を使用して items.list を呼び出すと、次の結果が返されます。
{
"items": [
{
"name": "item1",
"tools": {
"size": "MEDIUM"
}
},
{
"name": "item2",
"tools": {
"size": "LARGE"
}
}
]
}
item3 に item.tools.size が設定されていないため、ネガティブ フィルタは item3 オブジェクトを返しません。
例
| 例 | 説明 |
|---|---|
externalDealId = "123456789" |
文字列値「123456789」の externalDealId。 |
advertiserId:93641 |
整数値 93641 の advertiserId。 |
isSetupComplete = true |
isSetupComplete は TRUE と等しい。 |
updateTime > "2018-02-14T11:09:19.378Z" |
updateTime が 2018 年 2 月 14 日 11:09:19.378 UTC より後 |
displayName = "proposal" AND proposalRevision = 3 |
displayName 文字列の値が「proposal」であり、かつ、ProposalRevision が 3 に等しくなります。 |
displayName = "proposal" OR proposalRevision = 3 |
displayName に文字列値が「proposal」であるか、proposal リビジョンが 3 に等しい。 |
NOT displayName = "proposal" |
displayName は「proposal」と等しくありません。 |
proposalState = (PROPOSED OR BUYER_ACCEPTED) |
proposalState に PROPOSED または BUYER_ACCEPTED と等しい列挙値がある。 |
proposalState = (PROPOSED AND BUYER_ACCEPTED) |
proposalState に PROPOSED かつ BUYER_ACCEPTED に等しい列挙値がある |
dealName = Test Deal |
INVALID 式 |
dealName = "Test Deal" |
dealName は「Test Deal」となります。 |
dealName = (Test Deal) |
dealName は「Test」と「Deal」に相当します。 |
dealName = ("Test1" OR "Test2") |
dealName は「Test1」または「Test2」と等しくなります。 |
dealName:* |
dealName is not null. |
dealName:"test" |
dealName には部分文字列「test」が含まれます。 |
dealName:("A B") |
dealName には部分文字列「A B」が含まれます。 |
dealName:(A B) |
dealName には部分文字列「A」と部分文字列「B」が含まれます。 |
dealName:("A" OR "B" AND "C") |
dealName は部分文字列「A」または「B」を含み、さらに部分文字列「C」を含む |
dealName:("A B" C) |
dealName には部分文字列「A B」が含まれ、部分文字列「C」も含まれます。 |
dealName:("A B" OR C D) |
dealName は、部分文字列「A B」または「C」を含み、部分文字列「D」も含みます。 |
dealName:(NOT "A" B) |
dealName は部分文字列「A」を含まず、部分文字列「B」も含みます。 |
dealName:(NOT "A" OR "B") |
dealName に部分文字列「A」が含まれていないか、部分文字列「B」が含まれています。 |