Security stats API

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Lihat Apigee Edge dokumentasi.

Security Stats API memungkinkan Anda melihat statistik terkait penyalahgunaan dan bot selama 14 hari terakhir. Ada dua jenis statistik keamanan:

  • Statistik tabular, yang tidak memiliki dimensi waktu. Statistik tabular sering dihitung menggunakan fungsi agregasi, misalnya, sum for message_count atau bot_traffic.
  • Statistik deret waktu, yang memiliki dimensi waktu.
Catatan: Deteksi bot memiliki penundaan pemrosesan sekitar 15 hingga 20 menit rata-rata.

Parameter dalam contoh panggilan API

Bagian berikut memberikan contoh panggilan API yang menggunakan Security Stats API. Panggilan API berisi parameter berikut:

  • ORG: Organisasi Anda.
  • ENV: Lingkungan Anda.
  • METRIC_i: Metrik untuk statistik. Lihat Metrik dan fungsi agregasi.
  • AGGREGATION_i: Fungsi agregasi untuk metrik. Lihat tabel di bawah.
  • DIMENSION_i: Sebuah dimensi untuk mengelompokkan nilai statistik.
  • PAGE_SIZE: Jumlah maksimum subkomponen yang ditampilkan dalam satu halaman.
  • time_range: Rentang waktu untuk statistik dalam bentuk 
    "time_range": {
    "start_time": START_TIME,
    "end_time": END_TIME
}

    dengan:

    • START_TIME adalah waktu mulai untuk rentang waktu.
    • END_TIME adalah waktu berakhir untuk rentang waktu.

    START_TIME dan END_TIME memiliki format "YYYY-MM-DDT00:00:00Z".

    Panjang rentang waktu dapat mencapai maksimal 14 hari, dan tanggal mulai serta tanggal berakhir harus berada dalam 365 hari terakhir.

Contoh: Membuat kueri statistik keamanan tabular untuk lingkungan

Permintaan yang membuat kueri statistik tabular memiliki format berikut:

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
          }
        }'

Lihat Parameter dalam contoh panggilan API.

Lihat Batasan statistik keamanan untuk mengetahui jumlah maksimum metrik, fungsi agregasi, dan dimensi yang dapat disertakan dalam permintaan.

Berikut adalah contoh permintaan yang membuat kueri statistik tabular:

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
          }
        }'

Lihat halaman referensi queryTabularStats untuk mengetahui deskripsi permintaan dan respons.

Contoh: Membuat kueri statistik keamanan deret waktu untuk lingkungan

Time Series API menampilkan statistik deret waktu untuk metrik yang dipilih, yang dikelompokkan menurut dimensi yang dipilih.

Panggilan berikut memanggil statistik deret waktu untuk traffic bot yang dikelompokkan menurut proxy API. Karena ada empat proxy, hal ini menghasilkan empat urutan titik deret waktu. Urutan titik setiap baris cocok dengan indeks yang sesuai di kolom.

Berikut contoh permintaan:

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
          }
        }'

Lihat Parameter dalam contoh panggilan API.

Lihat halaman referensi queryTabularStats untuk mengetahui deskripsi permintaan dan respons.

Contoh: Membuat kueri detail insiden untuk deteksi penyalahgunaan

Contoh berikut membuat kueri detail insiden untuk deteksi Penyalahgunaan Advanced API Security's . Panggilan ini menampilkan detail jumlah bot untuk developer_app untuk insiden tertentu.

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
          }
        }'

Lihat Parameter dalam contoh panggilan API.

Tindakan ini akan menampilkan respons seperti berikut:

{
  "values": [
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer2_App1",
      18353
    ],
    [
      "d897d1af-51ac-4b5d-a29e-d1059d922a05",
      "Developer1_App1",
      18082
    ]
  ],
  "columns": [
    "incident_id",
    "developer_app",
    "bot_traffic"
  ]
}

Lihat halaman referensi queryTabularStats untuk mengetahui deskripsi permintaan dan respons.

Metrik dan fungsi agregasi

Tabel berikut menjelaskan metrik dan fungsi agregasi yang tersedia di Security Stats API:

Metric Deskripsi Aggregation function
bot Jumlah alamat IP unik untuk bot yang terdeteksi selama interval satu menit. count_distinct
bot_first_detected Tanggal dan waktu bot pertama kali terdeteksi. Hanya tersedia melalui API. min
bot_last_detected Tanggal dan waktu bot terakhir kali terdeteksi. Hanya tersedia melalui API. max
bot_traffic Jumlah pesan dari alamat IP bot yang terdeteksi selama interval satu menit. sum
message_count

Jumlah total panggilan API yang diproses oleh Apigee dalam interval satu menit.

Catatan: message_count tidak dapat digunakan dengan metrik lain dalam laporan yang sama.

 sum
response_size Ukuran respons. average, max, min, sum

Dimensi

Dimensi memungkinkan Anda mengelompokkan nilai metrik berdasarkan subset data terkait. Tabel berikut menjelaskan dimensi yang khusus untuk laporan Advanced API Security:

Dimensi Deskripsi
bot_reason Dapat berupa kombinasi aturan deteksi keamanan . bot_reason terdiri dari subset aturan deteksi yang cocok dengan pola traffic bot.
incident_id (pratinjau) UUID untuk insiden keamanan, yang ditampilkan oleh panggilan ke Incidents API. Lihat Contoh: Mendapatkan detail atau insiden tertentu.
security_action Tindakan keamanan. Nilai yang mungkin adalah ALLOW, DENY, atau FLAG.
security_action_name Nama tindakan keamanan.
security_action_headers Header yang dapat Anda gunakan untuk membuat kueri tindakan keamanan flag.

Catatan: bot_reason dan incident_id hanya berfungsi dengan metrik berikut:

  • bot
  • bot_traffic
  • response_size

Selain dimensi yang dijelaskan di atas, Advanced API Security juga mendukung dimensi berikut:

  • access_token
  • api_product
  • apiproxy
  • app_group_app
  • app_group_name
  • 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
  • is_filtered_out
  • proxy_basepath
  • proxy_pathsuffix
  • request_uri
  • response_status_code
  • target_url
  • useragent

Batasan statistik keamanan

Security Stats API (tabular dan deret waktu) memiliki batasan berikut:

  • Ukuran halaman maksimum: 14400
  • Maksimum 10 dimensi deret waktu
  • Maksimum 15 dimensi statistik tabular
  • Maksimum 5 agregasi metrik.
  • Maksimum 5 agregasi metrik deret waktu
  • Rentang waktu: Panjang dapat mencapai maksimal 14 hari, dan tanggal mulai serta tanggal berakhir harus berada dalam 365 hari terakhir.
  • Dimensi incident_id dan bot_reason tidak dapat digunakan dengan metrik message_count atau response_size.
  • Dimensi is_filtered_out hanya didukung oleh statistik tabular, dan juga berlaku untuk data lama.

Membandingkan Security Stats API dan Security Reports API

Security Stats API dan Security Reports API menampilkan statistik keamanan terkait penyalahgunaan dan bot, tetapi keduanya memiliki perbedaan berikut:

  • Security Stats API dirancang untuk melihat statistik traffic API terbaru. Data untuk Security Stats API hanya berlaku selama 14 hari terakhir, tetapi Anda dapat melihat statistiknya segera setelah mengirim permintaan.

    Statistik keamanan juga ditampilkan di tampilan Metrik penyalahgunaan di UI Apigee.

  • The Security Reports API dirancang untuk melihat statistik operasi yang berjalan lama. Untuk menggunakan Security Scores API, Anda harus mengirimkan tugas dan melihat hasilnya hanya setelah tugas selesai. Data untuk Security Scores API berlaku selama satu tahun terakhir.