Migrar endpoints de SOAR a la API Chronicle

Disponible en:

En este documento se describen los pasos y las consideraciones para migrar de la superficie de la API SOAR obsoleta a la API Chronicle unificada. El objetivo de esta guía es ayudarte a hacer la transición de forma fluida y eficiente, minimizando las interrupciones y aprovechando las nuevas funciones.

La superficie de la API Chronicle incluye varias mejoras diseñadas para optimizar tu proceso de desarrollo. También aborda las limitaciones y las complejidades de la API anterior.

Requisitos previos

Antes de llevar a cabo la migración de la API SOAR, debe hacer lo siguiente:

Cambios y mejoras clave

En la siguiente tabla se destacan las principales diferencias entre las superficies de la API antigua y la nueva:

Área de funciones API antigua Nueva API Detalles
Autenticación Token de API OAuth 2.0 El nuevo método de autenticación ofrece una mayor seguridad y estandariza el proceso.
Modelos de datos Estructuras planas Diseño orientado a recursos Este nuevo diseño mejora la coherencia de los datos y simplifica la manipulación de objetos.
Nombres de los endpoints Flujos de trabajo RESTful y estandarizada Si los nombres son coherentes, la API será más intuitiva y fácil de integrar.

Programación de la desactivación

La antigua superficie de la API de SOAR se retirará por completo el 30 de junio del 2026. Te recomendamos que completes la migración antes de esa fecha para evitar interrupciones del servicio.

Pasos de la migración

En esta sección se describen los pasos que debes seguir para migrar tus aplicaciones a la API Chronicle correctamente:

Consulta la documentación

Familiarízate con la documentación completa de la nueva API, incluida la guía de referencia de la API Chronicle.

Asignar endpoints a la nueva superficie de la API

Identifica los nuevos endpoints correspondientes a cada una de las llamadas a la API antiguas que hace tu aplicación. Del mismo modo, asigna los modelos de datos antiguos a los nuevos, teniendo en cuenta los cambios estructurales o los campos nuevos. Para obtener más información, consulta la tabla de asignación de endpoints de la API.

Opcional: Crear una integración de pruebas

Si vas a editar una integración personalizada o un componente de una integración comercial, te recomendamos que envíes los cambios primero a una integración de prueba. Este proceso te permite hacer pruebas sin que afecte a tus flujos de automatización de producción. Si vas a migrar una aplicación creada específicamente que usa la API SOAR, puedes ir al paso siguiente. Para obtener más información sobre la fase de pruebas de la integración, consulta el artículo Probar integraciones en el entorno de pruebas.

Actualizar el endpoint de servicio y las URLs

Un endpoint de servicio es la URL base que especifica la dirección de red de un servicio de API. Un servicio puede tener varios endpoints. Chronicle es un servicio regional y solo admite endpoints regionales.

Todos los endpoints nuevos usan un prefijo coherente, lo que hace que la dirección del endpoint final sea predecible. En el siguiente ejemplo se muestra la nueva estructura de la URL del endpoint:

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

Esta estructura hace que la dirección final del endpoint sea la siguiente:

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

Donde:

  • service_endpoint: una dirección de servicio regional
  • api_version: la versión de la API que se va a consultar. Puede ser v1alpha, v1beta o v1.
  • project_id: el ID de tu proyecto (el mismo que definiste para los permisos de gestión de identidades y accesos)
  • location: la ubicación de tu proyecto (región), que es la misma que la de los endpoints regionales.
  • instance_id: tu ID de cliente de Google Security Operations SIEM.

Direcciones regionales:

  • 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

Por ejemplo, para obtener una lista de todos los casos de un proyecto en EE. UU., haz lo siguiente:

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

Actualizar el método de autenticación

La nueva API usa Google Cloud IAM para la autenticación. Deberá actualizar su aplicación o integración de respuesta para implementar este nuevo flujo de autenticación. Asegúrate de que el usuario que ejecuta la secuencia de comandos tenga los permisos correctos para los endpoints a los que intenta acceder.

Actualizar la lógica de la API

Analiza los nuevos modelos de datos y estructuras de endpoints que se proporcionan en la referencia de la API. No todos los métodos han cambiado significativamente y se puede reutilizar parte del código. El objetivo principal es revisar la nueva documentación de referencia y, para cada caso de uso específico, identificar e implementar los cambios necesarios en los nombres de los campos y las estructuras de datos de la lógica de tu aplicación.

Probar la integración

Prueba tu aplicación actualizada en una integración de staging antes de implementarla en producción:

  1. Crea un plan de pruebas: define casos de prueba que abarquen todas las funciones migradas.
  2. Ejecuta pruebas: realiza pruebas automatizadas y manuales para confirmar la precisión y la validez.
  3. Monitorizar el rendimiento: evalúa el rendimiento de tu aplicación con la nueva API.

¿Necesitas más ayuda? Recibe respuestas de los miembros de la comunidad y de los profesionales de Google SecOps.