Abbiamo riorganizzato la struttura di navigazione della documentazione per allinearla direttamente ai tuoi flussi di lavoro operativi. Per ulteriori informazioni, consulta le note di rilascio e il video dimostrativo.

Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Eseguire la migrazione all'API Chronicle

Supportato in:

Google secops SOAR

Questo documento si applica se chiami l'API SOAR in modo programmatico utilizzando integrazioni, script personalizzati o azioni personalizzate. Questo documento illustra i passaggi e le considerazioni per aiutarti ad aggiornare i riferimenti API programmatici ai nuovi endpoint API SOAR nell'ambito dell'API Chronicle.

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

La vecchia API SOAR e le chiavi API saranno disponibili fino al 30 novembre 2026, dopodiché non funzioneranno più.

Prerequisiti

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

Completare la fase 1 della migrazione.

Modifiche e miglioramenti principali

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

Area funzionalità	Vecchia API	Nuova API	Dettagli
Autenticazione	Token API	OAuth 2.0	Il nuovo metodo di autenticazione offre una maggiore sicurezza e standardizza il processo.
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	Incoerente	RESTful e standardizzata	Una denominazione coerente rende l'API più intuitiva e facile da integrare.

Pianificazione del ritiro

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

Passi per la migrazione

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

Rivedi la documentazione

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

Mappa 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 di produzione. Se stai eseguendo la migrazione di un'applicazione personalizzata che utilizza l'API SOAR, puoi passare al passaggio successivo. Per maggiori dettagli sullo staging dell'integrazione, consulta 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 di emergenza 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 località del progetto (regione), uguale agli endpoint regionali
instance_id: l'ID cliente di 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 tutti i casi di 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'applicazione o l'integrazione 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. Per implementare questo nuovo flusso, devi aggiornare le integrazioni o le applicazioni di risposta. Assicurati che l'utente che esegue lo script disponga delle autorizzazioni necessarie per gli endpoint di destinazione. Per istruzioni dettagliate, consulta la pagina Autenticarsi all'API Chronicle.

Mappa il account di servizio o la workload identity ai parametri SOAR

Se utilizzi un account di servizio o la federazione delle identità per i workload per l'autenticazione all'API Chronicle, devi autorizzarlo all'interno della piattaforma per assicurarti che possa comunicare correttamente con Google SecOps. Questa mappatura è necessaria per fornire al account di servizio o alla workload identity l'accesso necessario ai ruoli e agli ambienti del SOC.

Per concedere l'accesso al service account o l'accesso alla federazione delle identità per i workload a Google SecOps, devi mappare l'identità ai parametri di controllo dell'accesso della piattaforma. Questo passaggio è obbligatorio per fornire all'identità l'accesso necessario ai ruoli del SOC e agli ambienti necessari per eseguire attività automatizzate o operazioni API.

Vai a Impostazioni SOAR > Avanzate > Mappatura dei gruppi.
Fai clic su Aggiungi Aggiungi.

Completa i campi nella finestra di dialogo Aggiungi mappatura per mappare l'identità ai parametri di controllo dell'accesso della piattaforma.

Nel campo Gruppo IdP / utente, inserisci uno dei seguenti valori:
- L'indirizzo email completo del account di servizio, se l'identità è stata configurata utilizzando Cloud Identity.
- La stringa principale di Workload Identity, se l'identità è stata configurata utilizzando la federazione delle identità per la forza lavoro.

Configura i seguenti campi di controllo dell'accesso:

Campo	Descrizione
Gruppi di autorizzazioni	Seleziona i gruppi di autorizzazioni per definire i moduli e i sottomoduli a cui l'identità può accedere.
Ruoli del SOC	Seleziona i ruoli del SOC per definire il ruolo dell'identità (ad esempio, livello 1).
Ambienti	Seleziona gli ambienti o i gruppi di ambienti a cui l'identità può accedere (ad esempio, Tutti gli ambienti).
Membri del gruppo	Inserisci gli indirizzi email degli utenti richiesti, se applicabile. Premi Invio dopo aver aggiunto ogni indirizzo email.
Azioni vietate	Seleziona le azioni vietate per limitare operazioni specifiche all'interno dei moduli.

Fai clic su Aggiungi.

Per informazioni più dettagliate sulla mappatura di utenti e service account, consulta Mappare gli utenti nella piattaforma utilizzando l'identità di terze parti o Mappare gli utenti nella piattaforma utilizzando Cloud Identity.

Aggiorna la logica dell'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 all'interno della logica dell'applicazione.

Verifica la tua integrazione

Verifica l'applicazione aggiornata in un'integrazione di staging prima di eseguirne il deployment in produzione:

Crea un piano di test: definisci i casi di test che coprono tutte le funzionalità di cui è stata eseguita la migrazione.
Esegui i test: esegui test automatici e manuali per confermare l'accuratezza e la validità.
Monitora il rendimento: valuta il rendimento dell'applicazione con la nuova API.

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