Security Stats API

このページの内容は Apigee と Apigee ハイブリッドに該当します。

Apigee Edge のドキュメントはこちらをご覧ください。

Security Stats API を使用すると、過去 14 日間の不正行為と bot 関連の統計情報を表示できます。セキュリティの統計情報には次の 2 種類があります。

時系列ディメンションがない表形式の統計情報。多くの場合、表形式の統計情報は集計関数（たとえば、sum for message_count や bot_traffic）を使用して計算されます。
時系列ディメンションがある時系列統計情報。

注: bot 検出の処理遅延は平均で 15～20 分です。

API 呼び出しの例のパラメータ

次のセクションでは、Security Stats API を使用する API 呼び出しの例を示します。API 呼び出しには次のパラメータが含まれます。

ORG: あなたの組織。
ENV: あなたの環境。
METRIC_i: 統計情報の指標。指標と集計関数をご覧ください。
AGGREGATION_i: 指標の集計関数。下の表をご覧ください。
DIMENSION_i: 統計情報の値をグループ化するためのディメンション。
PAGE_SIZE: 1 ページで返されるサブコンポーネントの最大数。
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 呼び出しの例のパラメータをご覧ください。

1 つのリクエストに含めることができる指標、集計関数、ディメンションの最大数については、セキュリティ統計情報の上限をご覧ください。

次は、表形式の統計情報に対してクエリを実行するリクエストの例です。

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 プロキシでグループ化された bot トラフィックの時系列統計を呼び出します。4 つのプロキシがあるため、時系列ポイントの 4 つのシーケンスが生成されます。各行のポイントの順序は、列フィールドの対応するインデックスと一致します。

以下はリクエストのサンプルです。

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 の bot 数の詳細を返します。

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 リファレンスページをご覧ください。

指標と集計関数

次の表に、Security Stats API で使用できる指標と集計関数を示します。

`Metric`	説明	`Aggregation function`
`bot`	1 分間隔で検出された bot の個別の IP アドレス数。	`count_distinct`
`bot_first_detected`	bot が最初に検出された日時。API を介してのみ利用可能です。	`min`
`bot_last_detected`	bot が最後に検出された日時。API を介してのみ利用可能です。	`max`
`bot_traffic`	1 分間隔で検出された bot の IP アドレスからのメッセージ数。	`sum`
`message_count`	Apigee によって 1 分間隔で処理された API 呼び出しの合計数。注: `message_count` は、同じレポート内の他の指標と一緒に使用できません。	`sum`
`response_size`	レスポンスのサイズ。	`average`、`max`、`min`、`sum`

ディメンション

ディメンションによって、関連するデータのサブセットに基づいて、指標値をまとめてグループ化できます。次の表に、Advanced API Security レポートに固有のディメンションを示します。

ディメンション	説明
`bot_reason`	セキュリティ検出ルールは任意の組み合わせが可能です。`bot_reason` は、bot のトラフィックパターンが一致した検出ルールのサブセットで構成されます。
`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

前述のディメンションに加えて、Advanced API Security では次のディメンションもサポートしています。

access_token
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 の比較

Security Stats API と Security Reports API はどちらも、不正行為と bot 関連のセキュリティ統計情報を返しますが、次の違いがあります。

セキュリティ統計情報 API は、最近の API トラフィックの統計情報を表示するように設計されています。セキュリティ統計情報 API のデータは 14 日前までしか遡れませんが、リクエストを送信するとすぐに統計情報を確認できます。

セキュリティ統計情報は、Apigee UI の不正行為指標ビューにも表示されます。
Security Reports API は、長時間実行オペレーションの統計情報を表示するように設計されています。Security Scores API を使用するには、ジョブを送信し、ジョブの完了時にのみ結果を表示します。Security Scores API のデータは 1 年前に遡ります。

Security Stats API

API 呼び出しの例のパラメータ

例: 環境の表形式のセキュリティ統計情報に対してクエリを実行する

例: 環境の時系列セキュリティ統計情報に対してクエリを実行する

例: 不正行為の検出のインシデントの詳細に対してクエリを実行する

指標と集計関数

ディメンション

セキュリティ統計情報の上限

セキュリティ統計情報 API とセキュリティ レポート API の比較

セキュリティ統計情報 API とセキュリティレポート API の比較