$filter 參數

$filter 是最強大的 OData 參數,此參數具有許多運算子。

搭配結果集當中的內容使用的內建邏輯和數學運算子,可用來建立過濾運算式。如果要妥善使用 $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 規格」。
1. 運算子
群組 Operator 意義
關聯式 gt 大於
ge 大於或等於
lt 少於
le 小於或等於
isof 類型測試
相等 eq 等於
ne 不等於
條件式 AND and 邏輯 And
條件式 OR or 邏輯 Or

Lambda 運算子

Lambda 運算子會啟用更進階的運算式過濾。lambda 運算子有兩個,anyall。它們用於包含需要操作之值陣列的欄位。如果至少有一個結果在其運算式中評估為 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)

字串運算子

字串運算子相當有用,因為大部分使用案例都不會牽涉到完全相等的字串。通常您需要像 substringendswith 之類的字串函數。這些函數內含在 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' 連結兩個字串。

日期特定函數

這些函數大部分會傳回日期的特定部分,例如日期物件的一個月中的某一天。
3. 日期函數
日期函數 例子
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 無條件進位至最接近的整數