このガイドでは、リスト フィルタの構文と、さまざまなフィルタ オプションを使用して、 学びます。
一部の API メソッドでは、フィルタを受け入れて、 レスポンスが返されます。
概要
このセクションでは、リストフィルタの構文構造の概要を説明します。
フィルタは、
expression
を含む文字列です。expression
はブール値です。 比較の組み合わせ:expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison } expression = ( expression )
comparison
は、リソース フィールドと値を照合します。すべての よく使われる比較演算子です。comparison = name OP value OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
has
演算子であるコロン(:
)は、文字列に対して使用できます。 表示されます。詳しくは、演算子があるセクションをご覧ください。フィルタでは、次の型の値を使用できます。
- Numbers
- 文字列
- かっこで囲まれた式
value = number| string | "*" | "(" expression ")"
文字列は以下を表すことができます。
- 任意のテキスト
- ブール値
- 列挙値
- タイムスタンプ
ブール式
expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}
オペレーションは次の順序で行われます。
NOT
OR
AND
たとえば、次の式は同じ内容を表します。
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
があり、そのフィールドに別の
shape
という名前のフィールドを持つ複合フィールド tool
。フィルタ内:
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"
|
比較演算子
比較演算子は次のとおりです。
- 以下:
"<="
- 未満:
"<"
- 以上:
">="
- 超える:
">"
- 等しくない:
"!="
- 等しい:
"="
- 添付コンテンツ:
":"
これらの演算子は倍精度浮動小数点値、整数値、ブール値値、列挙型値、タイムスタンプ値に適用されます できます。
演算子があります
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")
は、値が"red"
のすべてのアイテムを返します。colors
フィールド。item.colors:("red" "yellow")
は、"red"
とcolors
フィールドに"yellow"
を設定します。item.colors:("red" OR "yellow")
は、「"red"
」またはcolors
フィールドに"yellow"
を設定します。
item
には、スカラーを使用した複合オブジェクトである繰り返しtools
フィールドもあります。 フィールドshape
。その値は"square"
または"round"
です。item.tools.shape:("square")
は、形状が"square"
のアイテムをすべて返します できます。item.tools.shape:("square" "round")
は、両方の属性を持つすべてのアイテムを返します。"square"
シェイプと"round"
シェイプ ツールの 2 つがあります。item.tools.shape:("square" OR "round")
は、"square"
シェイプツールまたは"round"
シェイプツール。
ネストされたフィールドが入力されていない
ネストされたフィールドは、ルートレベルのフィールドのサブフィールドです。たとえば、shape
item.tools.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」が同一ですAND subscriptionRevision が 3 に等しい。 |
displayName = "proposal" OR proposalRevision = 3 |
displayName の文字列値は「proposal」です。または、ProposalRevision が 3 に等しい。 |
NOT displayName = "proposal" |
displayName は「プロポーザル」と等しくありません。 |
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」と等しい「取引」に相当します |
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」のいずれかが含まれる部分文字列「D」も含まれます。 |
dealName:(NOT "A" B) |
dealName に部分文字列「A」が含まれていません部分文字列「B」も含まれます。 |
dealName:(NOT "A" OR "B") |
dealName に部分文字列「A」が含まれていません部分文字列「B」が含まれるかどうかがわかります。 |