安全統計資料 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，因此會產生四個時間序列點序列。每個資料列的點順序，會與資料欄欄位中的對應索引相符。

以下是要求範例：

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 的濫用偵測功能事件詳細資料。這個呼叫會針對特定事件傳回 developer_app 的機器人數量詳細資料。

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 在 1 分鐘間隔內，從偵測到的機器人 IP 位址傳送的郵件數。 sum
message_count

Apigee 在一分鐘間隔內處理的 API 呼叫總數。

注意： message_count 無法與相同報表中的其他指標搭配使用。

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

維度

維度可讓您根據資料的相關子集，將指標值分組。下表說明 Advanced API Security 報表專屬的維度：

維度 說明
bot_reason 可任意組合安全偵測規則。bot_reason 包含機器人的流量模式相符的偵測規則子集。
incident_id (預先發布版) 安全事件的 UUID，由對事件 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
  • 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 的資料可追溯一年。