Halaman ini diterjemahkan oleh Cloud Translation API.

API laporan keamanan

Halaman ini berlaku untuk Apigee dan Apigee hybrid.

Selain menggunakan laporan keamanan di UI Apigee, Anda juga dapat mengakses semua fitur laporan keamanan melalui API laporan keamanan. Bagian ini menjelaskan cara menggunakan API laporan keamanan.

Catatan: Data yang masuk ke pipeline Apigee Analytics mengalami keterlambatan hingga 15 hingga 20 menit. Akibatnya, laporan keamanan dengan waktu berakhir kurang dari 20 menit sebelumnya mungkin menampilkan hasil yang salah.

Parameter dalam contoh panggilan API

Bagian berikut memberikan contoh panggilan API yang menggunakan laporan keamanan Compute Engine API. Panggilan API berisi parameter berikut:

ORG adalah organisasi Anda.
ENV adalah lingkungan tempat Anda ingin menghitung laporan.
ENVGROUP adalah grup lingkungan yang berisi lingkungan.
REPORT_ID adalah ID laporan yang ditampilkan melalui panggilan ke buat laporan keamanan.
$TOKEN adalah variabel lingkungan untuk Token akses OAuth.
timeRange adalah rentang waktu untuk laporan.

Membuat laporan keamanan

Untuk membuat laporan keamanan, masukkan perintah seperti berikut:

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"

dengan Query.json adalah template kueri yang menentukan kueri. Contoh template kueri ditampilkan di bawah ini.

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

Kueri tersebut memiliki parameter berikut:

Metrik:
- bot. Ini menghitung jumlah alamat IP unik yang telah yang diidentifikasi sebagai sumber bot.
  
  Fungsi agregasi: count_distinct
- bot_traffic. Jumlah total permintaan dari alamat IP yang sumber bot.
  
  Fungsi agregasi: sum
Lihat Metrik dan fungsi agregasi.
Dimensi: ax_resolved_client_ip. Tindakan ini mengelompokkan jumlah bot dalam laporan menurut alamat IP sumbernya.
Lihat Dimensi.
Filter: environment.
groupByTimeUnit: minute
timeRange: last7days. Lihat Rentang waktu.

Perhatikan bahwa panggilan API ini menampilkan laporan yang sama dengan contoh laporan alamat IP bot yang dibuat menggunakan UI Apigee.

Rentang waktu

Rentang waktu untuk laporan. Anda dapat menetapkan kolom timeRange di salah satu cara berikut:

Tentukan berapa lama laporan harus diperpanjang. Opsinya adalah:
```
"timeRange": "{last60minutes/last24hours/last7days}"
```
Tentukan waktu mulai dan berakhir untuk laporan dalam format berikut:
```
"timeRange": {
        "start": "YYYY-MM-DDT00:00:00Z",
        "end": "YYYY-MM-DDT00:00:00Z"
        }
```
start dan end harus yang sudah berlalu, dan maksimal 1 tahun sebelum {i>present<i} ketika Anda membuat laporan.

Contoh respons

Kueri di atas mengembalikan respons seperti berikut:

{
  "self": "/organizations/ORG/environments/ENV/securityReports/3964675e-9934-4398-bff5-39dd93a67201",
  "state": "enqueued",
  "created": "2021-08-06T22:28:28Z"
}

Respons akan berisi hal berikut:

ID laporan, yang dapat Anda gunakan untuk mendapatkan laporan setelah selesai. Pada contoh di atas, ID laporan adalah 3964675e-9934-4398-bff5-39dd93a67201.
"state": Status tugas laporan, yang dapat berupa salah satu dari berikut ini:
- enqueued: Tugas laporan baru saja dibuat tetapi belum berjalan.
- running: Tugas laporan sedang berjalan.
- completed: Tugas laporan selesai. Pada tahap ini, Anda dapat melihat laporan.
- expired: Tugas laporan telah berakhir, dan Anda tidak dapat lagi melihat laporan.

Mendapatkan status laporan

Untuk mendapatkan status laporan, kirim permintaan seperti berikut:

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"

dengan REPORT_ID sebagai ID laporannya. Lihat Parameter dalam contoh panggilan API.

Respons akan berisi ringkasan parameter laporan, serta status saat ini dalam laporan. Dalam contoh ini, statusnya adalah "completed", sehingga Anda dapat melihat hasil laporan.

{
  "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"
}

Baca laporannya

Untuk mendownload laporan keamanan, kirim permintaan seperti berikut:

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/securityReports/REPORT_ID/result" \
       -X GET -O -J \
       -H "Authorization: Bearer $TOKEN"

dengan REPORT_ID sebagai ID laporannya. Lihat Parameter dalam contoh panggilan API.

Tindakan ini akan menampilkan file yang berisi laporan, yang namanya berasal dari formulir OfflineQueryResult-{ID}.zip. Untuk melihat laporan:

Ekstrak file OfflineQueryResult-{ID}.zip.
Masukkan gzip -d QueryResults-{ID}*.json.gz.
Masukkan cat QueryResults-{ID}*.json

Contoh traffic bot

Contoh berikut membuat laporan tentang bot_traffic:

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

Kueri tersebut memiliki parameter berikut:

Metrik: bot_traffic. Ini adalah jumlah total permintaan dari alamat IP yang telah diidentifikasi sebagai sumber bot, dalam interval satu menit.

Lihat Metrik dan fungsi agregasi.
Dimensi: bot_reason. bot_reason dapat berupa kombinasi dari aturan deteksi untuk bot. Saat bot terdeteksi, bot_reason terdiri dari subkumpulan aturan deteksi yang cocok dengan pola traffic bot.

Lihat Dimensi.
Filter: environment.
groupByTimeUnit: minute
rentangwaktu: last7days

Perhatikan bahwa panggilan API ini menampilkan laporan yang sama dengan contoh laporan alamat IP bot yang dibuat menggunakan UI Apigee.

Penundaan data deteksi bot

Deteksi bot memiliki penundaan pemrosesan rata-rata sekitar 15 hingga 20 menit.

Membuat laporan keamanan untuk grup lingkungan

Dengan Security reports API, Anda dapat membuat laporan untuk data dalam grup lingkungan (bukan hanya lingkungan). Untuk melakukannya, masukkan perintah seperti berikut:

curl "https://apigee.googleapis.com/v1/organizations/ORG/hostSecurityReports" \
       -X POST -d @./Query.json \
       -H 'Content-type: application/json' -i \
       -H "Authorization: Bearer $TOKEN"

dan pastikan template kueri, Query.json, berisi baris berikut:

"envgroup_hostname": "ENVGROUP"

dengan ENVGROUP adalah nama grup lingkungan yang berisi lingkungan. Anda dapat menemukan nama grup lingkungan di UI Apigee dengan membuka Admin > Lingkungan > Grup.

Catatan:

Report API tingkat grup lingkungan hanya mendukung metrik message_count dengan fungsi agregasi sum.
Report API tingkat grup lingkungan tidak mendukung dimensi bot_reason atau incident_id, tetapi mendukung semua dimensi untuk laporan keamanan.

Mendapatkan status laporan

Untuk mendapatkan status laporan, masukkan perintah seperti berikut:

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"

Tindakan ini akan menampilkan ringkasan permintaan laporan, dan status laporan saat ini. Berikut adalah contoh respons:

{
  "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"
  }
}

Karena statusnya adalah "completed", Anda kini dapat melihat laporan, seperti yang dijelaskan berikutnya.

Melihat laporan keamanan

Untuk melihat laporan keamanan, masukkan perintah seperti berikut:

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"

Tindakan ini akan menampilkan file yang berisi laporan, yang namanya sama dengan formulir OfflineQueryResult-{ID}.zip. Untuk melihat laporan:

Ekstrak file OfflineQueryResult-{ID}.zip.
Masukkan gzip -d QueryResults-{ID}*.json.gz.
Masukkan cat QueryResults-{ID}*.json

Metrik dan fungsi agregasi

Anda dapat menggunakan metrik dan fungsi agregasi berikut, yang menghitung statistik dari metrik, untuk laporan.

Metrik	Deskripsi	`Aggregation function`
`bot`	Jumlah alamat IP yang berbeda untuk bot yang terdeteksi dalam interval satu menit.	`count_distinct`
`bot_traffic`	Jumlah pesan dari alamat IP bot yang terdeteksi dalam 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 yang menggunakan cara yang sama laporan.	`sum`
`response_size`	Ukuran payload respons yang ditampilkan dalam byte.	`sum`, `avg`, `min`, `max`
`bot_first_detected`	Tanggal dan waktu bot pertama kali terdeteksi. Hanya tersedia melalui API.	`min`
`bot_last_detected`	Tanggal dan waktu bot terakhir terdeteksi. Hanya tersedia melalui API.	`max`

Dimensi

Dimensi memungkinkan Anda mengelompokkan nilai metrik berdasarkan {i>subset <i}data. Tabel berikut menjelaskan dimensi yang spesifik untuk Keamanan API Lanjutan:

Dimensi	Deskripsi
`bot_reason`	Keamanan dapat berupa kombinasi apa pun aturan deteksi. `bot_reason` terdiri dari subkumpulan aturan deteksi yang cocok dengan pola traffic bot.
`incident_id` (pratinjau)	UUID untuk insiden keamanan, yang ditampilkan melalui panggilan ke Incidents API. Lihat Contoh: Mendapatkan detail atau insiden tertentu.
`security_action`	Tindakan keamanan. Kemungkinan nilai adalah `ALLOW`, `DENY`, atau `FLAG`.
`security_action_name`	Nama tindakan keamanan.
`security_action_headers`	Header yang dapat Anda gunakan untuk mengkueri tindakan keamanan laporan.

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 hal berikut dimensi:

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 (pratinjau)
proxy_basepath
proxy_pathsuffix
request_uri
request_verb
response_status_code
target_host
target_url
useragent

Batasan laporan keamanan

Lihat Batasan laporan keamanan.