$filter パラメーター

$filter は、最も多彩な OData パラメーターであり、多数の演算子があります。

組み込みの論理演算子と数学演算子があり、結果セット内のプロパティーと併用すると、フィルター式を作成できます。$filter 式を正しく使用するには、いくつかの表記規則に従う必要があります。プロパティーは、API 応答に含まれているフィールドです。以下に、ガイドラインをいくつか示します。

特定の API 呼び出しでどのプロパティーが使用できるかを確認するには、レスポンス・クラス・モデルを参照してください。
文字列は一重引用符で囲む必要があり、プロパティー、演算子、キーワードは囲む必要がありません。
```
$filter=Name eq 'Altoro'
```
式で使用したいプロパティーが別のプロパティーにネストされていることがあります。例えば、Get /api/v4/Scans 呼び出しで Scan JSON オブジェクトが返された場合、JSON オブジェクトは LatestExecution プロパティーに組み込まれています。このネストされたフィールドを参照するには、スラッシュを使用します。例えば、最新のスキャン実行状態が「準備完了」であるスキャンのみを返すには、次のようにスラッシュを使用します。
```
$filter=LatestExecution/Status eq 'Ready'
```
次のように、他の OData パラメーターにも使用できます。
```
$orderby=LatestExecution/ScanEndTime desc
```
日付を比較に使用する場合は、EDM 形式 (2018-06-26T09:13:28z など) にする必要があります。そのため、特定の日付以降に作成されたスキャンを取得するには、「CreatedAt」フィールドを特定の日付と比較し、EDM 日付文字列を DateTime オブジェクトに変換します。
```
$filter=CreatedAt gt 2018-07-31T07:30:00z
```

演算子

前出の例では「等しい」に eq、「より大」に gt などの演算子を使用しています。以下に、よく使用される論理演算子と数学演算子をいくつか示します。OData 演算子が漏れなく記載されたリストについては、参考資料の OData v3 仕様を参照してください。

表 1. 演算子
グループ	オペレーター	意味
リレーショナル	`gt`	次より大きい:
	`ge`	以上
	`lt`	次より小さい
	`le`	以下
	`isof`	型テスト
等価	`eq`	次と等しい
等価	`ne`	等しくない
条件付き AND	`and`	論理 AND
条件付き OR	`or`	論理 OR

lambda 演算子

lambda 演算子を使用すると、高度な式フィルターを構築できます。lambda 演算子には、any と all の 2 つがあります。これらは、操作対象の値の配列を含むフィールドで使用されます。any 式では、true と評価された結果が少なくとも 1 つあれば、true に評価されます。演算子 all が true を返すためには、すべての結果が true に評価される必要があります。

例えば、/api/v4/Apps という API について考えてみます。各アプリケーションが「ComplianceStatuses」の配列として返され、アプリケーションに関連付けられたポリシーごとに 1 つずつ ComplianceStatuses があります。

失敗したポリシーがないアプリケーションをすべて返すには、次のようにします。
```
$filter=ComplianceStatuses/all(d:d/Compliant eq true)
```
失敗したポリシーが少なくとも 1 つあるアプリケーションをすべて返すには、次のようにします。
```
$filter=ComplianceStatuses/any(d:d/Compliant eq false)
```

文字列演算子

文字列同士が一字一句違わないというのはあまりありません。そこで便利なのが文字列演算子です。通常、substring や endswith などのストリング関数が必要になります。OData には、このような文字列関数が含まれています。以下のリストは、OData 仕様に記載されているものです。

表 2. 文字列演算子
ストリング関数	例	意味
`contains`	`contains(Name,'Altoro')`	文字列にサブストリングが含まれている場合に、true を返します。
`endswith`	`endswith(Name,'Mutual')`	文字列がサブストリングで終了している場合に、true を返します。
`startswith`	`startswith(Name,'Altoro')`	文字列がサブストリングで始まっている場合に、true を返します。
`length`	`length(Name) gt 10`	文字列 (または配列) の長さを返します。
`indexof`	`indexof(Name,'Altoro') eq 1`	サブストリングの先頭のインデックスを返します。
`substring`	`substring(Name,1) eq 'toro Mutual'`	インデックスで始まる文字列を返します。
`tolower`	`tolower(Name) eq 'altoro mutual'`	文字列を小文字に変換します。
`toupper`	`toupper(Name) eq 'ALTORO MUTUAL'`	文字列を大文字に変換します。
`trim`	`trim(Name) eq 'Altoro Mutual'`	末尾と先頭の空白をトリムします。
`concat`	`concat(Name,' Financial') eq 'Altoro Mutual Financial'`	2 つの文字列を連結します。

日付固有の関数

日付固有の関数のほとんどは、日付オブジェクトから日付のうち月の日にちなど特定の部分を返します。

表 3. 日付関数
Date 関数	例
`year`	`year(ScanEndTime) eq 2024`
`month`	`month(ScanEndTime) eq 12`
`day`	`day(ScanEndTime) eq 8`
`hour`	`hour(ScanEndTime) eq 1`
`minute`	`minute(ScanEndTime) eq 0`
`second`	`second(ScanEndTime) eq 0`

数学関数

表 4. 数学関数
数学関数	意味
`round`	最も近い整数に四捨五入します
`floor`	最も近い整数に切り捨てます
`ceiling`	最も近い整数に切り上げます