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.

Bermigrasi dari SIEM API lama ke Chronicle API

Didukung di:

Google secops SIEM

Dokumen ini membantu Anda mengelola aplikasi yang memanggil salah satu SIEM API lama (Backstory API dan Ingestion API). Dokumen ini menjelaskan langkah-langkah yang harus Anda ikuti untuk menyiapkan akses terprogram, dan memperbarui referensi dari endpoint SIEM API lama ke endpoint Chronicle API modern.

Untuk ringkasan singkat proses migrasi, tonton video yang disematkan.

Chronicle API surface memperkenalkan beberapa peningkatan yang dirancang untuk menyederhanakan proses pengembangan dan selaras dengan Google Cloud standar API untuk meningkatkan keandalan, keamanan, performa, dan integrasi yang lebih kuat dengan Cloud Audit Logs, Cloud Monitoring, Cloud Identity, dan Identity and Access Management (IAM). Chronicle API surface juga mengatasi banyak batasan dan kompleksitas API lama.

Apa saja yang berubah

Semua permintaan terprogram ke endpoint Backstory API dan Ingestion API lama harus bertransisi ke Chronicle API modern. Jika organisasi Anda menggunakan integrasi kustom, skrip otomatisasi, atau alat pihak ketiga yang melakukan panggilan ke endpoint lama ini, Anda harus mengupdate workload tersebut untuk menggunakan endpoint dan alur autentikasi modern sebelum 20 Juli 2027.

Yang tidak berubah

Tindakan yang dilakukan langsung di antarmuka pengguna (UI) Google SecOps sudah memanggil Chronicle API modern. Jika organisasi Anda hanya berinteraksi dengan Google SecOps melalui UI, atau jika integrasi Anda sudah memanggil endpoint Chronicle API, Anda tidak perlu melakukan tindakan apa pun.

Perubahan dan peningkatan utama

Tabel berikut menyoroti perbedaan utama antara SIEM API lama dan Chronicle API:

Area fitur	SIEM API lama	Chronicle API	Detail
Pengelolaan kredensial	Proses manual yang melibatkan perwakilan Google	Pengelolaan akun layanan, kredensial, dan izin IAM secara mandiri	Pengelolaan kredensial dan IAM secara mandiri menyederhanakan proses orientasi dan menghilangkan ketergantungan pada permintaan dukungan manual.
Standar kepatuhan	Dukungan terbatas	Dukungan bawaan untuk kontrol Residensi Data, Kontrol Layanan VPC, Transparansi Akses, CMEK, dan FedRAMP	Kontrol infrastruktur bawaan modern memenuhi standar kepatuhan dan peraturan industri.
Logging dan audit	Aliran audit lama	Cloud Audit Logs terintegrasi ke dalam Google Cloud project Anda	Integrasi langsung menyediakan jalur audit dan pemantauan terpusat.
Autentikasi	Token API dan kredensial akun layanan	OAuth 2.0 dengan dukungan untuk metode autentikasi modern, termasuk Workload Identity dan akun layanan seperti yang dijelaskan dalam Autentikasi untuk Google Cloud API dan layanan	Metode autentikasi modern ini memberikan keamanan yang ditingkatkan dan menstandarkan alur kredensial.
Model data dan desain API	Struktur datar dan eksklusif	Desain berorientasi resource, arsitektur RESTful, dan penamaan standar yang mengikuti AIP	Desain modern ini meningkatkan konsistensi data, membuat API lebih intuitif, dan menyederhanakan manipulasi objek.
Penamaan endpoint	Tidak konsisten	RESTful dan standar	Penamaan yang konsisten membuat API lebih intuitif dan lebih mudah diintegrasikan.
Ekosistem	Sangat terbatas	Integrasi dengan MCP, Terraform, library klien, dan SDK	Kompatibilitas luas dengan alat cloud modern dan framework otomatisasi.

Jadwal penghentian

SIEM API lama dijadwalkan untuk dihentikan pada 20 Juli 2027. Sebaiknya selesaikan migrasi Anda sebelum tanggal ini untuk menghindari gangguan layanan:

Mulai 26 Oktober 2026, Anda tidak dapat lagi memanggil API lama (Backstory API dan Ingestion API) dari instance baru.
Pada 20 Juli 2027, Anda harus memigrasikan semua instance yang ada ke Chronicle API, karena API lama tidak akan tersedia lagi.

Sebelum memulai

Sebelum bermigrasi ke Chronicle API, pastikan Anda menyelesaikan hal berikut:

Men-deploy di infrastruktur SIEM modern: Pastikan instance Anda di-deploy di your Google Cloud project yang memanfaatkan infrastruktur SIEM modern. Untuk mengetahui petunjuk mendetail, lihat Ringkasan migrasi SIEM.
Mengaktifkan Chronicle API: Di Google Cloud konsol, buka project Anda dan aktifkan Chronicle API (chronicle.googleapis.com). Untuk mengetahui detailnya, lihat Mengaktifkan API di your Google Cloud project.

Bermigrasi ke Chronicle API

Migrasikan skrip dan integrasi Anda dari API lama ke Chronicle API dengan menyelesaikan langkah-langkah berikut:

Mengaudit penggunaan API: Identifikasi semua skrip dan integrasi di lingkungan Anda yang memanggil endpoint lama.
Menyiapkan autentikasi dan otorisasi: Konfigurasi lingkungan Anda untuk mengautentikasi dan memberi otorisasi permintaan ke Chronicle API.
Memetakan endpoint dan memperbarui URL: Ganti endpoint lama dengan endpoint regional modern yang setara.
Memperbarui logika API: Sesuaikan payload permintaan dan penanganan respons Anda agar sesuai dengan model data API modern.
Menguji integrasi Anda: Validasi perubahan di lingkungan staging sebelum men-deploy ke produksi.

Mengaudit penggunaan API

Audit lingkungan Anda untuk mengidentifikasi skrip atau integrasi yang memanggil backstory.googleapis.com atau malachiteingestion-pa.googleapis.com. Anda dapat mengidentifikasi integrasi ini dengan meninjau codebase, skrip otomatisasi, dan alat pihak ketiga.

Menyiapkan autentikasi dan otorisasi

Konfigurasi lingkungan Anda untuk mengautentikasi dan memberi otorisasi permintaan ke Chronicle API:

Memilih metode autentikasi: Pilih cara beban kerja Anda melakukan autentikasi ke Chronicle API menggunakan salah satu metode yang tercantum. Sebaiknya gunakan Workload Identity Federation untuk keamanan yang lebih baik, karena metode ini menghindari pengelolaan dan penyimpanan kunci akun layanan yang berumur panjang. Untuk skenario autentikasi lanjutan (seperti peniruan akun layanan), lihat Mengautentikasi ke Chronicle API.
- Workload Identity Federation (direkomendasikan): Siapkan Workload Identity Federation untuk mengizinkan beban kerja yang berjalan di luar Google Cloud melakukan autentikasi menggunakan identitas eksternal.
- Akun Layanan: Jika Anda harus menggunakan akun layanan, buat akun layanan di your Google Cloud project dan buat serta download kunci pribadi dalam format JSON. Pastikan kunci ini tetap aman.
Memberikan izin IAM: Berikan izin IAM yang diperlukan ke identitas (akun layanan atau pokok identitas eksternal) yang digunakan untuk autentikasi. Tetapkan peran IAM yang diperlukan ke identitas Anda, bergantung pada tingkat akses yang diperlukan. Lihat Mengelola akses ke project, folder, dan organisasi untuk mengetahui detailnya. Peran yang telah ditentukan sebelumnya mencakup hal berikut:
Sebaiknya gunakan prinsip hak istimewa terendah untuk hanya memberikan izin yang diperlukan untuk otomatisasi Anda dengan memanfaatkan peran IAM kustom atau yang telah ditentukan sebelumnya.

**Catatan:** Lihat Pemetaan endpoint API SIEM untuk menemukan izin IAM terperinci tertentu yang diperlukan untuk endpoint modern yang menggantikan panggilan lama Anda.
Menetapkan variabel lingkungan kredensial: Konfigurasi lingkungan runtime Anda untuk menggunakan kredensial dengan Kredensial Default Aplikasi (ADC) dengan menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS. Variabel ini harus mengarah ke file JSON kunci akun layanan yang didownload atau file konfigurasi kredensial Workload Identity Federation. Library klien akan otomatis mendeteksi variabel ini untuk mengautentikasi permintaan:Google Cloud
```
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/credentials.json"
```
Memperbarui cakupan OAuth: Perbarui string cakupan jika skrip integrasi lama Anda secara eksplisit meminta cakupan OAuth untuk pembuatan token. Cakupan lama tidak memberikan akses ke API surface modern:
- Cakupan Backstory lama: https://www.googleapis.com/auth/chronicle-backstory
- Cakupan Chronicle: https://www.googleapis.com/auth/chronicle (atau cakupan https://www.googleapis.com/auth/cloud-platform yang lebih luas).

Memetakan endpoint dan memperbarui URL

Pelajari Chronicle API surface, petakan panggilan lama Anda, dan perbarui endpoint layanan di aplikasi Anda.

Meninjau dokumentasi referensi

Pelajari dokumentasi komprehensif untuk Chronicle API.

Memetakan endpoint ke Chronicle API

Identifikasi endpoint modern yang sesuai untuk setiap panggilan API lama yang dibuat aplikasi Anda. Demikian pula, petakan model data yang ada ke struktur modern, dengan mempertimbangkan perubahan skema atau kolom tambahan. Untuk mengetahui detail di semua endpoint SIEM, lihat Pemetaan endpoint SIEM API. Jika alur kerja Anda juga berinteraksi dengan endpoint SOAR, lihat tabel pemetaan endpoint API SOAR.

Memperbarui endpoint layanan

Perbarui URL dasar panggilan API Anda agar mengarah ke endpoint layanan regional yang benar. Chronicle API adalah layanan regional, jadi Anda harus memanggil endpoint layanan regional yang cocok dengan lokasi instance Google SecOps Anda.

Semua endpoint modern menggunakan awalan yang konsisten, sehingga alamat endpoint akhir dapat diprediksi. Contoh berikut menunjukkan struktur URL endpoint modern:

[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Struktur ini membuat alamat akhir ke endpoint sebagai berikut:

https://[service_endpoint]/[api_version]/projects/[project_id]/locations/[location]/instances/[instance_id]/...

Dengan:

service_endpoint: Alamat layanan regional.
api_version: Versi API yang akan dikueri. Dapat berupa v1alpha, v1beta, atau v1.
project_id: Project ID Anda (project yang sama seperti yang Anda tentukan untuk izin IAM Anda).
location: Lokasi project Anda (region); sama dengan endpoint regional.
instance_id: ID pelanggan Google Security Operations SIEM Anda.

Alamat regional:

africa-south1: https://africa-south1-chronicle.googleapis.com atau https://chronicle.africa-south1.rep.googleapis.com
asia-northeast1: https://asia-northeast1-chronicle.googleapis.com atau https://chronicle.asia-northeast1.rep.googleapis.com
asia-south1: https://asia-south1-chronicle.googleapis.com atau https://chronicle.asia-south1.rep.googleapis.com
asia-southeast1: https://asia-southeast1-chronicle.googleapis.com atau https://chronicle.asia-southeast1.rep.googleapis.com
asia-southeast2: https://asia-southeast2-chronicle.googleapis.com atau https://chronicle.asia-southeast2.rep.googleapis.com
australia-southeast1: https://australia-southeast1-chronicle.googleapis.com atau https://chronicle.australia-southeast1.rep.googleapis.com
europe-west12: https://europe-west12-chronicle.googleapis.com atau https://chronicle.europe-west12.rep.googleapis.com
europe-west2: https://europe-west2-chronicle.googleapis.com atau https://chronicle.europe-west2.rep.googleapis.com
europe-west3: https://europe-west3-chronicle.googleapis.com atau https://chronicle.europe-west3.rep.googleapis.com
europe-west6: https://europe-west6-chronicle.googleapis.com atau https://chronicle.europe-west6.rep.googleapis.com
europe-west9: https://europe-west9-chronicle.googleapis.com atau https://chronicle.europe-west9.rep.googleapis.com
me-central1: https://me-central1-chronicle.googleapis.com atau https://chronicle.me-central1.rep.googleapis.com
me-central2: https://me-central2-chronicle.googleapis.com atau https://chronicle.me-central2.rep.googleapis.com
me-west1: https://me-west1-chronicle.googleapis.com atau https://chronicle.me-west1.rep.googleapis.com
northamerica-northeast2: https://northamerica-northeast2-chronicle.googleapis.com atau https://chronicle.northamerica-northeast2.rep.googleapis.com
southamerica-east1: https://southamerica-east1-chronicle.googleapis.com atau https://chronicle.southamerica-east1.rep.googleapis.com
Amerika Serikat (us): https://us-chronicle.googleapis.com atau https://chronicle.us.rep.googleapis.com
Eropa (eu): https://eu-chronicle.googleapis.com atau https://chronicle.eu.rep.googleapis.com

Untuk mengetahui daftar lengkap semua endpoint yang didukung, lihat referensi resmi dalam dokumentasi Endpoint layanan Chronicle API Service endpoint.

Misalnya, untuk mencantumkan semua aturan deteksi untuk instance di lokasi us, kirim permintaan berikut:

GET 
  https://us-chronicle.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/rules

Demikian pula, untuk mengkueri resource SOAR seperti Kasus menggunakan alias endpoint regional (rep), kirim permintaan berikut:

GET 
  https://chronicle.us.rep.googleapis.com/v1alpha/projects/my-project-name-or-id/locations/us/instances/408bfb7b-5746-4a50-885a-50a323023529/cases

Memperbarui logika API

Tinjau referensi REST Chronicle API untuk mengidentifikasi dan menerapkan perubahan pada nama kolom dan struktur data di aplikasi Anda. Meskipun beberapa endpoint lama mungkin tetap serupa, Anda harus memperbarui integrasi agar sesuai dengan model data dan struktur endpoint terbaru.

Menggunakan Google Cloud library klien

Sederhanakan integrasi Anda untuk menangani autentikasi, penyegaran token, dan detail transportasi secara otomatis. Sebaiknya gunakanlibrary klien resmi Google Cloud untuk melakukannya. Dukungan Chronicle API tersedia di delapan bahasa pemrograman, termasuk Python, Go, Java, Node.js, dan C#. Untuk mengetahui detail penginstalan dan penggunaan, lihat Library klien dan SDK.

Menguji integrasi Anda

Uji aplikasi yang telah diupdate dalam integrasi staging sebelum men-deploy ke produksi:

Membuat rencana pengujian: Tentukan kasus pengujian yang mencakup semua fungsi yang dimigrasikan.
Menjalankan pengujian: Jalankan pengujian otomatis dan manual untuk mengonfirmasi akurasi dan validitas.
Memantau performa: Nilai performa aplikasi Anda dengan API modern.

Memecahkan masalah

Bagian ini menjelaskan cara mengatasi error umum yang mungkin Anda temui selama migrasi.

HTTP 403 Forbidden atau PERMISSION_DENIED

Jika panggilan API Anda menampilkan error HTTP 403 Forbidden atau PERMISSION_DENIED, verifikasi hal berikut:

Metode dan pokok autentikasi: Pastikan Anda menggunakan kredensial yang benar.
- Jika menggunakan Workload Identity Federation, pastikan pokok identitas eksternal cocok dengan pokok yang terikat ke peran IAM di project Anda.
- Jika menggunakan akun layanan, pastikan akun layanan yang benar digunakan dan belum dinonaktifkan. Jangan gunakan akun layanan lama (sering kali berisi bk atau malachite-cx di alamat emailnya) untuk endpoint Chronicle API modern.
Peran IAM: Pastikan akun layanan atau pokok identitas eksternal telah diberi peran IAM kustom atau yang telah ditentukan sebelumnya (seperti Chronicle API Viewer atau Chronicle API Editor) di your Google Cloud project. Untuk izin endpoint API terperinci, lihat Pemetaan endpoint API SIEM.

HTTP 401 Unauthorized atau UNAUTHENTICATED

Jika panggilan API Anda gagal dengan HTTP 401 Unauthorized atau UNAUTHENTICATED, periksa hal berikut:

Cakupan OAuth: Pastikan skrip Anda meminta cakupan modern: https://www.googleapis.com/auth/chronicle (atau cakupan https://www.googleapis.com/auth/cloud-platform yang lebih luas). Cakupan lama (https://www.googleapis.com/auth/chronicle-backstory) tidak memberikan akses ke Chronicle API modern.
Variabel lingkungan: Pastikan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ditetapkan dan mengarah ke file kunci JSON atau file konfigurasi Workload Identity Federation yang benar di lingkungan runtime Anda.

HTTP 404 Not Found atau ketidakcocokan regional

Jika panggilan API Anda menampilkan HTTP 404 Not Found atau gagal terhubung, periksa endpoint regional Anda:

Endpoint Regional: Chronicle API adalah layanan regional. Pastikan Anda memanggil endpoint yang cocok dengan region instance Google SecOps Anda (misalnya, https://europe-west3-chronicle.googleapis.com untuk instance di Frankfurt). Mengirim permintaan ke region lain akan menyebabkan error. Untuk mengetahui daftar lengkap alamat regional, lihat Memperbarui endpoint layanan atau referensi Endpoint layanan resmi.

Langkah berikutnya

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