本頁面由 Cloud Translation API 翻譯而成。

安全性報告 API

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

查看 Apigee Edge 說明文件。

除了在 Apigee 使用者介面中查看安全性報表，您也可以透過安全性報表 API 存取所有安全性報表功能。本節說明如何使用安全性報告 API。

注意：流入 Apigee Analytics 管道的資料平均會延遲 15 到 20 分鐘。因此，如果安全報告的結束時間是過去 20 分鐘內，可能會傳回不正確的結果。

範例 API 呼叫中的參數

下列各節提供使用安全防護報告 API 的 API 呼叫範例。API 呼叫包含下列參數：

ORG 是貴機構。
ENV 是您要計算報表的環境。
ENVGROUP 是包含環境的環境群組。
REPORT_ID 是呼叫「建立安全性報告」時傳回的報告 ID。
$TOKEN 是 OAuth 存取權杖的環境變數。
timeRange 是報表的時間範圍。

建立安全性報表

如要建立安全性報告，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

其中 Query.json 是定義查詢的查詢範本。查詢範本範例如下所示。

{
  "dimensions": [
    "ax_resolved_client_ip",
  ],
  "metrics": [
    {
      "aggregation_function": "count_distinct",
      "name": "bot"
    },
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    },
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

查詢的參數如下：

指標：
- bot。這會計算已識別為機器人來源的不重複 IP 位址數量。
  
  匯總函式：count_distinct
- bot_traffic。來自機器人來源 IP 位址的請求總數。
  
  匯總函式：sum
請參閱「指標和匯總函式」。
維度：ax_resolved_client_ip。這會依據來源的 IP 位址，將報表中的機器人數量分組。
請參閱「維度」。
篩選器：environment。
groupByTimeUnit：minute
timeRange：last7days。請參閱「時間範圍」。

請注意，這個 API 呼叫會傳回與使用 Apigee UI 建立的機器人 IP 位址報表範例相同的報表。

時間範圍

報表的時間範圍。您可以透過下列任一方式設定 timeRange 欄位：

指定報表應回溯的時間長度。選項如下：
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
請以下列格式指定報表的開始和結束時間：
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
start 和 end 都必須是過去的時間，且建立報表時，最多只能是目前時間前 1 年。

回應範例

上述查詢會傳回類似以下的回應：

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

回覆內容包含下列項目：

報表 ID，可用於在報表完成後取得報表。在上述範例中，報表 ID 為 3964675e-9934-4398-bff5-39dd93a67201。
"state"：報表作業的狀態，可能如下：
- enqueued：報表作業剛建立，但尚未執行。
- running：報表作業正在執行中。
- completed：報表工作已完成。此時您就可以查看報表。
- expired：報表工作已過期，您無法再查看報表。

取得報告狀態

如要取得報表狀態，請傳送類似下列的要求：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

其中 REPORT_ID 是報表 ID。請參閱範例 API 呼叫中的參數。

回應會包含報表參數摘要，以及報表的目前狀態。在本例中，狀態為 "completed"，因此您可以查看報表結果。

{
  "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d",
  "state": "completed",
  "created": "2022-06-27T13:00:25-07:00",
  "updated": "2022-06-27T13:01:08-07:00",
  "result": {
    "self": "/organizations/sense-staging-test/environments/local/securityReports/bd2f4fe0-a906-44c2-8dcb-2c618e4b565d/result",
    "expires": "2022-07-04T13:01:08-07:00"
  },
  "resultRows": "848",
  "resultFileSize": "5.10 KB",
  "executionTime": "43 seconds",
  "queryParams": {
    "metrics": [
      "name:bot,func:count_distinct,alias:count_distinct_bot,op:,val:",
      "name:bot_traffic,func:sum,alias:sum_bot_traffic,op:,val:"
    ],
    "dimensions": [
      "ax_resolved_client_ip"
    ],
    "startTimestamp": "2022-06-20T20:00:25.098237292Z",
    "endTimestamp": "2022-06-27T20:00:25.098237292Z",
    "mimeType": "json",
    "timeUnit": "minute"
  },
  "displayName": "Sample Query Bot"
}

下載報告

如要下載安全性報告，請傳送類似下列內容的要求：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

其中 REPORT_ID 是報表 ID。請參閱範例 API 呼叫中的參數。

這會傳回包含報表的檔案，檔案名稱格式為 OfflineQueryResult-{ID}.zip。如要查看報表，請按照下列步驟操作：

解壓縮 OfflineQueryResult-{ID}.zip。
輸入 gzip -d QueryResults-{ID}*.json.gz。
輸入cat QueryResults-{ID}*.json人數

漫遊器流量範例

以下範例會建立 bot_traffic 的報表：

{
  "dimensions": [
    "bot_reason"
  ],
   "metrics": [
    {
      "aggregation_function": "sum",
      "name": "bot_traffic"
    }
  ],
  "groupByTimeUnit": "minute",
  "timeRange": "last7days"
}

查詢的參數如下：

指標：bot_traffic。這是指在 1 分鐘間隔內，來自已識別為機器人來源的 IP 位址要求總數。

請參閱「指標和匯總函式」。
維度：bot_reason。bot_reason 可以是機器人的任何偵測規則組合。偵測到機器人時，bot_reason 會包含機器人流量模式符合的偵測規則子集。

請參閱「維度」。
篩選器：environment。
groupByTimeUnit：minute
timeRange：last7days

請注意，這個 API 呼叫會傳回與使用 Apigee UI 建立的機器人 IP 位址報表範例相同的報表。

機器人偵測資料延遲

機器人偵測作業的處理延遲時間平均約為 15 到 20 分鐘。

為環境群組建立安全性報告

使用安全報告 API 時，您可以為環境群組中的資料建立報告 (而不只是環境)。如要這麼做，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

並確認查詢範本 Query.json 包含下列程式碼：

"envgroup_hostname": "ENVGROUP"

其中 ENVGROUP 是包含環境的環境群組名稱。如要查看環境群組名稱，請前往 Apigee UI 中的「管理」>「環境」>「群組」。

注意：

環境群組層級的 Report API 只支援使用匯總函式 sum 的指標 message_count。
環境群組層級的 Report API 不支援 bot_reason 或 incident_id 維度，但支援安全性報表的所有其他維度。

取得報告狀態

如要取得報表狀態，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID" \
       -X GET  -H 'Content-type: application/json' -i \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

這會傳回報表要求的摘要，以及報表的目前狀態。回覆範例如下：

{
  "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "completed",
  "created": "2021-08-06T15:28:28-07:00",
  "updated": "2021-08-06T15:28:40-07:00",
  "result": {
    "self": "/organizations/ngsaas-runtime-staging/environments/test/securityReports/3964675e-9934-4398-bff5-39dd93a67201/result",
    "expires": "2021-08-13T15:28:40-07:00"
  },
  "resultRows": "60",
  "resultFileSize": "0.31 KB",
  "executionTime": "11 seconds",
  "queryParams": {
    "metrics": [
      "name:message_count,func:sum,alias:sum_message_count,op:,val:"
    ],
    "dimensions": [
      "apiproxy"
    ],
    "startTimestamp": "2021-08-06T21:28:28.570770570Z",
    "endTimestamp": "2021-08-06T22:28:28.570770570Z",
    "mimeType": "json",
    "timeUnit": "minute"
  }
}

由於狀態為 "completed"，您現在可以查看報表，詳情請見下文。

查看安全性報告

如要查看安全性報告，請輸入類似下列的指令：

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

這會傳回包含報表的檔案，檔案名稱格式為 OfflineQueryResult-{ID}.zip。如要查看報表，請按照下列步驟操作：

解壓縮 OfflineQueryResult-{ID}.zip。
輸入 gzip -d QueryResults-{ID}*.json.gz。
輸入cat QueryResults-{ID}*.json人數

指標和匯總函式

您可以在報表中使用下列指標和匯總函式，從指標計算統計資料。

指標	說明	`Aggregation function`
`bot`	每分鐘間隔內偵測到的機器人專屬 IP 位址數量。	`count_distinct`
`bot_traffic`	每隔一分鐘，系統會統計偵測到的機器人 IP 位址傳送的郵件數。	`sum`
`message_count`	Apigee 每分鐘處理的 API 呼叫總數。注意： `message_count` 無法與其他指標顯示在同一份報表中。	`sum`
`response_size`	以位元組為單位，傳回的回應酬載大小。	`sum`、`avg`、`min`、`max`
`bot_first_detected`	首次偵測到機器人的日期和時間。只能透過 API 使用。	`min`
`bot_last_detected`	上次偵測到機器人的日期和時間。只能透過 API 使用。	`max`

維度

維度可讓您根據相關資料子集，將指標值分組。下表說明進階 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
ax_dn_region
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_family
ax_ua_agent_type
ax_ua_agent_version
ax_ua_agent_category
ax_ua_os_family
bot_reason
client_id
developer
developer_app
developer_email
envgroup_hostname
environment
incident_id (預先發布版)
proxy_basepath
proxy_pathsuffix
request_uri
request_verb
response_status_code
target_host
target_url
useragent

安全性報告的限制

請參閱安全性報告的限制。

安全性報告 API 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

範例 API 呼叫中的參數

建立安全性報表

時間範圍

回應範例

取得報告狀態

下載報告

漫遊器流量範例

機器人偵測資料延遲

為環境群組建立安全性報告

取得報告狀態

查看安全性報告

指標和匯總函式

維度

安全性報告的限制

安全性報告 API