フィルター構文

API検索リクエスト（ HTTP GET）で返される結果を制限するために、リソースのリストを返すほとんどのAPIエンドポイントは パラメータをサポートしている。 IBM® QRadar® リソースのリストを返すAPIエンドポイントのほとんどは、 filter パラメータをサポートしています。

filter パラメーターの構文は、そのパラメーターをサポートしているすべてのエンドポイントで一貫性があります。 エンドポイントの資料を参照し、フィルター・パラメーターがそれに適用されるかどうかを判別してください。 フィルター構文の制限事項はすべて、そのエンドポイントの説明に記載されています。 照会パラメーターは、送信前に二重 URL エンコードする必要があります。

比較演算子

フィルター比較演算子の表で、フィルター・パラメーターの一部として使用可能な比較演算子について説明します。

表 1. フィルター比較演算子
演算子 説明 フィルター構文の例
= ID と、返される指定値が等しい。 status=CLOSED であるオフェンスを検索するには、以下の構文を使用します。

GET /api/siem/offenses?filter=status%3DCLOSED
> ID が指定値より大きい。 credibility > 3 であるオフェンスを検索するには、以下の構文を使用します。

/api/siem/offenses?filter=credibility%20%3E%203
< Identifierが指定値より小さい。 magnitude < 9 であるオフェンスを検索するには、以下の構文を使用します。

/api/siem/offenses?filter=magnitude%20%3C%209
<= ID が指定値より小さいか等しい。 id <= 1004 であるオフェンスを検索するには、以下の構文を使用します。

/api/asset_model/properties?filter=id%20%3C%3D%201004
>= ID が指定値より大きいか等しい。

scanProfileId >= 3 であるオフェンスを検索するには、以下の構文を使用します。

/api/scanner/scanprofiles?filter=scanProfileId%20%3E%3D%203

!=,

<>,

^=

 ID が指定値と等しくない。

以下の例では、5 と等しくないすべての ID がフィルタリングされます。

/api/siem/offenses?filter=id%20!%3D%205

/api/siem/offenses?filter=id%20%3C%3E%205

/api/siem/offenses?filter=id%20%5E%3D%205
in ID が、リスト内の指定値の少なくとも 1 つと等しい。 構文: id in (1001,1111,1200)

例:/api/asset_model/assets?filter=id%20in%20(1001%2C1111%2C1200)
not in ID が、リスト内の指定された値のいずれとも等しくない。 構文: id not in (1001,1002,1003):

例:/api/asset_model/saved_searches?filter=id%20not%20in%20(14%2C20%2C1003)
between … and … ID が、2 つの指定値の間にある。 構文: id between 0 and 3:

例:/api/siem/offenses?filter=id%20between%200%20and%203
not between … and … 識別子が指定された2つの値の間にない。 構文: id not between 30 and 31:

例:/api/siem/offenses?filter=id%20not%20between%2030%20and%2031
is null ID がヌルである。 構文: assigned_to is null:

例:/api/siem/offenses?filter=assigned_to%20is%20null
is not null ID がヌルではない。 構文: assigned_to is not null:

例:/api/siem/offenses?filter=assigned_to%20is%20not%20null

ヌル値と比較演算子

フィルタリングしたフィールドに「ヌル」値がある場合、比較演算子は以下のように動作します。

「=」、「> 」、「> =」、「<」、「< =」、「IN」および「BETWEEN」オペレーターは常にfalseを返します。
「! =」、「<>」、「^ =」、「NOT BETWEEN」および「NOT IN」は常にtrueを返します。

ヌル値をテストする最良の方法は、「is null」演算子または「is not null」演算子を使用することです。

論理演算子

副次式で論理演算を実行するには、論理演算子の OR、AND、および NOT を使用します。 以下の表に、フィルターで論理演算子を使用する方法の例を示します。

演算子 説明 例
or 2 つの副次式で論理 OR 演算を実行します。 副次式は比較ノードまたは他の論理ノードである場合があります。 assigned_toはnullまたはid = 111ではない場合：

/api/siem/offenses?filter=assigned_to%20is%20not%20null%20or%20id%20%3D%20111
and 2 つの副次式で論理 AND 演算を実行します。 副次式は比較ノードまたは他の論理ノードである場合があります。 assigned_to is not null AND id = 111 ：

/api/siem/offenses?filter=assigned_to%20is%20not%20null%20and%20id%20%3D%20111
not 副次式で論理 NOT 演算を実行します。 protected =true and not id in (111,112,113)

/api/siem/offenses?filter=protected%20%3D%20true%20and%20not%20id%20in%20(111%2C112%2C113)

比較のための JSON フィールドの指定

以下の表では、フィルターの比較演算子で使用する際の JSON フィールドの指定方法について説明します。

JSON フィールドの例 説明 例 
{
"name": "Proprietary Data",
"element_type": "ALN"
}
 返されるオブジェクト内のフィールドにフィルターを直接適用する場合、そのフィールドは名前で指定します。

name = "Proprietary Data"

GET /api/reference_data/sets?filter=name%20%3D%20%22Proprietary%20Data%22

 
{
 "description": "String",
 "duration": {
  "days": 42,
  "hours": 42,
  "minutes": 42,
  "months": 42,
  "seconds": 42.5,
  "years": 42
  }
}

サブオブジェクト内にネストされているフィールドにフィルターを適用する場合、括弧を使用して内部フィールドを指定します。

duration(days) >= 20

GET /api/scanner/scanprofiles?filter=duration(days)%20%3E%3D%201

 
["events","flows","simarc"]
 ストリング、数値、ブールなど、フィールド・ラベルが存在しない単純な JSON タイプの場合は、. 演算子を使用します。

.= events

GET /api/ariel/databases?filter=.%3D%20events

フィルターでのストリング値および数値の指定

非英数字の値があるストリングをフィルタリングする場合、ターゲット・ストリングを引用符で囲む必要があります。 数値をフィルタリングする場合、必要に応じて以下の特殊な値を使用できます。

  • 正符号 (+) または負符号 (-) で始まる。
  • 小数点を含むか、小数点で始まる。
  • e 表記による指数を含む。

CONTAINS 演算子の使用による複合オブジェクトのフィルタリング

複合オブジェクトをフィルタリングするには、CONTAINS 演算子を使用します。 CONTAINS 演算子を使用して、リストやマップの内容をテストします。 演算子の左側は、標準形式の ID (例えば x(y(z))) です。 ID は、リスト、マップ、またはコレクションであるエレメントを指す必要があります。 演算子の右側は、リスト内のオブジェクトがどのように一致する必要があるかを指定する式です。 CONTAINS 演算子の使用には、以下の 2 つの基本的なユース・ケースがあります。

  • 調査対象のリストに、ストリングや数値のような単純エレメントが含まれている。
  • リストに複合オブジェクトが含まれている。
単純タイプを含むリスト
ストリングや数値などの単純タイプを含むリストの場合、式は同じタイプの値です。 単一比較の場合、括弧は必要ありません。

フィルターの値フィールドにストリングとして ftp がある、アセットの保存済み検索のみを要求する場合:

GET /api/asset_model/saved_searches?filter=filters%20contains%20value%20%3D%20ftp

インターフェースに IP アドレス「192.0.2.0」が含まれているアセットを要求するには、以下のようにします。

GET /api/asset_model/assets?filter=interfaces%20contains%20ip_addresses%20contains%20value%20%3D%20%192.0.2.0%22

複合オブジェクトを含むリスト

複合オブジェクトを含むリストの場合、式は、リスト内のオブジェクトに対する完全なフィルター式です。 このサブフィルター式では、他のすべてのフィルターと同じ構文を使用します。 サブフィルターで任意の演算子を使用して、元のリスト内のサブリストをテストできます。 この式内の ID は、CONTAINS 演算子の作用対象であるリスト内のオブジェクトに関連します。 複合サブフィルター式には、括弧が必要です。

フィールドvalue = 14およびGreater thanオペレーターを持つ資産のみを要求するには、フィルターfilters contains (value = 14 or operator = "Greater than")を適用します。 このフィルターは、リスト内の最初のエレメントと最後のエレメントを返します。

GET /api/asset_model/saved_searches?filter=filters%20contains%20(value%20%3D%2014%20and%20operator%20%3D%20%22Greater%20than%22)

3 より小さい ID 値がある送信元アドレスを含むオフェンスを見つけるには、以下のフィルターを適用します。

GET /api/siem/offenses?filter=source_address_ids%20contains%20(.%3C3)

LIKE 演算子

ストリングの部分的一致を検索するには、LIKE 演算子を使用します。

LIKE 演算子では、形式として identifier like "expression" を使用します。 式を囲む引用符は必須です。 単一引用符および二重引用符がサポートされています。 LIKE キーワードでは、大/小文字を区別した付き合わせを行います。

以下のワイルドカード文字がサポートされています。 ストリングでワイルドカード文字を使用する場合は、その文字をエスケープする必要があります。

ワイルドカード文字 説明
% ゼロ以上の文字のストリングの照合を行います。
_ 任意の単一文字の照合を行います。
例えば、以下のデータ・コレクションを返す API について考えてみます。
GET /path/to/api
[
 {
 "hostname": "server.domain1"
 },
 {
 "hostname": "server.domain2"
 },
 {
 "hostname": "SERVER.domain"
 },
 {
 "hostname": "server.DOMAIN"
 }
]

同一の式内で複数のワイルドカード文字を組み合わせることができます。 例えば、domain1またはdomain2にあるサーバーを検索するには、次の式hostname LIKE "%.domain_"を使用します。

GET /path/to/api?filter=hostname%20LIKE%20%22%25.domain_%22 
[
 {
 "hostname": "server.domain1"
 },
 {
 "hostname": "server.domain2"
 }
]

下線 (_) に一致する末尾文字がないため、SERVER.domain は返されないことに注意してください。

ILIKE 演算子

大/小文字を区別しない部分ストリングの一致を検索するには、ILIKE 演算子を使用します。

ILIKE 演算子は LIKE 演算子に似ていますが、大/小文字が区別されません。 例えば、以下のデータ・コレクションを返す API について考えてみます。
GET /path/to/api
[
 {
 "hostname": "server.domain1"
 },
 {
 "hostname": "server.domain2"
 },
 {
 "hostname": "SERVER.domain"
 },
 {
 "hostname": "server.DOMAIN"
 }
]
hostname ILIKE "server.domain" という式でフィルターに掛けると、以下のデータ・コレクションが生成されます。
GET /path/to/api?filter=hostname%20ILIKE%20%22server.domain%22'
[
 {
 "hostname": "SERVER.domain"
 },
 {
 "hostname": "server.DOMAIN"
 }
]