Security Stats API

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

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

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

  • 時系列ディメンションがない表形式の統計情報。多くの場合、表形式の統計情報は集計関数(たとえば、sum for message_countbot_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_TIMEEND_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 レスポンスのサイズ。 averagemaxminsum

ディメンション

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

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

incident_id(プレビュー版) セキュリティ インシデントの UUID。Incidents API の呼び出しで返されます。例: 詳細または特定のインシデントを取得するをご覧ください。
security_action セキュリティ アクション。使用できる値は、ALLOWDENYFLAG です。
security_action_name セキュリティ アクションの名前。
security_action_headers フラグ セキュリティ アクションのクエリに使用できるヘッダー。

注: bot_reasonincident_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_idbot_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 年前に遡ります。