Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Migrer vers l'API Chronicle

Compatible avec :

Google SecOps SOAR

Ce document décrit les étapes et les points à prendre en compte pour vous aider à mettre à jour la documentation de référence de l'API programmatique vers les points de terminaison de l'API SOAR dans le cadre de l'API Chronicle.

La surface de l'API Chronicle introduit plusieurs améliorations conçues pour simplifier votre processus de développement. Elle résout également les limites et les complexités de l'ancienne API.

L'ancienne API SOAR et les anciennes clés API resteront disponibles jusqu'au 31 mars 2027, date à laquelle elles cesseront de fonctionner.

Intégrations de réponses prêtes à l'emploi

Si vous utilisez une version d'intégration obsolète qui appelle les anciennes API SOAR, mettez à jour le package d'intégration avant le 31 mars 2027 :

Intégrations du hub de contenus : ouvrez le hub de contenus dans Google Security Operations et mettez à jour les intégrations commerciales obsolètes vers leurs dernières versions. Pour en savoir plus, consultez Présentation du hub de contenus.
Module complémentaire Splunk : si vous utilisez le module complémentaire Chronicle SOAR pour Splunk, mettez à niveau TA-Siemplify dans Splunk vers la dernière version. Après la mise à niveau, reconfigurez le module complémentaire pour qu'il utilise le point de terminaison de l'API Chronicle régional et les identifiants du compte de service Google Cloud .

Prérequis

Avant de migrer les appels d'API SOAR vers l'API Chronicle, terminez l'étape 1 de la migration (Google.com apparaît à côté de la version du système dans Paramètres SOAR > Gestion des licences). Vous pouvez tester et migrer les appels d'API Chronicle programmatiques avant ou après l'activation d' Google Cloud Identity and Access Management (IAM) pour les groupes d'autorisations SOAR.

Principaux changements et améliorations

Le tableau suivant met en évidence les principales différences entre l'ancienne et la nouvelle surface d'API :

Zone de la fonctionnalité	Ancienne API	Nouvelle API	Détails
Authentification	Jeton d'API	OAuth 2.0	La nouvelle méthode d'authentification offre une sécurité renforcée et standardise le processus.
Modèles de données	Structures plates	Conception orientée ressources	Cette nouvelle conception améliore la cohérence des données et simplifie la manipulation des objets.
Nommage des points de terminaison	Incohérent	RESTful et standardisé	La cohérence des noms rend l'API plus intuitive et plus facile à intégrer.

Planning d'abandon

L'ancienne surface d'API siemplify-soar.com et l'authentification AppKey resteront disponibles jusqu'au 31 mars 2027, date à laquelle elles cesseront de fonctionner.

Jusqu'au 31 mars 2027, les anciennes API SOAR continueront de fonctionner en parallèle de l'API Chronicle, même après l'activation d' Google Cloud IAM. Vous pourrez ainsi migrer et valider progressivement chaque composant à votre rythme, sans perturber les workflows actifs.

L'ancienne API SOAR étant moins efficace que l'API Chronicle, nous vous recommandons de migrer vers les alternatives de l'API Chronicle dès que possible, et avant le 31 mars 2027 pour éviter toute interruption de service.

Procédure de migration

Cette section décrit les étapes à suivre pour migrer vos applications vers l'API Chronicle :

Consulter la documentation

Familiarisez-vous avec la documentation complète de la nouvelle API, y compris le guide de référence de l'API Chronicle.

Mapper les points de terminaison vers la nouvelle surface d'API

Identifiez les nouveaux points de terminaison correspondants pour chacun des anciens appels d'API effectués par votre application. De même, mappez les anciens modèles de données aux nouveaux, en tenant compte des modifications structurelles ou des nouveaux champs. Pour en savoir plus, consultez Table de mappage des points de terminaison d'API.

Facultatif : Créer une intégration de préproduction

Si vous modifiez une intégration ou une action personnalisée, Google vous recommande de transférer d'abord les modifications vers une intégration de préproduction. Ce processus vous permet d'effectuer des tests sans affecter vos flux d'automatisation de production. Si vous migrez une application personnalisée qui utilise l'API SOAR, vous pouvez passer à l'étape suivante. Pour en savoir plus sur la préproduction des intégrations, consultez Tester des intégrations en mode préproduction.

Mettre à jour le point de terminaison et les URL du service

Un point de terminaison de service est l'URL de base qui spécifie l'adresse réseau d'un service d'API. Un même service peut avoir plusieurs points de terminaison de service. Chronicle est un service régional et n'est compatible qu'avec les points de terminaison régionaux.

Tous les nouveaux points de terminaison utilisent un préfixe cohérent, ce qui rend l'adresse finale du point de terminaison prévisible. L'exemple suivant montre la nouvelle structure d'URL du point de terminaison :

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

Cette structure donne l'adresse finale suivante au point de terminaison :

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

Où :

service_endpoint : adresse de service régional
api_version : version de l'API à interroger. Utilisez v1 lorsqu'il est disponible, ou utilisez v1beta ou v1alpha si v1 n'est pas encore disponible (consultez le tableau de mappage de l'API SOAR pour connaître la version compatible avec chaque point de terminaison).
project_id : ID du projet (le même que celui que vous avez défini pour vos autorisations IAM)
location : emplacement de votre projet (région), identique aux points de terminaison régionaux
instance_id : ID client de votre solution SIEM Google Security Operations.

Adresses régionales :

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

Par exemple, pour obtenir la liste de toutes les demandes d'un projet aux États-Unis :

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

Mettre à jour la méthode d'authentification

L'API Chronicle utilise Google Cloud IAM pour l'authentification. Mettez à jour vos intégrations personnalisées ou vos applications externes pour implémenter ce flux d'authentification. Assurez-vous que l'utilisateur ou le compte de service qui exécute le script dispose des autorisations requises pour les points de terminaison cibles. Pour en savoir plus, consultez S'authentifier auprès de l'API Chronicle.

Mapper le compte de service ou Workload Identity aux paramètres SOAR

Si vous utilisez un compte de service ou la fédération d'identité de charge de travail pour vous authentifier auprès de l'API Chronicle, vous devez l'autoriser sur la plate-forme pour vous assurer qu'il peut communiquer avec Google SecOps. Ce mappage est nécessaire pour fournir au compte de service ou à l'identité de charge de travail l'accès nécessaire aux rôles et environnements SOC.

Pour accorder l'accès à un compte de service ou l'accès à la fédération d'identité de charge de travail à Google SecOps, vous devez mapper l'identité aux paramètres de contrôle des accès de la plate-forme. Ce mappage est une étape obligatoire pour fournir à l'identité l'accès nécessaire aux rôles SOC et aux environnements requis pour effectuer des tâches automatisées ou des opérations d'API.

Remarque : L'attribution de rôles IAM Google Cloud à un compte de service ou à un compte principal est nécessaire, mais pas suffisante pour accéder à l'API Google SecOps SOAR. Si le compte de service n'est pas explicitement mappé dans Mappage de groupe, les requêtes API échouent avec une erreur 401 UNAUTHENTICATED, même si tous les rôles IAM requis au niveau du projet sont configurés.

Accédez à Paramètres > Gestion des accès > Mappage de groupes.
Cliquez sur add Ajouter.

Complétez les champs de la boîte de dialogue Ajouter un mappage pour mapper l'identité aux paramètres de contrôle des accès de la plate-forme.

Dans le champ IdP / User group (IdP/Groupe d'utilisateurs), saisissez l'une des valeurs suivantes :
- Adresse e-mail complète de votre compte de service, si l'identité a été configurée à l'aide de Cloud Identity.
- Chaîne du compte principal Workload Identity, si l'identité a été configurée à l'aide de la fédération des identités des employés.

Configurez les champs de contrôle des accès suivants :

Champ	Description
Groupes d'autorisations	Sélectionnez les groupes d'autorisations pour définir les modules et sous-modules auxquels l'identité peut accéder.
Rôles dans le SOC	Sélectionnez les rôles SOC pour définir le rôle de l'identité (par exemple, Niveau 1).
Environnements	Sélectionnez les environnements ou les groupes d'environnements auxquels l'identité peut accéder (par exemple, Tous les environnements).
Membres du groupe	Saisissez les adresses e-mail des utilisateurs requis, le cas échéant. Appuyez sur Entrée après avoir ajouté chaque adresse e-mail.
Actions limitées	Sélectionnez les actions restreintes pour limiter des opérations spécifiques dans les modules.

Cliquez sur Ajouter.

Pour en savoir plus sur le mappage des utilisateurs et des comptes de service, consultez Mapper les utilisateurs de la plate-forme à l'aide d'une identité tierce ou Mapper les utilisateurs de la plate-forme à l'aide de Cloud Identity.

Mettre à jour la logique de l'API

Analysez les nouveaux modèles de données et les structures de points de terminaison fournis dans la documentation de référence de l'API. Toutes les méthodes n'ont pas changé de manière significative, et une partie du code existant peut être réutilisée. L'objectif principal est d'examiner la nouvelle documentation de référence et, pour chaque cas d'utilisation spécifique, d'identifier et d'implémenter les modifications nécessaires aux noms de champs et aux structures de données dans la logique de votre application.

Migrer les appels d'API personnalisés vers l'API Chronicle

Remarque : Google va bientôt publier progressivement des instructions de migration en libre-service et une compatibilité de la plate-forme pour les appels HTTP manuels dans le code Python personnalisé SOAR. Ne modifiez pas le code Python personnalisé interne tant que ces instructions n'ont pas été publiées. Les anciens appels siemplify.API_ROOT et siemplify.api_key continueront de fonctionner jusqu'au 31 mars 2027. Lorsque la migration du code personnalisé interne est lancée, les scripts appelant des points de terminaison d'API Chronicle non SDK empruntent l'identité d'un compte de service cible disposant des autorisations IAM requises et autorisé dans Paramètres SOAR > Avancé > Mappage de groupe (voir Mapper le compte de service ou l'identité de charge de travail aux paramètres SOAR). Les scripts externes exécutés en dehors de Google SecOps peuvent être migrés dès maintenant en suivant les étapes décrites dans les sections précédentes.

Tous les codes Python personnalisés dans Google SecOps ne nécessitent pas de modifications de code :

Les méthodes SDK intégrées ne nécessitent aucune modification du code : le code Python personnalisé dans les intégrations personnalisées, les actions de playbook, les connecteurs et les jobs qui utilisent des méthodes SDK intégrées standards (comme siemplify.add_comment(), siemplify.get_case_comments() ou siemplify.update_alerts_additional_data()) ne nécessite aucune modification du code. Google SecOps achemine automatiquement les méthodes du SDK Siemplify intégrées via la surface d'API unifiée.
Seules les requêtes HTTP manuelles nécessitent des mises à jour : vous ne devez mettre à jour que les scripts Python personnalisés qui créent manuellement des requêtes HTTP vers les anciennes API SOAR à l'aide des propriétés du SDK (par exemple, en créant une URL avec siemplify.API_ROOT et en vous authentifiant avec siemplify.api_key à l'aide de requests ou siemplify.session). Pour identifier les composants personnalisés concernés, exécutez resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" dans l'explorateur de journaux (en inspectant labels.integration_name, labels.action_name, labels.connector_name, labels.job_name et labels.playbook_name) ou consultez la liste CustomCode dans le rapport récapitulatif sur l'utilisation des anciennes API.

Tester votre intégration

Testez votre application mise à jour dans une intégration de préproduction avant de la déployer en production :

Créez un plan de test : définissez des scénarios de test qui couvrent toutes les fonctionnalités migrées.
Exécuter des tests : exécutez des tests automatisés et manuels pour confirmer l'exactitude et la validité.
Surveiller les performances : évaluez les performances de votre application avec la nouvelle API.

Quotas et limites de débit

L'API Chronicle applique des quotas au niveau du projet Google Cloud pour maintenir la disponibilité du service et éviter un trafic excessif :

Quotas par défaut : l'API Chronicle applique des limites de requêtes par minute (RPM) au niveau du projet Google Cloud , généralement 6 000 RPM par projet, avec des sous-limites d'API régionales.
Erreurs de limitation du débit (HTTP 429) : si une intégration ou un script externe dépasse le quota de votre projet, l'API Chronicle renvoie HTTP 429 (RESOURCE_EXHAUSTED ou TooManyRequestsException).

Pour afficher votre utilisation actuelle du quota de l'API Chronicle ou demander une augmentation de la limite, procédez comme suit :

Dans la console Google Cloud , accédez à IAM et administration > Quotas et limites du système :

Accéder à la page Quotas et limites du système
Cliquez sur Filtrer, sélectionnez Service, puis saisissez chronicle.googleapis.com pour inspecter l'utilisation et les limites actuelles. Pour en savoir plus, consultez Afficher les quotas dans la console Google Cloud .
Si votre intégration d'ingestion, d'automatisation ou de gestion des tickets en production nécessite des limites plus élevées, cochez la case à côté du quota concerné, puis cliquez sur Modifier (ou Modifier les quotas) pour demander une augmentation. Pour connaître la procédure détaillée, consultez Demander un ajustement de quota. Vous pouvez également envoyer une demande d'augmentation de quota via Cloud Customer Care ou votre représentant Google SecOps.

Auditer l'utilisation restante de l'ancienne API

Vous pouvez identifier les appels d'API SOAR hérités restants à l'aide de Logging, des notifications système dans le produit ou du point de terminaison du récapitulatif d'utilisation de l'API héritée.

Journalisation des requêtes

Les avertissements d'abandon de l'ancienne API (labels.auth_deprecation="true") sont émis en tant que journaux opérationnels SOAR de gravité WARNING sous resource.labels.namespace_name="chronicle-soar" (voir Collecter les journaux de la plate-forme SOAR), plutôt que dans Cloud Audit Logs. Seuls les avertissements nécessitant une action de la part du client (labels.actionable_by="Customer") sont exportés vers votre projet Google Cloud . Les appels système et d'UI Google internes sont automatiquement filtrés.

Exécutez les requêtes suivantes dans l'explorateur de journaux :

Attribution de l'agent distant (labels.is_remote="true") : indique les appels d'ancienne version provenant du code exécuté sur un agent distant. Commencez par mettre à niveau l'agent distant vers la version 2.6.2 ou une version ultérieure, puis migrez-le vers l'authentification par compte de service (consultez Migrer l'infrastructure d'authentification de l'agent distant). Une fois l'agent distant mis à niveau et configuré avec un compte de service Google Cloud , l'interrogation du plan de contrôle de l'agent utilise OAuth 2.0. L'attribution complète des libellés de composants pour les appels du SDK de l'agent distant est en cours de déploiement par étapes en production. Si des entrées continuent d'apparaître après la migration de l'agent, recherchez les intégrations obsolètes ou le code personnalisé exécuté sur cet agent.
Vérification de l'absence de journaux après 30 jours (tous les appels dans l'ancienne version nécessitant une action du client) :
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
```
La migration de votre API est terminée lorsque cette requête ne renvoie aucun journal pendant 30 jours consécutifs.
Scripts externes et outils tiers appelant directement les anciennes API (AppKey) :
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="false"
```
Les champs émis incluent labels.app_key (l'ancien identifiant de clé API), labels.via_xlb ("true" pour l'entrée externe) et la route HTTP appelée dans textPayload (Deprecated direct AppKey authentication detected (Route: ROUTE).).
Intégrations Content Hub obsolètes : pour vérifier si les intégrations commerciales installées appellent toujours les anciennes API SOAR, exécutez la requête suivante pour lister les entrées d'obsolescence correspondantes (voir Intégrations de réponse prêtes à l'emploi) :
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="true"
labels.is_custom="false"
```
Figure 1 : Résultats de la requête de l'explorateur de journaux listant les entrées d'abandon pour une intégration commerciale obsolète.

Développez une entrée de journal correspondante pour afficher labels.integration_name, labels.integration_version, labels.latest_integration_version et le composant déclencheur (labels.action_name, labels.connector_name, labels.job_name ou labels.playbook_name) :

Figure 2. Entrée de journal d'abandon développée affichant la version installée et la dernière version de l'intégration commerciale.

Vous pouvez également consulter la liste OutdatedIntegrations dans le rapport récapitulatif sur l'utilisation de l'ancienne API.
Code Python personnalisé effectuant des appels HTTP manuels : exécutez resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" (consultez Migrer les appels d'API personnalisés vers l'API Chronicle).

Consulter les notifications système dans le produit

À mesure que cette fonctionnalité devient disponible dans les instances Google SecOps, les notifications système affichent un résumé des appels d'anciennes API nécessitant une action de la part du client au cours des dernières 24 heures, pour les intégrations Content Hub obsolètes, les composants IDE personnalisés et les clés API externes, comme dans l'exemple suivant :

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'.

Interroger l'ancien point de terminaison du récapitulatif d'utilisation de l'API

Vous pouvez également interroger directement GET /api/external/v1/logging/non-1p-api-usage pour récupérer un rapport JSON agrégé des appels d'API anciens récents :

Dans Paramètres SOAR > Avancé > Clés API, créez ou sélectionnez une ancienne clé API attribuée à un groupe d'autorisations incluant l'autorisation Paramètres. Pour obtenir des instructions, consultez S'authentifier auprès de l'ancienne API SOAR.

Envoyez une requête GET avec l'en-tête AppKey (définissez hoursBack entre 1 et 168 ; la valeur par défaut est 24) :

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

La réponse regroupe les avertissements d'abandon nécessitant une action de la part du client dans les sections suivantes :

OutdatedIntegrations : liste les intégrations Content Hub commerciales où InstalledVersion est antérieur à LatestVersion, y compris IntegrationName, InstalledVersion, LatestVersion, ActionNeeded, InvocationCount, FirstUsedTimestamp, LastUsedTimestamp et les composants concernés (AffectedActions, AffectedConnectors, AffectedJobs, AffectedPlaybooks), comme dans l'exemple suivant :

{
  "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 : liste les composants SDK personnalisés (ComponentType : Action, Connector, Job, Playbook ou Custom Script) qui effectuent des appels d'API anciens manuels, y compris ComponentName, IntegrationName, AffectedPlaybooks, RoutesUsed, InvocationCount, FirstUsedTimestamp et LastUsedTimestamp.

DirectAppKeys : liste les appels AppKey externes directs effectués en dehors du SDK, y compris AppKey, ActionNeeded, RoutesUsed, InvocationCount, FirstUsedTimestamp et LastUsedTimestamp, comme dans l'exemple suivant :

{
  "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 et TopRoutes) : résume les identités AppKey et les routes HTTP (méthode et route HTTP) anciennes les plus fréquemment utilisées pour vous aider à prioriser le travail de migration.

Vous avez encore besoin d'aide ? Obtenez des réponses de membres de la communauté et de professionnels Google SecOps.