Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Migra a la API de Chronicle

Compatible con:

Google SecOps SOAR

En este documento, se describen los pasos y las consideraciones para ayudarte a actualizar las referencias programáticas de la API a los extremos de la API de SOAR como parte de la API de Chronicle.

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

La API heredada de SOAR y las claves de API seguirán estando disponibles hasta el 31 de marzo de 2027, después de lo cual dejarán de funcionar.

Integraciones de respuestas listas para usar

Si usas una versión de integración desactualizada que llama a las APIs de SOAR heredadas, actualiza el paquete de integración antes del 31 de marzo de 2027:

Integraciones de Content Hub: Abre Content Hub en Google Security Operations y actualiza las integraciones comerciales obsoletas a sus versiones más recientes. Para obtener más información, consulta la descripción general de Content Hub.
Complemento de Splunk: Si usas el complemento de Chronicle SOAR para Splunk, actualiza TA-Siemplify en Splunk a la versión más reciente. Después de la actualización, vuelve a configurar el complemento para usar el endpoint de API de Chronicle regional y las credenciales de cuenta de servicio de Google Cloud .

Requisitos previos

Antes de migrar las llamadas a la API de SOAR a la API de Chronicle, completa la etapa 1 de la migración (Google.com aparece junto a la versión del sistema en Configuración de SOAR > Administración de licencias). Puedes probar y migrar llamadas programáticas a la API de Chronicle antes o después de habilitar Identity and Access Management (IAM) de Google Cloud para los grupos de permisos de SOAR.

Cambios y mejoras clave

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

Área de características	API antigua	API nueva	Detalles
Autenticación	Token de API	OAuth 2.0	El nuevo método de autenticación proporciona una seguridad mejorada 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.
Asignación de nombres de extremos	Incoherente	RESTful y estandarizada	La coherencia en los nombres hace que la API sea más intuitiva y fácil de integrar.

Programa de baja

La plataforma de la API de siemplify-soar.com heredada y la autenticación de AppKey seguirán disponibles hasta el 31 de marzo de 2027, después de lo cual dejarán de funcionar.

Hasta el 31 de marzo de 2027, las APIs heredadas de SOAR seguirán funcionando en paralelo con la API de Chronicle, incluso después de que habilites Google Cloud IAM, para que puedas migrar y validar gradualmente cada componente a tu propio ritmo sin interrumpir los flujos de trabajo activos.

Debido a que la API de SOAR heredada es menos eficiente que la API de Chronicle, te recomendamos que migres a los sustitutos de la API de Chronicle lo antes posible y antes del 31 de marzo de 2027 para evitar interrupciones del servicio.

Pasos para la migración

En esta sección, se describen los pasos para migrar correctamente tus aplicaciones a la API de Chronicle:

Revisa la documentación

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

Asigna extremos a la nueva plataforma de la API

Identifica los extremos nuevos correspondientes para cada una de las llamadas a la API antiguas que realiza tu aplicación. Del mismo modo, asigna los modelos de datos antiguos a los nuevos, teniendo en cuenta cualquier cambio estructural o campo nuevo. Para obtener más detalles, consulta la tabla de asignación de endpoints de API.

Opcional: Crea una integración de etapa de pruebas

Si editas una integración personalizada o una acción personalizada, Google recomienda que envíes los cambios a una integración de etapa de pruebas primero. Este proceso te permite realizar pruebas sin afectar tus flujos de automatización de producción. Si migras una aplicación personalizada que usa la API de SOAR, puedes pasar al siguiente paso. Para obtener detalles sobre la etapa de pruebas de integración, consulta Prueba las integraciones en el modo de etapa de pruebas.

Actualiza el extremo y las URLs del servicio

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

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

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

Esta estructura hace que la dirección final al extremo sea la siguiente:

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

Aquí:

service_endpoint: Es una dirección de servicio regional.
api_version: Es la versión de la API que se consultará. Usa v1 cuando esté disponible o recurre a v1beta o v1alpha si v1 aún no está disponible (consulta la tabla de asignación de la API de SOAR para conocer la versión compatible con cada extremo).
project_id: Es el ID del proyecto (el mismo que definiste para tus permisos de IAM).
location: Es la ubicación de tu proyecto (región), igual que los extremos regionales.
instance_id: Es el ID de cliente de Google Security Operations SIEM.

Direcciones regionales:

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

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

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

Actualiza el método de autenticación

La API de Chronicle usa Google Cloud IAM para la autenticación. Actualiza tus integraciones personalizadas o aplicaciones externas para implementar este flujo de autenticación. Asegúrate de que el usuario o la cuenta de servicio que ejecuta la secuencia de comandos tenga los permisos necesarios para los extremos de destino. Para obtener más información, consulta Autentica en la API de Chronicle.

Asigna la cuenta de servicio o la identidad de carga de trabajo a los parámetros de SOAR

Si usas una cuenta de servicio o la federación de Workload Identity para autenticarte en la API de Chronicle, debes autorizarla dentro de la plataforma para garantizar que pueda comunicarse correctamente con Google SecOps. Esta asignación es necesaria para proporcionar a la cuenta de servicio o a la Workload Identity el acceso necesario a los roles y entornos de SOC.

Para otorgar acceso a una cuenta de servicio o acceso a la federación de identidades para cargas de trabajo a Google SecOps, debes asignar la identidad a los parámetros de control de acceso de la plataforma. Esta asignación es un paso obligatorio para proporcionar a la identidad el acceso necesario a los roles de SOC y los entornos necesarios para realizar tareas automatizadas o de API.

Nota: Otorgar roles de IAM de Google Cloud a una cuenta de servicio o principal es necesario, pero no suficiente para acceder a la API de Google SecOps SOAR. Si la cuenta de servicio no se asigna de forma explícita en Asignación de grupos, las solicitudes a la API fallan con un error 401 UNAUTHENTICATED, incluso cuando se configuran todos los roles de IAM necesarios a nivel del proyecto.

Ve a Configuración > Administración de acceso > Asignación de grupos.
Haz clic en Agregar Agregar.

Completa los campos en el cuadro de diálogo Agregar asignación para asignar la identidad a los parámetros de control de acceso de la plataforma.

En el campo IdP / User group, ingresa una de las siguientes opciones:
- La dirección de correo electrónico completa de tu cuenta de servicio, si la identidad se configuró con Cloud Identity.
- Es la cadena de la principal de Workload Identity, si la identidad se configuró con la federación de identidades de personal.

Configura los siguientes campos de control de acceso:

Campo	Descripción
Grupos de permisos	Selecciona los grupos de permisos para definir a qué módulos y submódulos puede acceder la identidad.
Roles del SOC	Selecciona los roles de SOC para definir el rol de la identidad (como Nivel 1).
Entornos	Selecciona los entornos o grupos de entornos a los que puede acceder la identidad (como Todos los entornos).
Miembros del grupo	Ingresa los correos electrónicos de los usuarios requeridos, si corresponde. Presiona Intro después de agregar cada correo electrónico.
Acciones restringidas	Selecciona las acciones restringidas para limitar operaciones específicas dentro de los módulos.

Haz clic en Agregar.

Para obtener información más detallada sobre la asignación de usuarios y cuentas de servicio, consulta Asigna usuarios en la plataforma con un proveedor de identidad externo o Asigna usuarios en la plataforma con Cloud Identity.

Actualiza la lógica de la API

Analiza los nuevos modelos de datos y las estructuras de extremos que se proporcionan en la referencia de la API. No todos los métodos cambiaron de forma significativa, y se puede reutilizar parte del código existente. 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 dentro de la lógica de tu aplicación.

Migra las llamadas a la API personalizadas a la API de Chronicle

Nota: Pronto, Google lanzará por etapas la compatibilidad con la plataforma y las instrucciones de migración de autoservicio para las llamadas HTTP manuales dentro del código de Python personalizado de SOAR. No modifiques el código interno personalizado de Python hasta que se publiquen estas instrucciones. Las llamadas heredadas de siemplify.API_ROOT y siemplify.api_key seguirán funcionando hasta el 31 de marzo de 2027. Cuando se inicie la migración interna de código personalizado, las secuencias de comandos que llamen a los endpoints de API de Chronicle que no sean del SDK usarán la identidad de una cuenta de servicio de destino que tenga los permisos de IAM necesarios y esté autorizada en Configuración de SOAR > Opciones avanzadas > Asignación de grupos (consulta Asigna la cuenta de servicio o Workload Identity a los parámetros de SOAR). Las secuencias de comandos externas que se ejecutan fuera de Google SecOps se pueden migrar ahora con los pasos de las secciones anteriores.

No todo el código personalizado de Python en Google SecOps requiere cambios en el código:

Los métodos de SDK integrados no requieren cambios en el código: El código de Python personalizado en integraciones personalizadas, acciones de guía, conectores y trabajos que usan métodos de SDK integrados estándar, como siemplify.add_comment(), siemplify.get_case_comments() o siemplify.update_alerts_additional_data(), no requiere modificaciones en el código. Google SecOps enruta automáticamente los métodos del SDK de Siemplify integrados a través de la plataforma de la API unificada.
Solo las solicitudes HTTP manuales requieren actualizaciones: Solo necesitas actualizar las secuencias de comandos de Python personalizadas que crean manualmente solicitudes HTTP a las APIs de SOAR heredadas con propiedades del SDK, por ejemplo, crear una URL con siemplify.API_ROOT y autenticar con siemplify.api_key usando requests o siemplify.session. Para identificar los componentes personalizados afectados, ejecuta resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" en el Explorador de registros (inspeccionando labels.integration_name, labels.action_name, labels.connector_name, labels.job_name y labels.playbook_name) o consulta la lista CustomCode en el informe de resumen de uso de la API heredada.

Prueba tu integración

Prueba la aplicación actualizada en una integración de etapa de pruebas antes de implementarla en producción:

Crea un plan de pruebas: Define casos de prueba que abarquen todas las funcionalidades migradas.
Ejecuta pruebas: Ejecuta pruebas automatizadas y manuales para confirmar la exactitud y la validez.
Supervisa el rendimiento: Evalúa el rendimiento de tu aplicación con la API nueva.

Cuotas y límites de frecuencia

La API de Chronicle aplica cuotas a nivel de proyecto de Google Cloud para mantener la disponibilidad del servicio y evitar el tráfico descontrolado:

Cuotas predeterminadas: La API de Chronicle aplica límites de solicitudes por minuto (RPM) a nivel del proyecto de Google Cloud , por lo general, 6,000 RPM por proyecto, con sublímites regionales de la API.
Errores de límite de frecuencia (HTTP 429): Si una integración o una secuencia de comandos externa supera la cuota de tu proyecto, la API de Chronicle devuelve HTTP 429 (RESOURCE_EXHAUSTED o TooManyRequestsException).

Para ver el uso actual de la cuota de la API de Chronicle o solicitar un límite más alto, sigue estos pasos:

En la consola de Google Cloud , ve a IAM y administración > Cuotas y límites del sistema:

Ir a Cuotas y límites del sistema
Haz clic en Filtrar, selecciona Servicio y, luego, ingresa chronicle.googleapis.com para inspeccionar el uso y los límites actuales. Para obtener más información, consulta Visualiza las cuotas en la consola de Google Cloud .
Si tu integración de transferencia, automatización o emisión de tickets de producción requiere límites más altos, selecciona la casilla de verificación junto a la cuota correspondiente y haz clic en Editar (o Editar cuotas) para solicitar un aumento. Para obtener pasos detallados, consulta Solicita un ajuste de cuota. También puedes enviar una solicitud de aumento de cuota a través de la Atención al cliente de Cloud o de tu representante de Google SecOps.

Audita el uso restante de la API heredada

Puedes identificar las llamadas restantes a la API de SOAR heredada con Logging, las notificaciones del sistema en el producto o el extremo de resumen de uso de la API heredada.

Registro de consultas

Las advertencias de baja de la API heredada (labels.auth_deprecation="true") se emiten como registros operativos de SOAR con gravedad WARNING en resource.labels.namespace_name="chronicle-soar" (consulta Recopila registros de la plataforma de SOAR), en lugar de en los registros de auditoría de Cloud. Solo se exportan a tu proyecto de Google Cloud las advertencias que requieren acciones del cliente (labels.actionable_by="Customer"). Las llamadas internas del sistema y de la IU de Google se filtran automáticamente.

Ejecuta las siguientes consultas en el Explorador de registros:

Atribución de agente remoto (labels.is_remote="true"): Indica llamadas heredadas desde código que se ejecuta en un agente remoto. Primero, actualiza el agente remoto a la versión 2.6.2 o una posterior, y mígralo a la autenticación de la cuenta de servicio (consulta Migra la infraestructura de autenticación del agente remoto). Una vez que el agente remoto se actualiza y se configura con una cuenta de servicio de Google Cloud , el sondeo del plano de control del agente usa OAuth 2.0. La atribución completa de etiquetas de componentes para las llamadas al SDK del agente remoto se lanzará por etapas en producción. Si las entradas continúan después de migrar el agente, verifica si hay integraciones o código personalizado desactualizados que se ejecuten en ese agente.
Verificación de finalización de registro cero de 30 días (todas las llamadas heredadas que requieren acciones del cliente):
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
```
La migración de la API se completará cuando esta consulta no devuelva ningún registro durante 30 días consecutivos.
Secuencias de comandos externas y herramientas de terceros que llaman directamente a las APIs heredadas (AppKey):
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="false"
```
Los campos emitidos incluyen labels.app_key (el identificador de clave de API heredado), labels.via_xlb ("true" para la entrada externa) y la ruta HTTP llamada en textPayload (Deprecated direct AppKey authentication detected (Route: ROUTE).).
Integraciones de Content Hub obsoletas: Para verificar si las integraciones comerciales instaladas aún llaman a las APIs de SOAR heredadas, ejecuta la siguiente consulta para enumerar las entradas de baja que coincidan (consulta Integraciones de respuesta listas para usar):
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="true"
labels.is_custom="false"
```
Figura 1. Resultados de la consulta del Explorador de registros que muestran las entradas de baja de una integración comercial obsoleta.

Expande una entrada de registro coincidente para ver labels.integration_name, labels.integration_version, labels.latest_integration_version y el componente activador (labels.action_name, labels.connector_name, labels.job_name o labels.playbook_name):

Figura 2. Entrada de registro de baja expandida que muestra las versiones de integración comercial instaladas y más recientes.

También puedes consultar la lista de OutdatedIntegrations en el informe de resumen de uso de la API heredada.
Código de Python personalizado que realiza llamadas HTTP manuales: Ejecuta resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" (consulta Migra llamadas a la API personalizadas a la API de Chronicle).

Revisa las notificaciones del sistema en el producto

A medida que esta función esté disponible en las instancias de Google SecOps, las notificaciones del sistema mostrarán un resumen de las llamadas a la API heredadas que requieren acciones del cliente de las últimas 24 horas en las integraciones de Content Hub, los componentes de IDE personalizados y las claves de API externas obsoletas, de forma similar al siguiente ejemplo:

Non-1P API usage summary (last 24h): 2294 legacy API call(s) require action.
Content Hub - Update 1 outdated integration(s): GoogleChronicle (v94->v98).
IDE - Refactor 15 custom component(s): Action 'CustomAction' (LegacyAuthCases),
Connector 'CustomConnector' (LegacyAuthCases), Job 'CustomJob'
(LegacyAuthCases) (+12 more).
Settings > API Keys - Migrate 1 external key(s) to 1P auth:
'example_external_automation_key'.

Consulta el extremo del resumen de uso de la API heredada

También puedes consultar GET /api/external/v1/logging/non-1p-api-usage directamente para recuperar un informe JSON agregado de las llamadas recientes a la API heredada:

En Configuración de SOAR > Avanzada > Claves de API, crea o selecciona una clave de API heredada asignada a un grupo de permisos que incluya el permiso Configuración. Para obtener instrucciones, consulta Autentícate en la API de SOAR heredada.

Envía una solicitud GET con el encabezado AppKey (establece hoursBack entre 1 y 168; el valor predeterminado es 24):

curl -H "AppKey: API_KEY" \
  "https://INSTANCE.siemplify-soar.com/api/external/v1/logging/non-1p-api-usage?hoursBack=24"

La respuesta agrupa las advertencias de baja que requieren acciones del cliente en las siguientes secciones:

OutdatedIntegrations: Enumera las integraciones comerciales de Content Hub en las que InstalledVersion es anterior a LatestVersion, incluidos IntegrationName, InstalledVersion, LatestVersion, ActionNeeded, InvocationCount, FirstUsedTimestamp, LastUsedTimestamp y los componentes afectados (AffectedActions, AffectedConnectors, AffectedJobs, AffectedPlaybooks), de forma similar al siguiente ejemplo:

{
  "OutdatedIntegrations": [
    {
      "IntegrationName": "GoogleChronicle",
      "InstalledVersion": "94",
      "LatestVersion": "98",
      "ActionNeeded": "Upgrade integration to v98 in Content Hub",
      "AffectedActions": ["Ping"],
      "AffectedConnectors": ["Google Chronicle - Chronicle Alerts Connector"],
      "InvocationCount": 202,
      "FirstUsedTimestamp": "2026-10-14T19:16:31Z",
      "LastUsedTimestamp": "2026-10-14T19:44:54Z"
    }
  ]
}

CustomCode: Muestra una lista de los componentes personalizados del SDK (ComponentType: Action, Connector, Job, Playbook o Custom Script) que realizan llamadas manuales a la API heredada, incluidos ComponentName, IntegrationName, AffectedPlaybooks, RoutesUsed, InvocationCount, FirstUsedTimestamp y LastUsedTimestamp.

DirectAppKeys: Enumera las llamadas externas directas AppKey realizadas fuera del SDK, incluidas AppKey, ActionNeeded, RoutesUsed, InvocationCount, FirstUsedTimestamp y LastUsedTimestamp, de forma similar al siguiente ejemplo:

{
  "DirectAppKeys": [
    {
      "AppKey": "example_external_automation_key",
      "ActionNeeded": "Migrate external script or automation to use Google Cloud service account or OAuth authentication",
      "RoutesUsed": [
        "GET /api/external/v1/cases/GetCaseFullDetails/14",
        "GET /api/external/v1/dynamic-cases/GetCaseDetails/14",
        "GET /api/external/v1/ide/GetIdeItemCards",
        "GET /api/external/v1/jobs/GetInstalledJobs",
        "GET /api/external/v1/jobs/GetJobHistoryLogs/jobIdStr",
        "GET /api/external/v1/logging/non-1p-api-usage",
        "GET /api/external/v1/playbooks/GetWorkflowFullInfoWithEnvFilterByIdentifier/00000000-0000-0000-0000-000000000000",
        "POST /api/external/v1/ide/GetIdeItem",
        "POST /api/external/v1/ide/TestItem",
        "POST /api/external/v1/integrations/GetOptionalIntegrationInstances",
        "POST /api/external/v1/jobs/RunJob",
        "POST /api/external/v1/playbooks/AttacheWorkflowToCase",
        "POST /api/external/v1/playbooks/GetWorkflowMenuCardsWithEnvFilter",
        "POST /api/external/v1/playbooks/RerunPlaybook"
      ],
      "InvocationCount": 1084,
      "FirstUsedTimestamp": "2026-10-14T19:30:15.169684Z",
      "LastUsedTimestamp": "2026-10-14T20:24:13.552893800Z"
    }
  ]
}

TopOffenders (TopAppKeys y TopRoutes): Resume las identidades de AppKey heredadas y las rutas HTTP (método y ruta HTTP) que se usan con más frecuencia para ayudarte a priorizar el trabajo de migración.

¿Necesitas más ayuda? Obtén respuestas de miembros de la comunidad y profesionales de Google SecOps.