$filter 參數

搭配結果集當中的內容使用的內建邏輯和數學運算子，可用來建立過濾運算式。如果要妥善使用 $filter 運算式，則必須遵循一些慣例。Properties 是 API 回應中包含的欄位。以下是一些準則：

如果要尋找哪些內容可讓您在特定 API 呼叫中使用，請參閱回應類別模型。
字串必須以單引號括住，內容、運算子和關鍵字則不需要：
```
$filter=Name eq 'Altoro'
```
有時候，您想要在運算式中使用的內容，是以巢狀方式置於其他內容中。例如，在 Get /api/v4/Scans 呼叫中傳回的 Scan JSON 物件在其 LatestExecution 內容中有內嵌的 JSON 物件。如果要參照此巢狀欄位，請使用斜線。例如，若只要傳回在其中最新掃描執行狀態為 Ready 的掃描，請使用斜線：
```
$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 規格」。

Lambda 運算子會啟用更進階的運算式過濾。lambda 運算子有兩個，any 和 all。它們用於包含需要操作之值陣列的欄位。如果至少有一個結果在其運算式中評估為 True，則 any 評估為 True。所有結果都必須評估為 True，all 運算子才會傳回 True。

例如，考量 /api/v4/Apps API，每個應用程式以 ComplianceStatuses 的陣列傳回，各用於與應用程式相關聯的原則。

如果要傳回沒有失敗原則的所有應用程式：
```
$filter=ComplianceStatuses/all(d:d/Compliant eq true)
```
如果要傳回具有至少一個失敗原則的所有應用程式：
```
$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'`	連結兩個字串。

這些函數大部分會傳回日期的特定部分，例如日期物件的一個月中的某一天。