適用於雲端的 Defender 應用程式 REST API
本文說明如何透過 HTTPS 與 Defender for Cloud Apps 互動。
Microsoft Defender for Cloud Apps API 可透過 REST API 端點，以程式設計方式存取 Defender for Cloud Apps。 應用程式可以使用 API 對 Defender for Cloud Apps 資料和物件執行讀取和更新作業。 例如，Defender for Cloud Apps API 支援下列使用者物件的常見作業：
- 上傳用於雲端探索的記錄檔
- 產生區塊腳本
- 列出活動和警示
- 關閉或解決警示
API URL 結構
若要使用 Defender for Cloud Apps API，您必須先從租使用者取得 API URL。 API URL 使用下列格式： https://<portal_url>/api/<endpoint>。
若要取得租使用者的 Defender for Cloud Apps API URL，請執行下列步驟：
在 Microsoft Defender 入口網站中，選取 [設定]。 然後選擇 [雲端應用程式]。 在 [系統] 底下，選取 [ 關於]。
在關於畫面的 Defender for Cloud Apps 中，您可以看到 API URL。
取得 API URL 之後，請將後綴新 /api 增至其中，以取得您的 API URL。 例如，如果您入口網站的網址是 https://mytenant.us2.contoso.com，則您的 API URL 是 https://mytenant.us2.portal.cloudappsecurity.com/api。
API 令牌
Defender for Cloud Apps 在伺服器的所有 API 要求標頭中需要 API 令牌，如下所示：
Authorization: Token <your_token_key>
其中 <your_token_key> 是您的個人 API 令牌。
如需 API 令牌的詳細資訊，請 參閱管理 API 令牌。
API 令牌 - 範例
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"
支援哪些動作？
下表描述支援的動作：
| 資源 | HTTP 動詞命令 | URI 路由 |
|---|---|---|
| 活動 | GET 或 POST | /api/v1/activities/ |
| 警示 | GET 或 POST | /api/v1/alerts/ |
| 數據擴充 | GET、POST 或 DELETE | /api/subnet/ |
| 實體 | GET 或 POST | /api/v1/entities/ |
| 檔案 | GET 或 POST | /api/v1/files/ |
其中 Resource 代表一組相關實體。
支援哪些欄位類型？
下表描述支援的欄位型態：
| 欄位 | 描述 |
|---|---|
| 字串 | 文字字串 |
| 布林值 | 代表 true/false 的布爾值 |
| 整數 | 32 位帶正負號的整數 |
| 時間戳 | Epoch 後的毫秒數 |
時間 戳
在 Defender for Cloud Apps API 中提及時間戳時，請參閱以毫秒為單位的 Unix 時間戳。 此時間戳取決於自 1970-01-01 0：00：00 起的毫秒數。 您可以使用 get-date PowerShell Cmdlet 將日期轉換成時間戳。
限制
您可以在要求中提供 limit 參數，以選擇限制您的要求。
提供 limit 參数時支援下列方法：
- 具有標頭的 URL 編碼 (
Content-Type: application/x-www-form-urlencoded) - 表單資料
- JSON 主體 (與
Content-Type: multipart/form-data適當的界限標頭)
注意事項
- 如果未提供任何限制，則會設定預設值 100。
- 使用 API 令牌所發出之所有要求的回應限制為最多 100 個專案。
- 所有 API 要求的節流限制是每個租使用者每分鐘 30 個要求。
篩選
當您有大量結果時，您會發現使用篩選器微調要求會很有用。 本節描述可用於篩選條件的 和運算符結構。
結構
我們的某些 API 端點在執行查詢時支持篩選。 在其相關章節中，您會找到一個參考，其中列出該資源所有可用的可篩選欄位和支援的運算符。
大部分的篩選都支援多個值，為您提供功能強大的查詢。 結合篩選條件和運算符時，我們會使用 AND 做為篩選之間的邏輯運算元。
篩選 - 範例
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
"filters": {
"some.field": {
"eq": ["value1", "value2"],
"isset": true
},
"some.field2": {
"gte": 5
}
},
"skip": 5,
"limit": 10
}'
運算子
注意事項
並非所有運算子都與所有篩選相容。
下表描述支援的運算子：
| 運算子 | 回應類型 | 描述 |
|---|---|---|
| 包含 | 字串清單 | 傳回包含其中一個所提供字串的所有相關記錄 |
| deq | 值清單 | 傳回包含一個值且不等於所提供值之一的所有記錄 |
| descendantof | 值清單 | 傳回所有符合其值或子系的相關記錄 |
| doesnotstartwith | 字串清單 | 傳回所有未以每個提供字串開頭的相關記錄 |
| endswith | 字串清單 | 傳回以其中一個提供的字串結尾的所有相關記錄 |
| 情 商 | 值清單 | 傳回包含其中一個所提供值的所有相關記錄 |
| 燃氣輪機 | 單一值 | 傳回其值大於所提供值的所有記錄 |
| gte | 單一值 | 傳回其值大於或等於所提供值的所有記錄 |
| gte_ndays | number | 傳回日期晚於 N 天前的所有記錄 |
| isnotset | 布林值 | 當設定為 「true」 時，傳回指定欄位中沒有值的所有相關記錄 |
| isset | 布林值 | 當設定為 「true」 時，傳回在指定欄位中具有值的所有相關記錄 |
| lt | 單一值 | 傳回其值小於所提供值的所有記錄 |
| lte | 單一值 | 傳回其值小於或等於所提供值的所有記錄 |
| lte_ndays | number | 傳回日期早於 N 天前的所有記錄 |
| ncontains | 字串清單 | 傳回不包含其中一個所提供字串的所有相關記錄 |
| ndescendantof | 值清單 | 傳回所有不相符值或其子系的相關記錄 |
| neq | 值清單 | 傳回未包含所有提供值的所有相關記錄 |
| range | 包含 「start」 和 「end」 欄位的物件清單 | 傳回其中一個所提供範圍內的所有記錄 |
| startswith | 字串清單 | 傳回從其中一個提供的字串開始的所有相關記錄 |
| startswithsingle | 字串 | 傳回以所提供字串開頭的所有相關記錄 |
| 文字 | 字串 | 執行所有記錄的全文搜索 |
後續步驟
如果您遇到任何問題，我們在這裡提供協助。 若要取得產品問題的協助或支援，請 開啟支援票證。