API Penelusuran Asinkron

Didukung di:

Google SecOps SIEM

Platform Penelusuran di Google Security Operations memungkinkan Anda menggunakan API asinkron untuk kueri yang berjalan lama yang menampilkan set hasil besar hingga 1 juta hasil. API ini memungkinkan Anda memulai penelusuran di seluruh sumber data, termasuk peristiwa Unified Data Model (UDM), deteksi, tabel data, dan Entity Context Graph (ECG), tanpa memblokir aplikasi Anda. Saat menjalankan kueri penelusuran menggunakan API operasi yang berjalan lama (LRO), Anda akan menerima ID operasi. Anda dapat menggunakan ID ini untuk memantau status operasi dan mendapatkan hasil halaman demi halaman.

Prasyarat

Untuk menggunakan API operasi yang berjalan lama, akun utama yang memanggil memerlukan izin Identity and Access Management (IAM) tertentu.

Untuk melakukan tindakan berikut, Anda harus memiliki izin IAM yang sesuai:

• Memulai penelusuran: chronicle.searchSessions.search
• Hasil daftar: chronicle.searchedResults.list pada resource SearchSession.

Pastikan akun utama yang memanggil memiliki peran yang memberikan izin ini, misalnya, peran Chronicle API Viewer, Chronicle API Editor, atau Chronicle API Admin.

Menjalankan penelusuran menggunakan LRO API

Ikuti langkah-langkah berikut untuk menjalankan penelusuran menggunakan LRO API:

1. Memulai penelusuran.
2. Pantau operasi.
3. Mengambil hasil.

Memulai penelusuran

Kirim permintaan POST ke metode kustom search di instance Google SecOps.

• Endpoint: POST /{$api_version}/projects/{project}/locations/{location}/instances/{instance}:search
• Metode: Search
• Isi permintaan: SearchRequest

Contoh berikut menunjukkan objek SearchRequest:

{
  "parent": "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID",
  "query": "metadata.event_type = \"USER_LOGIN\"",
  "time_range": {},
  "start_time": "2026-03-16T14:40:13Z",
  "endTime": "2026-03-16T15:40:13Z",
  "dialect": "YL2"
}

Permintaan memerlukan parameter utama berikut:

• query: String kueri penelusuran.
• time_range: Interval waktu untuk penelusuran.
• dialect: Menentukan dialek bahasa sebagai YL2.
  • Dialek SQL tidak didukung untuk pengambilan hasil LRO asinkron menggunakan ListSearchedResults (searchedResults.list).
  • Dialek RAW_LOG masih dalam Pratinjau dan mungkin menampilkan error 501 UNIMPLEMENTED jika tidak diaktifkan untuk instance Anda.
• result_limit: Opsional. Jumlah maksimum baris yang akan diwujudkan. Nilai defaultnya adalah 10000, dan nilai maksimumnya adalah 1000000.
• simulated_data_visibility (atau simulatedDataVisibility di JSON): Opsional. Mengontrol apakah hasil penelusuran menyertakan peristiwa yang disimulasikan. Tetapkan ke SIMULATED_DATA_INCLUDED untuk menyertakan peristiwa simulasi dalam hasil penelusuran. Jika tidak ditentukan, parameter ini akan ditetapkan secara default ke SIMULATED_DATA_EXCLUDED, yang mengecualikan peristiwa simulasi.

Panggilan ini menampilkan objek google.longrunning.Operation.

Contoh berikut menunjukkan respons operasi yang berhasil:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "[type.googleapis.com/google.cloud.chronicle.v1main.SearchOperationMetadata](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchOperationMetadata)",
    "state": "RUNNING",
    "start_time": "2026-03-13T10:00:00Z"
  }
}

Kolom state: RUNNING menunjukkan bahwa penelusuran sedang berlangsung.

Memantau operasi

Lakukan polling status LRO menggunakan metode GetOperation standar dari layanan google.longrunning.Operations. Gunakan nilai name dari respons sebelumnya.

• Endpoint: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}/operations/{operationID}

Lanjutkan polling hingga kolom done dalam respons GetOperation menampilkan true.

• Jika operasi berhasil, kolom metadata.state akan menampilkan SUCCEEDED, dan kolom respons akan berisi resource SearchSession yang dibuat.
• Jika operasi gagal, kolom done akan menampilkan true, dan kolom error akan berisi detail kegagalan terkait.

Contoh berikut menunjukkan respons GetOperation yang berhasil:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/operations/OPERATION_ID",
  "metadata": {
    "@type": "[type.googleapis.com/google.cloud.chronicle.v1main.SearchOperation](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchOperation) Metadata",
    "state": "SUCCEEDED",
    "startTime": "2026-03-16T15:42:11.037506921Z"
  },
  "endTime": "2026-03-16T15:42:17.504730842Z",
  "expireTime": "2026-03-17T15:42:17.504731874Z",
  "progress": 100,
  "done": true,
  "response": {
    "@type": "[type.googleapis.com/google.cloud.chronicle.v1main.SearchSession](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchSession)",
    "name": "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/SEARCH_SESSION_ID",
    "query": "metadata.event_type = \"USER_LOGIN\"",
    "timeRange": {},
    "startTime": "2026-03-16T14:40:13Z",
    "endTime": "2026-03-16T15:40:13Z",
    "dialect": "YL2",
    "metadata": {
      "operationId": "OPERATION_ID",
      "startTime": "2026-03-16T15:42:11.037506921Z",
      "endTime": "2026-03-16T15:42:17.504730842Z",
      "expireTime": "2026-03-17T15:42:17.504731874Z",
      "resultRowCount": 10000,
      "moreDataAvailable": true
    }
  }
}

Format nama resource SearchSession adalah projects/{project}/locations/{location}/instances/{instance}/searchSessions/{search_session}.

Respons yang berhasil berisi kolom kunci berikut:

• done: Jika ditetapkan ke true, operasi akan selesai.
• state: Jika ditetapkan ke SUCCEEDED, penelusuran berhasil diselesaikan.
• response.name: Nama resource SearchSession. Gunakan nilai ini sebagai properti induk di langkah berikutnya.
• response.metadata.resultRowCount: Menunjukkan jumlah total baris yang ditemukan.
• response.metadata.moreDataAvailable: Menunjukkan bahwa jumlah hasil yang tersedia melebihi batas pengembalian yang ditentukan.

Mencantumkan operasi LRO

Untuk mencantumkan operasi LRO, gunakan metode ListOperations dari layanan google.longrunning.Operations. Gunakan nilai name dari respons sebelumnya.

• Endpoint: GET /{$api_version}/projects/{project}/locations/{location}/instances/{instance}

Untuk mencantumkan operasi LRO penelusuran dari 24 jam terakhir, tentukan filter name:"operations/s-lro-", termasuk tanda hubung di akhir.

Catatan: Filter ini diperlukan saat Anda memanggil ListOperations (operations.list) untuk mengambil operasi penelusuran. Jika Anda memanggil ListOperations tanpa filter ini, respons hanya akan menampilkan operasi retrohunt dan menghilangkan operasi penelusuran. Selain itu, metode CancelOperation (operations.cancel) dan DeleteOperation (operations.delete) tidak didukung untuk operasi penelusuran s-lro-.

Contoh berikut menunjukkan permintaan ListOperations yang berhasil:

google.longrunning.ListOperationsRequest {
  name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID"
  filter: "name:\"operations/s-lro-\""
  page_size: 100
}

Contoh berikut menunjukkan respons ListOperations yang berhasil:

{
  operations {
    name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/operations/OPERATION_ID_1"
    metadata {
      type_url: "[type.googleapis.com/google.cloud.chronicle.v1main.SearchOperation](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchOperation) Metadata"
      value: "\b\002\022\f\b\367\304\363\316\006\020\317\352\232\240\003\032\f\b\237\307\363\316\006\020\326\334\351\311\001\"\f\b\237\352\370\316\006\020\352\342\351\311\001(d"
    }
    done: true
    response {
      type_url: "[type.googleapis.com/google.cloud.chronicle.v1main.SearchSession](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchSession)"
      value: "\n\213\001projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/OPERATION_ID_11022\bip != \"\"\032\020\n\006\b\251\255\334\316\006\022\006\b\351\345\336\316\006\0012\\\n*OPERATION_ID_1\022\f\b\367\304\363\316\006\020\317\352\232\240\003\032\f\b\237\307\363\316\006\020\326\334\351\311\001\"\f\b\237\352\370\316\006\020\352\342\351\311\001(\300\204=0\001"
    }
  }
  operations {
    name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/operations/OPERATION_ID_2"
    metadata {
      type_url: "[type.googleapis.com/google.cloud.chronicle.v1main.SearchOperationMetadata](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchOperationMetadata)"
      value: "\b\002\022\f\b\200\305\363\316\006\020\324\262\367\225\001\032\v\b\241\307\363\316\006\020\321\261\333?\"\v\b\241\352\370\316\006\020\317\264\333?(d"
    }
    done: true
    response {
      type_url: "[type.googleapis.com/google.cloud.chronicle.v1main.SearchSession](https://type.googleapis.com/google.cloud.chronicle.v1main.SearchSession)"
      value: "\n\213\001projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/OPERATION_ID_2\022\bip != \"\"\0321020\n\006\b\251\255\334\316\006\022\006\b\351\345\336\316\006\0012Z\n*OPERATION_ID_2\022\f\b\200\305\363\316\006\0201324\262\367\225\001\032\v\b\241\307\363\316\006\020\321\261\333?\"\v\b\241\352\370\316\006\020\317\264\333?(\300\204=0\001"
    }
  }
}

Mengambil hasil

Setelah status operasi menampilkan SUCCEEDED, gunakan metode ListSearchedResults() untuk mengambil hasil penelusuran.

• Endpoint: GET /{$api_version}/{parent=projects/*/locations/*/instances/*/searchSessions/*}/searchedResults
• Metode: ListSearchedResults
• Parameter permintaan: ListSearchedResultsRequest

Contoh berikut menunjukkan ListSearchedResultsRequest yang mengambil tiga hasil dan melewati lima hasil pertama:

// GET
/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/SEARCH_SESSION_ID/searchedResults?page_size=3&skip=5

Permintaan ini mendukung parameter kueri berikut:

• page_size: Jumlah hasil maksimum yang akan ditampilkan per halaman. Nilai defaultnya adalah 100, dan nilai maksimumnya adalah 10.000.
• page_token: Token dari ListSearchedResultsResponse sebelumnya yang digunakan untuk mengambil halaman berikutnya.

• order_by (atau orderBy di JSON): Opsional. Kolom yang digunakan untuk mengurutkan hasil. Jika Anda menghilangkan order_by, hasil peristiwa UDM akan diurutkan berdasarkan udm.metadata.event_timestamp dalam urutan menurun secara default, yang menampilkan peristiwa terbaru terlebih dahulu. Jika Anda menentukan jalur kolom di order_by tanpa akhiran arah, seperti udm.principal.hostname, hasil akan diurutkan dalam urutan menaik secara default. Jangan menambahkan asc, karena akhiran asc tidak didukung dan menampilkan error 400 INVALID_ARGUMENT. Untuk mengurutkan hasil dalam urutan menurun, tambahkan akhiran desc ke jalur kolom, seperti udm.metadata.event_timestamp desc. Pengurutan multi-kolom tidak didukung.

  • UDM events (eventRecord): Gunakan jalur yang sepenuhnya memenuhi syarat dalam kolom udm, seperti udm.metadata.event_timestamp desc atau udm.principal.hostname. Nama kolom seperti hostname, user, process name, dan event type juga didukung.

    Tata urutan default adalah udm.metadata.event_timestamp dalam urutan menurun, yang menampilkan peristiwa terbaru terlebih dahulu.

  • Entities / ECG (entityContextRecord): Gunakan jalur dalam kolom entity, seperti graph.entity.ip atau graph.entity.ip desc.

  • data tables (dataTableRecord): Gunakan format %<table_alias>.<column_name>. Misalnya, %dt.user desc.

    Nilai defaultnya adalah kolom tabel data pertama.

  • Detections (DetectionRecord): Gunakan kata kunci detection diikuti dengan jalur, misalnya, detection.id.

  • Gabungan: Untuk peristiwa dan entity, gunakan variabel placeholder yang menentukannya. Untuk semua sumber lainnya, formatnya tetap sama.

    Contoh:

    • ECG (gabungan UDM-ECG): Entity: $e1.graph.entity.hostname
    • UDM (Semua gabungan dengan UDM): $e1.principal.ip
    • Tabel data (Gabungan tabel data UDM): %<table_alias>.<column_name>

    Alias yang telah ditetapkan seperti hostname, user, process name, dan event type juga didukung. Untuk ini, gunakan format $e1.hostname.at.

• skip: Opsional. Jumlah hasil yang akan dilewati. Jangan gunakan parameter ini dengan page_token.

  • Pengurutan default (udm.metadata.event_timestamp) tidak unik di seluruh peristiwa yang memiliki stempel waktu yang sama. Selain itu, tata urutan untuk hasil penelusuran ditetapkan pada panggilan ListSearchedResults (searchedResults.list) pertama.
  • Saat Anda memberi nomor halaman dengan skip, terutama di seluruh permintaan paralel, tentukan kolom pengurutan unik seperti udm.metadata.id dalam parameter order_by. Atau, ambil halaman pertama sebelum mengirim permintaan skip paralel sehingga tata urutan sudah ditetapkan.

Contoh berikut menunjukkan respons ListSearchedResultsResponse yang berhasil:

{
"searchedResults": [
{
"name":
"projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/searchSessions/SEARCH_SESSION_ID/searchedResults/
RESULT_ID",
"resultRow": {
"eventRecord": {
"event": {
"name":
"projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID/events/EVENT_ID",
"udm": {
"metadata": {
"eventTimestamp": "2026-03-16T14:45:18Z",
"eventType": "USER_LOGIN",
"vendorName": "Microsoft",
"productName": "Azure AD"
}
},
//... other UDM fields
}
//... other UDM fields
"eventLogToken":
"EVENT_LOG_TOKEN"
}
},
{ }
},
{
"name": "projects/PROJECT_NUMBER/locations/
LOCATION/instances/INSTANCE_ID</span>
/searchSessions/SEARCH_SESSION_ID/searchedResults/RESULT_ID", "resultRow": {
"eventRecord": {
//... Similar UDM event structure...
}
}
},
{
""name": "projects/PROJECT_NUMBER/locations/
LOCATION/instances/INSTANCE_ID</span>
/searchSessions/SEARCH_SESSION_ID/searchedResults/RESULT_ID", "resultRow": {
"eventRecord": {
//... Similar UDM event structure...
}
}
}
],
"totalSize": 10000,
"columnNames": [],
"columnSchema": {},
"nextPageToken": "CAKYASAB"
}

Untuk mengambil halaman hasil berikutnya, gunakan nilai nextPageToken yang ditampilkan dalam parameter kueri page_token dari permintaan ListSearchedResults berikutnya. Kolom resultRow berisi data aktual.

Lanjutkan memanggil ListSearchedResults dengan nilai next_page_token dari setiap respons. Jika next_page_token menampilkan hasil kosong, berarti semua hasil telah diambil.

Langkah berikutnya

Untuk mengetahui informasi selengkapnya tentang metode, kolom permintaan dan respons, serta jenis, lihat dokumentasi referensi API berikut:

• Referensi REST API Google SecOps
• Metode search
• Metode ListSearchedResults

Perlu bantuan lain? Dapatkan jawaban dari anggota Komunitas dan profesional Google SecOps.