Migrar endpoints de SOAR para a API Chronicle

Compatível com:

Este documento descreve as etapas e considerações para migrar da plataforma da API SOAR descontinuada para a API unificada do Chronicle. Este guia foi criado para ajudar você a fazer a transição de forma tranquila e eficiente, minimizando interrupções e aproveitando as novas funcionalidades.

A plataforma da API do Chronicle apresenta várias melhorias projetadas para simplificar seu processo de desenvolvimento. Ela também aborda limitações e complexidades presentes na API mais antiga.

Pré-requisitos

Antes de realizar a migração da API SOAR, faça o seguinte:

Principais mudanças e melhorias

A tabela a seguir destaca as principais diferenças entre as superfícies de API antigas e novas:

Área do recurso API antiga Nova API Detalhes
Autenticação Token de API OAuth 2.0 O novo método de autenticação oferece mais segurança e padroniza o processo.
Modelos de dados Estruturas planas Projeto voltado para recursos Esse novo design melhora a consistência dos dados e simplifica a manipulação de objetos.
Nomenclatura de endpoints Inconsistente RESTful e padronizado A nomenclatura consistente torna a API mais intuitiva e fácil de integrar.

Programação de descontinuação

A antiga interface da API para SOAR será totalmente descontinuada em 30 de junho de 2026. Recomendamos que você conclua a migração antes dessa data para evitar interrupções no serviço.

Etapas da migração

Esta seção descreve as etapas para migrar seus aplicativos para a API Chronicle:

Leia a documentação

Leia a documentação completa da nova API, incluindo o guia de referência da API Chronicle.

Mapear endpoints para a nova superfície da API

Identifique os novos endpoints correspondentes para cada uma das chamadas de API antigas feitas pelo seu aplicativo. Da mesma forma, mapeie os modelos de dados antigos para os novos, considerando mudanças estruturais ou novos campos. Para mais detalhes, consulte a tabela de mapeamento de endpoints da API.

Opcional: criar uma integração de teste

Se você estiver editando uma integração personalizada ou um componente de uma integração comercial, recomendamos enviar as mudanças primeiro para uma integração de preparo. Esse processo permite testar sem afetar os fluxos de automação de produção. Se você estiver migrando um aplicativo personalizado que usa a API SOAR, pule para a próxima etapa. Para detalhes sobre o teste de integração, consulte Testar integrações no modo de teste.

Atualizar o endpoint e os URLs do serviço

Um endpoint de serviço é o URL base que especifica o endereço de rede de um serviço de API. Um único serviço pode ter vários endpoints de serviço. O Chronicle é um serviço regional e só oferece suporte a endpoints regionais.

Todos os novos endpoints usam um prefixo consistente, tornando o endereço final previsível. O exemplo a seguir mostra a nova estrutura do URL do endpoint:

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

Essa estrutura cria o endereço final do endpoint da seguinte maneira:

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

Em que:

  • service_endpoint: um endereço de serviço regional
  • api_version: a versão da API a ser consultada. Pode ser v1alpha, v1beta ou v1.
  • project_id: o ID do projeto (o mesmo que você definiu para as permissões do IAM)
  • location: o local do projeto (região), igual aos endpoints regionais.
  • instance_id: é o ID do cliente do Google Security Operations SIEM.

Endereços regionais:

  • 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

  • nós: https://chronicle.us.rep.googleapis.com

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

Por exemplo, para receber uma lista de todos os casos em um projeto nos EUA:

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

Atualizar o método de autenticação

A nova API usa o IAM Google Cloud para autenticação. É necessário atualizar seu aplicativo ou integração de resposta para implementar esse novo fluxo de autenticação. Verifique se o usuário que executa o script tem as permissões corretas para os endpoints que está tentando acessar.

Atualizar a lógica da API

Analise os novos modelos de dados e estruturas de endpoint fornecidos na referência da API. Nem todos os métodos mudaram significativamente, e parte do código atual pode ser reutilizada. O objetivo principal é analisar a nova documentação de referência e, para cada caso de uso específico, identificar e implementar as mudanças necessárias nos nomes de campos e nas estruturas de dados na lógica do aplicativo.

Testar sua integração

Teste o aplicativo atualizado em uma integração de preparo antes de implantar na produção:

  1. Crie um plano de teste: defina casos de teste que cubram todas as funcionalidades migradas.
  2. Execute testes: faça testes automatizados e manuais para confirmar a precisão e a validade.
  3. Monitore a performance: avalie o desempenho do aplicativo com a nova API.

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.