Migre pontos finais SOAR para a API Chronicle

Compatível com:

Este documento descreve os passos e as considerações para migrar da superfície da API SOAR descontinuada para a API Chronicle unificada. Este guia destina-se a ajudar na transição de forma simples e eficiente, minimizando a interrupção e tirando partido das novas funcionalidades.

A superfície da API Chronicle introduz várias melhorias concebidas para simplificar o processo de desenvolvimento. Também aborda as limitações e as complexidades presentes na API mais antiga.

Pré-requisitos

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

Principais alterações e melhorias

A tabela seguinte realça as principais diferenças entre as superfícies da API antiga e nova:

Área de funcionalidades API antiga Nova API Detalhes
Autenticação Chave da API OAuth 2.0 O novo método de autenticação oferece segurança melhorada e padroniza o processo.
Modelos de dados Estruturas planas Design orientado para recursos Este novo design melhora a consistência dos dados e simplifica a manipulação de objetos.
Nomenclatura de pontos finais Inconsistente Baseado em REST e padronizado A nomenclatura consistente torna a API mais intuitiva e fácil de integrar.

Agenda de descontinuação

A superfície da API antiga para SOAR vai ser totalmente descontinuada a 30 de junho de 2026. Recomendamos que conclua a migração antes desta data para evitar interrupções no serviço.

Passos de migração

Esta secção descreve os passos para migrar com êxito as suas aplicações para a API Chronicle:

Reveja a documentação

Familiarize-se com a documentação abrangente da nova API, incluindo o guia de referência da API Chronicle.

Mapeie os pontos finais para a nova superfície da API

Identifique os novos pontos finais correspondentes para cada uma das chamadas da API antigas que a sua aplicação faz. Da mesma forma, mapeie os modelos de dados antigos para os novos, tendo em conta quaisquer alterações estruturais ou novos campos. Para obter detalhes, consulte a tabela de mapeamento de pontos finais da API.

Opcional: crie uma integração de preparação

Se estiver a editar uma integração personalizada ou um componente de uma integração comercial, recomendamos que envie primeiro as alterações para uma integração de teste. Este processo permite-lhe fazer testes sem afetar os fluxos de automatização de produção. Se estiver a migrar uma aplicação criada de forma personalizada que usa a API SOAR, pode avançar para o passo seguinte. Para ver detalhes sobre a preparação da integração, consulte o artigo Teste integrações no modo de preparação.

Atualize o ponto final do serviço e os URLs

Um ponto final 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 pontos finais de serviço. O Chronicle é um serviço regional e só suporta pontos finais regionais.

Todos os novos pontos finais usam um prefixo consistente, o que torna o endereço do ponto final final previsível. O exemplo seguinte mostra a nova estrutura do URL do ponto final:

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

Esta estrutura torna o endereço final do ponto final da seguinte forma:

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

Onde:

  • service_endpoint: um endereço de serviço regional
  • api_version: a versão da API a consultar. Pode ser v1alpha, v1beta ou v1.
  • project_id: o ID do projeto (o mesmo projeto que definiu para as suas autorizações de IAM)
  • location: a localização do seu projeto (região); igual aos pontos finais regionais
  • instance_id: O seu ID de cliente do SIEM do Google Security Operations.

Moradas 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

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

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

Por exemplo, para obter uma lista de todos os registos num 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

Atualize o método de autenticação

A nova API usa o Google Cloud IAM para autenticação. Tem de atualizar a sua aplicação ou integração de respostas para implementar este novo fluxo de autenticação. Certifique-se de que o utilizador que executa o script tem as autorizações corretas para os pontos finais aos quais está a tentar aceder.

Atualize a lógica da API

Analise os novos modelos de dados e estruturas de pontos finais fornecidos na referência da API. Nem todos os métodos foram alterados significativamente e é possível reutilizar algum código existente. O objetivo principal é rever a nova documentação de referência e, para cada exemplo de utilização específico, identificar e implementar as alterações necessárias aos nomes dos campos e às estruturas de dados na lógica da sua aplicação.

Teste a integração

Teste a aplicação atualizada numa integração de preparação antes da implementação em produção:

  1. Crie um plano de teste: defina casos de teste que cubram todas as funcionalidades migradas.
  2. Executar testes: execute testes automáticos e manuais para confirmar a precisão e a validade.
  3. Monitorize o desempenho: avalie o desempenho da sua aplicação com a nova API.

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