使用 API 管理安全性報告

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

查看 Apigee Edge 說明文件。

本頁面說明如何使用安全報告 API 建立及查看安全報告。

如要瞭解安全性報告總覽 (包括限制)，請參閱「 安全性報告總覽」。如要查看安全報告的 API 參考說明文件，請參閱 安全報告 API 參考資料。

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

範例 API 呼叫中的參數

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

建立安全性報告

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

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」。如要查看報表，請按照下列步驟操作：

  1. 解壓縮 OfflineQueryResult-{ID}.zip。
  2. 輸入 gzip -d QueryResults-{ID}*.json.gz。
  3. 進入cat QueryResults-{ID}*.json
    4. 。

漫遊器流量範例

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

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

查詢的參數如下：

  • 指標：bot_traffic。這是指在一分鐘間隔內，來自已識別為機器人來源的 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 只支援指標 message_count 和匯總函式 sum。
  • 環境群組層級的 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。如要查看報表，請按照下列步驟操作：

  1. 解壓縮 OfflineQueryResult-{ID}.zip。
  2. 輸入 gzip -d QueryResults-{ID}*.json.gz。
  3. 進入cat QueryResults-{ID}*.json
    4. 。