Cloud App Security REST APICloud App Security REST API

適用於:Microsoft Cloud App SecurityApplies to: Microsoft Cloud App Security

重要

Microsoft 的威脅防護產品名稱即將變更。Threat protection product names from Microsoft are changing. 如需有關此變更的詳細資訊與其他更新,請參閱這裡Read more about this and other updates here. 我們將在不久的將來更新產品與文件中的名稱。We'll be updating names in products and in the docs in the near future.

本文說明如何透過 HTTPS 與 Cloud App Security 互動。This article describes how to interact with Cloud App Security over HTTPS.

Microsoft Cloud App Security API 可利用程式設計方式透過 REST API 端點存取 Cloud App Security。The Microsoft Cloud App Security API provides programmatic access to Cloud App Security through REST API endpoints. 應用程式可以使用 API,在 Cloud App Security 資料和物件上執行讀取和更新作業。Applications can use the API to perform read and update operations on Cloud App Security data and objects. 例如,Cloud App Security API 支援使用者物件的下列常見作業:For example, the Cloud App Security API supports the following common operations for a user object:

  • 上傳 Cloud Discovery 的記錄檔Upload log files for Cloud Discovery
  • 產生封鎖指令碼Generate block scripts
  • 列出活動和警示List activities and alerts
  • 關閉或解決警示Dismiss or resolve alerts

API URL 結構API URL structure

若要使用 Cloud App Security API,您必須先從您的租使用者取得 API URL。To use the Cloud App Security API, you must first obtain the API URL from your tenant. API URL 會使用下列格式: https://<portal_url>/api/<endpoint>The API URL uses the following format: https://<portal_url>/api/<endpoint>.

若要取得租使用者的 Cloud App Security 入口網站 URL,請執行下列步驟:To obtain the Cloud App Security portal URL for your tenant, do the following steps:

  1. 在 Cloud App Security 入口網站中,按一下功能表列中的問號圖示In the Cloud App Security portal, click the question mark icon in the menu bar. 然後,選取 [關於]****。Then, select About.

    按一下 [關於]

  2. 在 [關於] 畫面的 [Cloud App Security] 中,您可以看到入口網站 url。In the Cloud App Security about screen, you can see the portal url.

    檢視您的資料中心

當您有入口網站 url 之後,請在 /api 其中新增尾碼以取得您的 API url。Once you have the portal url, add the /api suffix to it to obtain your API URL. 例如,如果您的入口網站 URL 為 https://mytenant.us2.contoso.com ,則您的 API url 為 https://mytenant.us2.contoso.com/apiFor example, if your portal's URL is https://mytenant.us2.contoso.com, then your API URL is https://mytenant.us2.contoso.com/api.

API 權杖API tokens

Cloud App Security 需要伺服器的所有 API 要求標頭中的 API 權杖,如下所示:Cloud App Security requires an API token in the header of all API requests to the server, such as the following:

Authorization: Token <your_token_key>

其中 <your_token_key> 是您的個人 API 權杖。Where <your_token_key> is your personal API token.

如需 API 權杖的詳細資訊,請參閱 管理 api 權杖For more information about API tokens, see Managing API tokens.

範例Example

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.contoso.com/api/example-endpoint"

支援哪些動作?What actions are supported?

下表說明支援的動作:The following table describes the actions supported:

資源Resource HTTP 動詞HTTP verbs URI 路由URI routes
探索Discovery GET、POST 或 PUTGET, POST, or PUT /api/v1/discovery//api/v1/discovery/
資料擴充Data enrichment POSTPOST /api/subnet//api/subnet/
活動Activities GET 或 POSTGET or POST /api/v1/activities//api/v1/activities/
警示Alerts GET 或 POSTGET or POST /api/v1/alerts//api/v1/alerts/
實體Entities GET 或 POSTGET or POST /api/v1/entities//api/v1/entities/
檔案儲存體Files GET 或 POSTGET or POST /api/v1/files//api/v1/files/

其中 資源 代表一組相關的實體。Where Resource represents a group of related entities.

支援哪些欄位類型?What field types are supported?

下表說明支援的欄位類型:The following table describes the supported field types:

欄位Field 描述Description
字串string 文字字串A textual string
booleanboolean 代表 true/false 的布林值A boolean value representing true/false
整數integer 32 位元帶正負號的整數32-bit signed integer
timestamptimestamp 從 epoch 起的毫秒Milliseconds since epoch

限制Limits

您可以在要求中提供 limit 參數,以選擇限制您的要求。You can choose to limit your requests by providing a limit parameter in the request.

以下是支援提供 limit 參數的方法:The following methods are supported for providing the limit parameter:

  • 具有標頭) 的 URL 編碼 (Content-Type: application/x-www-form-urlencodedURL-encoded (with Content-Type: application/x-www-form-urlencoded header)
  • 表單資料Form data
  • JSON 主體 (搭配 Content-Type: multipart/form-data 和適當的界限標頭) JSON body (with Content-Type: multipart/form-data and an appropriate boundary header)

注意

  • 如果未提供任何限制,則會設定預設值100。If no limit is provided a default of 100 will be set.
  • 使用 API 權杖提出之所有要求的回應,最多可達100個專案。Responses for all requests made with the API token are limited to a maximum of 100 items.
  • 所有 API 要求的節流限制為每個租使用者每分鐘30個要求。The throttle limit for all API requests is 30 requests per minute per tenant.

篩選器Filters

當您有大量的結果時,您會發現使用篩選器來微調要求會很有用。When you have a large number of results, you'll find it useful to fine-tune requests using filters. 本章節描述可搭配使用的、和運算子的結構,以及篩選。This section describes the structure of, and operators that can be used with, filters.

結構Structure

某些 API 端點在執行查詢時支援篩選。Some of our API endpoints support filters when performing queries. 在相關的區段中,您會找到一個參考清單,列出該資源的所有可用可篩選欄位和支援的運算子。In their relevant sections, you will find a reference listing all available filterable fields and supported operators for that resource.

大部分的篩選準則都支援多個值,以提供您強大的查詢。Most filters support multiple values to provide you with powerful queries. 結合我們使用的篩選準則和運算子,以及做為篩選之間的邏輯運算子時。When combining filters and operators we use AND as the logical operator between the filters.

範例Example

curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.contoso.com/api/example-endpoint" -d '{
  "filters": {
    "some.field": {
      "eq": ["value1", "value2"],
      "isset": true
    },
    "some.field2": {
      "gte": 5
    }
  },
  "skip": 5,
  "limit": 10
}'

運算子Operators

注意

並非所有運算子都與所有篩選都相容。Not all operators are compatible with all filters.

下表說明支援的運算子:The following table describes the supported operators:

運算子Operator 回應類型Response type 描述Description
containscontains 字串清單list of strings 傳回包含其中一個所提供字串的所有相關記錄Returns all relevant records containing one of the provided strings
deqdeq 值清單list of values 傳回包含一個值的所有記錄,該值不等於所提供值的一個值Returns all records who contain one value that does not equal one the provided values
descendantofdescendantof 值清單list of values 傳回符合其值或下階的所有相關記錄Returns all relevant records matching values or descendants of them
doesnotstartwithdoesnotstartwith 字串清單list of strings 傳回未以每個提供的字串開頭的所有相關記錄Returns all relevant records not starting with each of the provided strings
endswithendswith 字串清單list of strings 傳回以其中一個提供的字串結尾的所有相關記錄Returns all relevant records ending with one of the provided strings
eqeq 值清單list of values 傳回包含其中一個所提供值的所有相關記錄Returns all relevant records containing one of the provided values
gtgt 單一值single value 傳回其值大於所提供值的所有記錄。Returns all records whose value is greater than the provided value
gtegte 單一值single value 傳回其值大於或等於提供值的所有記錄。Returns all records whose value is greater than or equal to the provided value
gte_ndaysgte_ndays numbernumber 傳回日期晚于 N 天前的所有記錄Returns all records with date later than N days ago
isnotsetisnotset booleanboolean 設定為 "true" 時,會傳回在指定欄位中沒有值的所有相關記錄。When set to "true", returns all relevant records that don't have a value in the specified field
issetisset booleanboolean 設定為 "true" 時,會傳回在指定欄位中具有值的所有相關記錄。When set to "true", returns all relevant records that have a value in the specified field
ltlt 單一值single value 傳回其值小於所提供值的所有記錄。Returns all records whose value is less than the provided value
Ltelte 單一值single value 傳回其值小於或等於所提供值的所有記錄。Returns all records whose value is less than or equal to the provided value
lte_ndayslte_ndays numbernumber 傳回日期早于 N 天前的所有記錄Returns all records with date earlier than N days ago
ncontainsncontains 字串清單list of strings 傳回未包含其中一個所提供字串的所有相關記錄Returns all relevant records not containing one of the provided strings
ndescendantofndescendantof 值清單list of values 傳回所有不符合值或下階的相關記錄Returns all relevant records not matching values or descendants of them
neqneq 值清單list of values 傳回所有未包含所有提供值的相關記錄Returns all relevant records not containing all the provided values
rangerange 包含 [開始] 和 [結束] 欄位的物件清單list of objects containing "start" and "end" fields 傳回其中一個所提供範圍內的所有記錄Returns all records within one of the provided ranges
startswithstartswith 字串清單list of strings 傳回所有相關記錄,並以其中一個提供的字串開頭Returns all relevant records starting with one of the provided strings
startswithsinglestartswithsingle 字串string 傳回以提供的字串開頭的所有相關記錄Returns all relevant records starting with the provided string
texttext 字串string 執行所有記錄的全文檢索搜尋Performs a full-text search of all records

下一步Next steps

若您遇到任何問題,我們隨時提供協助。If you run into any problems, we're here to help. 若要取得產品問題的協助或支援,請建立支援票證To get assistance or support for your product issue, please open a support ticket.