安全統計資料 API

本頁內容適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

透過安全性統計資料 API，您可以查看過去 14 天的濫用和機器人相關統計資料。安全統計資料分為兩種：

  • 表格統計資料，不含時間維度。表格統計資料通常是使用匯總函式計算，例如 sum for message_count 或 bot_traffic。
  • 時間序列統計資料，這類資料確實有時間維度。
注意：機器人偵測功能平均會有 15 到 20 分鐘的處理延遲。

範例 API 呼叫中的參數

下列各節提供使用安全統計資料 API 的 API 呼叫範例。API 呼叫包含下列參數：

  • ORG：貴機構。
  • ENV：您的環境。
  • METRIC_i：統計資料的指標。請參閱指標和匯總函式。
  • AGGREGATION_i：指標的匯總函式。請參閱下表。
  • DIMENSION_i：用於分組統計資料值的 維度。
  • PAGE_SIZE：單一頁面中傳回的子元件數量上限。
  • time_range：表單中統計資料的時間範圍 
    "time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}

    其中：

    • START_TIME 是時間範圍的開始時間。
    • END_TIME 是時間範圍的結束時間。

    START_TIME 和 END_TIME 的格式為 "YYYY-MM-DDT00:00:00Z"。

    時間範圍長度最多為 14 天，且開始日期和結束日期都必須在過去 365 天內。

範例：查詢環境的表格安全性統計資料

查詢表格統計資料的要求格式如下：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1",
                      {"metric": "METRIC_2", "aggregation": "AGGREGATION_2"}],
          "dimensions": ["DIMENSION_1",  "DIMENSION_2"],
          "page_size": PAGE_SIZE,
          "time_range": {
              "start_time": START_TIME,
              "end_time": END_TIME
          }
        }'

請參閱範例 API 呼叫中的參數。

如要瞭解要求中可納入的指標、匯總函式和維度數量上限，請參閱安全性統計資料的限制。

以下是查詢表格統計資料的範例要求：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "bot", "aggregation": "count_distinct"},
                      {"metric": "bot_traffic", "aggregation": "sum"},
                      {"metric": "bot_first_detected", "aggregation": "min"},
                      {"metric": "bot_last_detected", "aggregation": "max"}],
          "dimensions": ["apiproxy",  "bot_reason", "ax_resolved_client_ip",  "ax_geo_city",  "ax_geo_country",  "client_id",  "proxy_basepath", "proxy_pathsuffix"],
          "page_size": 1,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

如需要求和回應的說明，請參閱 queryTabularStats參考頁面。

範例：查詢環境的時間序列安全性統計資料

時間序列 API 會傳回所選指標的時間序列統計資料，並依所選維度分組。

以下呼叫會叫用按 API Proxy 分組的機器人流量時間序列統計資料。由於有四個 Proxy，因此會產生四個時間序列點序列。每個資料列的點順序會與 columns 欄位中的對應索引相符。

以下是範例要求：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTimeSeriesStats" \
       -H 'Content-type: application/json' -H "Authorization: Bearer $TOKEN" -X POST -d \
       '{ "metrics": [{"metric": "METRIC_1", "aggregation": "AGGREGATION_1", "order": "ORDER"}],
          "dimensions": ["DIMENSION_1"], "window_size": "WINDOW_SIZE",
          "page_size": PAGE_SIZE,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

請參閱範例 API 呼叫中的參數。

如需要求和回應的說明，請參閱 queryTabularStats參考頁面。

範例：查詢濫用行為偵測事件詳細資料

以下範例會查詢 Advanced API Security 的濫用行為偵測事件詳細資料。呼叫會傳回指定事件的開發人員應用程式機器人數量詳細資料。

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityStats:queryTabularStats" \
       -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" -X POST -d  \
       '{"metrics": [{"metric": "bot_traffic", "aggregation": "sum"}],
         "dimensions": ["incident_id", "developer_app"],
          "filter": "incident_id eq '\''d897d1af-51ac-4b5d-a29e-d1059d922a05'\''",
          "page_size": 100,
          "time_range": {
            "start_time": START_TIME,
            "end_time": END_TIME
          }
        }'

請參閱範例 API 呼叫中的參數。

這會傳回類似以下的回應：

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

如需要求和回應的說明，請參閱 queryTabularStats參考頁面。

指標和匯總函式

下表說明安全性統計資料 API 提供的指標和匯總函式：

Metric 說明 Aggregation function
bot 每分鐘間隔內偵測到的機器人專屬 IP 位址數量。 count_distinct
bot_first_detected 系統首次偵測到機器人的日期和時間。只能透過 API 使用。 min
bot_last_detected 上次偵測到機器人的日期和時間。只能透過 API 使用。 max
bot_traffic 每隔一分鐘，系統會統計偵測到的機器人 IP 位址傳送的郵件數。 sum
message_count

Apigee 每分鐘處理的 API 呼叫總數。

注意： message_count 無法與其他指標顯示在同一份報表中。

 sum
response_size 回應大小。 average、max、min、sum

維度

維度可讓您根據相關資料子集，將指標值分組。下表說明進階 API 安全防護報表專屬的維度：

維度 說明
bot_reason 可以是任意組合的安全性偵測規則。bot_reason 包含與機器人流量模式相符的偵測規則子集。
incident_id (預先發布版) 安全事件的 UUID，由對 Incidents API 的呼叫傳回。 請參閱 範例：取得詳細資料或特定事件。
security_action 安全性動作。可能的值為 ALLOW、DENY 或 FLAG。
security_action_name 安全措施的名稱。
security_action_headers 可用於查詢標記安全性動作的標頭。

注意： bot_reason 和 incident_id 僅適用於下列指標：

  • bot
  • bot_traffic
  • response_size

除了上述維度外，進階 API 安全性也支援下列維度：

  • access_token
  • api_product
  • apiproxy
  • app_group_app
  • app_group_name
  • ax_edge_execution_fault_code
  • ax_geo_city
  • ax_geo_continent
  • ax_geo_country
  • ax_geo_region
  • ax_isp
  • ax_resolved_client_ip
  • ax_ua_agent_version
  • client_id
  • developer
  • developer_app
  • developer_email
  • environment
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • response_status_code
  • target_url
  • useragent

安全性統計資料的限制

安全性統計資料 API (表格和時間序列) 有下列限制：

  • 頁面大小上限：14400
  • 最多 10 個時間序列維度
  • 最多 15 個表格統計資料維度
  • 最多 5 個指標匯總。
  • 最多 5 個時間序列指標匯總
  • 時間範圍：長度最多 14 天，開始日期和結束日期都必須在過去 365 天內。
  • 維度 incident_id 和 bot_reason 無法與指標 message_count 或 response_size 搭配使用。

比較安全統計資料 API 和安全報告 API

安全性統計資料 API 和安全性報表 API 都會傳回與濫用和機器人相關的安全性統計資料，但兩者有以下差異：

  • 安全統計資料 API 的用途是查看近期 API 流量的統計資料。安全性統計資料 API 只會提供過去 14 天的資料，但您傳送要求後，就能立即查看統計資料。

    您也可以在 Apigee UI 的「濫用指標」檢視畫面中查看安全性統計資料。

  • 安全報告 API 可用於查看長時間執行的作業統計資料。如要使用安全分數 API，請提交工作，並在工作完成後查看結果。安全分數 API 的資料會回溯一年。