本頁面由 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 中查看環境群組名稱，請依序前往「Admin」>「Environments」>「Groups」。

注意事項：

環境群組層級報表 API 僅支援使用匯總函式 sum 的指標 message_count。
環境群組層級報表 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`	在 1 分鐘間隔內，從偵測到的機器人 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`

維度

維度可讓您根據資料的相關子集，將指標值分組。下表說明 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_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