Esegui la migrazione degli endpoint SOAR all'API Chronicle

Supportato in:

Questo documento descrive i passaggi e le considerazioni per la migrazione dall'interfaccia API SOAR ritirata all'API Chronicle unificata. Questa guida ha lo scopo di aiutarti a eseguire la transizione in modo semplice ed efficiente, riducendo al minimo le interruzioni e sfruttando le nuove funzionalità.

La superficie API di Chronicle introduce diversi miglioramenti progettati per semplificare il processo di sviluppo. Affronta anche le limitazioni e le complessità presenti nella vecchia API.

Prerequisiti

Prima di eseguire la migrazione dell'API SOAR, devi:

Modifiche e miglioramenti principali

La seguente tabella evidenzia le principali differenze tra le vecchie e le nuove superfici API:

Area delle funzionalità API precedente Nuova API Dettagli
Autenticazione Token API OAuth 2.0 Il nuovo metodo di autenticazione offre maggiore sicurezza e standardizza la procedura.
Modelli dati Strutture piatte Progettazione orientata alle risorse Questo nuovo design migliora la coerenza dei dati e semplifica la manipolazione degli oggetti.
Denominazione degli endpoint Flussi di lavoro RESTful e standardizzato La denominazione coerente rende l'API più intuitiva e più facile da integrare.

Programmazione del ritiro

Il ritiro completo della vecchia superficie API per SOAR è previsto per il 30 giugno 2026. Ti consigliamo di completare la migrazione prima di questa data per evitare interruzioni del servizio.

Passi per la migrazione

Questa sezione descrive i passaggi per eseguire la migrazione delle applicazioni all'API Chronicle:

Esamina la documentazione

Acquisisci familiarità con la documentazione completa della nuova API, inclusa la guida di riferimento dell'API Chronicle.

Mappare gli endpoint alla nuova superficie API

Identifica i nuovi endpoint corrispondenti per ciascuna delle vecchie chiamate API effettuate dalla tua applicazione. Allo stesso modo, mappa i vecchi modelli di dati a quelli nuovi, tenendo conto di eventuali modifiche strutturali o nuovi campi. Per maggiori dettagli, consulta la tabella di mappatura degli endpoint API.

(Facoltativo) Crea un'integrazione di staging

Se stai modificando un'integrazione personalizzata o un componente di un'integrazione commerciale, ti consigliamo di eseguire il push delle modifiche prima in un'integrazione di staging. Questo processo ti consente di eseguire test senza influire sui flussi di automazione della produzione. Se esegui la migrazione di un'applicazione creata su misura che utilizza l'API SOAR, puoi passare al passaggio successivo. Per informazioni dettagliate sul test delle integrazioni, vedi Testare le integrazioni in modalità di staging.

Aggiorna l'endpoint di servizio e gli URL

Un endpoint di servizio è l'URL di base che specifica l'indirizzo di rete di un servizio API. Un singolo servizio può avere più endpoint di servizio. Chronicle è un servizio regionale e supporta solo gli endpoint regionali.

Tutti i nuovi endpoint utilizzano un prefisso coerente, il che rende prevedibile l'indirizzo dell'endpoint finale. L'esempio seguente mostra la nuova struttura dell'URL dell'endpoint:

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

Questa struttura rende l'indirizzo finale dell'endpoint come segue:

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

Dove:

  • service_endpoint: Un indirizzo del servizio regionale
  • api_version: la versione dell'API da interrogare. Può essere v1alpha, v1beta o v1.
  • project_id: L'ID progetto (lo stesso progetto definito per le autorizzazioni IAM)
  • location: La posizione del progetto (regione); uguale agli endpoint regionali
  • instance_id: il tuo ID cliente Google Security Operations SIEM.

Indirizzi regionali:

  • africa-south1: https://chronicle.africa-south1.rep.googleapis.com

  • asia-northeast1: https://chronicle.asia-northeast1.rep.googleapis.com

  • asia-south1: https://chronicle.asia-south1.rep.googleapis.com

  • asia-southeast1: https://chronicle.asia-southeast1.rep.googleapis.com

  • asia-southeast2: https://chronicle.asia-southeast2.rep.googleapis.com

  • australia-southeast1: https://chronicle.australia-southeast1.rep.googleapis.com

  • europe-west12: https://chronicle.europe-west12.rep.googleapis.com

  • europe-west2: https://chronicle.europe-west2.rep.googleapis.com

  • europe-west3: https://chronicle.europe-west3.rep.googleapis.com

  • europe-west6: https://chronicle.europe-west6.rep.googleapis.com

  • europe-west9: https://chronicle.europe-west9.rep.googleapis.com

  • me-central1: https://chronicle.me-central1.rep.googleapis.com

  • me-central2: https://chronicle.me-central2.rep.googleapis.com

  • me-west1: https://chronicle.me-west1.rep.googleapis.com

  • northamerica-northeast2: https://chronicle.northamerica-northeast2.rep.googleapis.com

  • southamerica-east1: https://chronicle.southamerica-east1.rep.googleapis.com

  • us: https://chronicle.us.rep.googleapis.com

  • eu: https://chronicle.eu.rep.googleapis.com

Ad esempio, per ottenere un elenco di tutte le richieste relative a un progetto negli Stati Uniti:

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

Aggiorna il metodo di autenticazione

La nuova API utilizza Google Cloud IAM per l'autenticazione. Dovrai aggiornare l'integrazione dell'applicazione o della risposta per implementare questo nuovo flusso di autenticazione. Assicurati che l'utente che esegue lo script disponga delle autorizzazioni corrette per gli endpoint a cui sta tentando di accedere.

Aggiorna la logica API

Analizza i nuovi modelli di dati e le strutture degli endpoint forniti nel riferimento API. Non tutti i metodi sono cambiati in modo significativo e alcuni codici esistenti possono essere riutilizzati. L'obiettivo principale è esaminare la nuova documentazione di riferimento e, per ogni caso d'uso specifico, identificare e implementare le modifiche necessarie ai nomi dei campi e alle strutture dei dati nella logica dell'applicazione.

Testare l'integrazione

Testa l'applicazione aggiornata in un'integrazione di staging prima di eseguire il deployment in produzione:

  1. Crea un piano di test: definisci scenari di test che coprano tutte le funzionalità migrate.
  2. Esegui test: esegui test automatici e manuali per verificare l'accuratezza e la validità.
  3. Monitora il rendimento: valuta il rendimento della tua applicazione con la nuova API.

Hai bisogno di ulteriore assistenza? Ricevi risposte dai membri della community e dai professionisti di Google SecOps.