Kami telah mengatur ulang struktur navigasi dokumentasi agar selaras langsung dengan alur kerja operasional Anda. Lihat catatan rilis dan video panduan untuk mengetahui informasi selengkapnya.

Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Search API Asinkron

Didukung di:

Google secops SIEM

Platform Penelusuran di Google Security Operations memungkinkan Anda menggunakan API asinkron untuk kueri yang berjalan lama dan menampilkan kumpulan 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 Long-Running Operation (LRO) API, Anda akan menerima ID operasi. Anda dapat menggunakan ID ini untuk memantau status operasi dan mendapatkan halaman hasil satu per satu.

Prasyarat

Untuk menggunakan API operasi yang berjalan lama, entitas pemanggil memerlukan izin Identity and Access Management (IAM) tertentu.

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

Memulai penelusuran: chronicle.searchSessions.search
Mencantumkan hasil: chronicle.searchedResults.list pada resource SearchSession.

Pastikan prinsipal panggilan 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:

Mulai penelusuran.
Pantau operasi.
Ambil hasilnya.

Mulai 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 kunci berikut:

query: String kueri penelusuran.
time_range: Interval waktu untuk penelusuran.
dialect: Menentukan dialek bahasa sebagai YL2.
result_limit: Opsional. Jumlah maksimum baris yang akan diwujudkan. Nilai defaultnya adalah 10000, dan nilai maksimumnya adalah 1000000.

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 berisi resource SearchSession yang dibuat.
Jika operasi gagal, kolom done akan menampilkan true, dan kolom error 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 akan selesai dengan sukses.
response.name: Nama resource SearchSession. Gunakan nilai ini sebagai properti induk pada langkah berikutnya.
response.metadata.resultRowCount: Menunjukkan jumlah total baris yang ditemukan.
response.metadata.moreDataAvailable: Menunjukkan bahwa jumlah hasil yang tersedia melebihi batas hasil 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 semua operasi LRO dari 24 jam terakhir, tambahkan filter name: "operations/s-lro".

Contoh berikut menunjukkan permintaan ListOperations yang berhasil:

google.longrunning.ListOperationsRequest {
  name: "projects/PROJECT_NUMBER/locations/LOCATION/instances/INSTANCE_ID"
  filter: "name:\"operations/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 hasilnya

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 mendukung parameter kueri berikut:

page_size: Jumlah maksimum hasil yang akan ditampilkan per halaman. Nilai defaultnya adalah 100, dan nilai maksimumnya adalah 10000.
page_token: Token dari ListSearchedResultsResponse sebelumnya yang digunakan untuk mengambil halaman berikutnya.
order_by: Opsional. Kolom digunakan untuk mengurutkan hasil.
- UDM events (eventRecord): Gunakan jalur dalam kolom udm, misalnya, udm.metadata.timestamp desc atau udm.principal.hostname asc. Nama kolom termasuk hostname, user, process name, dan event type juga didukung.
  
  Nilai defaultnya adalah udm.metadata.event_timestamp.
- Entities / ECG (entityContextRecord): Gunakan jalur dalam kolom entity, misalnya, graph.entity.ip asc.
- 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 yang 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 UDM-Tabel data): %<table_alias>.<column_name>
  Alias bawaan seperti hostname, user, process name, dan event type juga didukung. Untuk alias ini, gunakan format $e1.hostname.at.
- skip: Opsional. Jumlah hasil yang akan dilewati. Jangan gunakan jika menggunakan page_token.

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
/searchSessions/SEARCH_SESSION_ID/searchedResults/RESULT_ID", "resultRow": {
"eventRecord": {
//... Similar UDM event structure...
}
}
},
{
""name": "projects/PROJECT_NUMBER/locations/
LOCATION/instances/INSTANCE_ID
/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 sebenarnya.

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

Langkah berikutnya

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

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