適用於雲端的 Defender 應用程式 REST API

發行項
01/23/2024

本文說明如何透過 HTTPS 與適用於雲端的 Defender Apps 互動。

適用於雲端的 Microsoft Defender Apps API 可讓您透過 REST API 端點以程式設計方式存取適用於雲端的 Defender Apps。應用程式可以使用 API 對適用於雲端的 Defender Apps 資料和物件執行讀取和更新作業。例如，適用於雲端的 Defender Apps API 支援下列使用者物件的常見作業：

上傳 Cloud Discovery 的記錄檔
產生封鎖指令碼
列出活動和警示
關閉或解決警示

API URL 結構

若要使用適用於雲端的 Defender Apps API，您必須先從租使用者取得 API URL。 API URL 使用下列格式： https://<portal_url>/api/<endpoint>。

若要取得租使用者的適用於雲端的 Defender 應用程式 API URL，請執行下列步驟：

在 Microsoft Defender 入口網站中，選取 [設定]。然後選擇 [ 雲端應用程式]。在 [系統] 底下，選取 [關於]。
在 [適用於雲端的 Defender 應用程式] 畫面中，您可以看到 API URL。

取得 API URL 之後，請將後綴新增 /api 至該 URL 以取得您的 API URL。例如，如果您的入口網站的網址是 https://mytenant.us2.contoso.com，則您的 API URL 為 https://mytenant.us2.portal.cloudappsecurity.com/api。

API 權杖

適用於雲端的 Defender 應用程式需要伺服器所有 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/
Files	GET 或 POST	/api/v1/files/

其中 Resource 代表一組相關的實體。

支援哪些欄位類型？

下表描述支援的欄位型態：

欄位	描述
string	文字字串
boolean	代表 true/false 的布爾值
整數	32 位元帶正負號的整數
timestamp	自 epoch 以來的毫秒數

時間戳記

適用於雲端的 Defender 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
}'

操作員

注意

並非所有運算子都與所有篩選相容。

下表描述支援的運算子：

運算子	回應類型	描述
contains	字串清單	傳回包含其中一個所提供字串的所有相關記錄
deq	值清單	傳回包含一個值不等於所提供值的所有記錄
descendantof	值清單	傳回符合值或子系的所有相關記錄
doesnotstartwith	字串清單	傳回不是以每個提供的字串開頭的所有相關記錄
endswith	字串清單	傳回以其中一個提供的字串結尾的所有相關記錄
eq	值清單	傳回包含其中一個所提供值的所有相關記錄
gt	單一值	傳回值大於所提供值的所有記錄
gte	單一值	傳回值大於或等於所提供值的所有記錄
gte_ndays	number	傳回日期比 N 天前晚的所有記錄
isnotset	boolean	當設定為「true」時，傳回在指定字段中沒有值的所有相關記錄
isset	boolean	當設定為「true」時，傳回在指定欄位中具有值的所有相關記錄
lt	單一值	傳回值小於所提供值的所有記錄
lte	單一值	傳回值小於或等於所提供值的所有記錄
lte_ndays	number	傳回日期早於 N 天前的所有記錄
ncontains	字串清單	傳回不包含其中一個所提供字串的所有相關記錄
ndescendantof	值清單	傳回所有相關記錄，但不符合這些記錄的值或子系
neq	值清單	傳回所有相關記錄，但不包含所有提供的值
range	包含「start」和「end」欄位的物件清單	傳回其中一個提供範圍中的所有記錄
startswith	字串清單	傳回以其中一個提供的字串開頭的所有相關記錄
startswithsingle	string	傳回從提供的字串開始的所有相關記錄
text	string	執行所有記錄的全文搜索

下一步

API 驗證

如果您遇到任何問題，我們會在這裡提供説明。若要取得產品問題的協助或支援，請開啟支援票證。

Share via