Reorganizamos a estrutura de navegação da documentação para se alinhar diretamente aos seus fluxos de trabalho operacionais. Consulte as notas da versão e o vídeo explicativo para mais informações.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Migrar para a API Chronicle

Compatível com:

Google SecOps SOAR

Este documento é válido para quem chama a API SOAR de forma programática usando integrações, scripts personalizados ou ações personalizadas. Ele descreve as etapas e considerações para ajudar você a atualizar as referências de API programáticas para os novos endpoints da API SOAR como parte da API Chronicle.

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

A API SOAR legada e as chaves de API vão ficar disponíveis até 30 de novembro de 2026. Depois disso, elas não vão mais funcionar.

Pré-requisitos

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

Conclua a etapa 1 da migração.

Principais mudanças e melhorias

A tabela a seguir destaca as principais diferenças entre as plataformas de API antiga e nova

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

Programação da descontinuação

A plataforma de API antiga para SOAR será totalmente descontinuada em 30 de novembro 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:

Consulte a documentação

Familiarize-se com a documentação completa da nova API, incluindo o Guia de Referência da API Chronicle.

Mapear endpoints para a nova plataforma de API

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

Opcional: criar uma integração de preparo

Se você estiver editando uma integração personalizada ou um componente de uma integração comercial, recomendamos que envie as mudanças para uma integração de preparo primeiro. 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 mais detalhes sobre o preparo da integração, consulte Testar integrações no modo de preparo.

Atualizar o endpoint e os URLs do serviço

Um endpoint de serviço é o URL de 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 do endpoint final previsível. O exemplo a seguir mostra a nova estrutura de URL do endpoint:

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

Essa estrutura torna 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 do 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), o mesmo que os 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
us: 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 Google Cloud o IAM para autenticação. Você precisa atualizar seu aplicativo ou integração de resposta para implementar esse novo fluxo de autenticação. Confira se o usuário que executa o script tem as permissões corretas para os endpoints que está tentando acessar. Para implementar esse novo fluxo, atualize as integrações ou aplicativos de resposta. Confira se o usuário que executa o script tem as permissões necessárias para os endpoints de destino. Para instruções detalhadas, consulte a página Autenticar na API Chronicle.

Mapear a conta de serviço ou a identidade da carga de trabalho para os parâmetros SOAR

Se você estiver usando uma conta de serviço ou a federação de identidade da carga de trabalho para autenticar na API Chronicle, autorize-a na plataforma para garantir que ela possa se comunicar com o Google SecOps. Esse mapeamento é necessário para fornecer à conta de serviço ou à identidade da carga de trabalho o acesso necessário às funções e aos ambientes do SOC.

Para conceder acesso à conta de serviço ou acesso à federação de identidade da carga de trabalho ao Google SecOps, mapeie a identidade para os parâmetros de controle de acesso da plataforma. Esse mapeamento é uma etapa obrigatória para fornecer à identidade o acesso necessário às funções do SOC e aos ambientes necessários para realizar tarefas automatizadas ou operações de API.

Acesse Configurações do SOAR > Avançado > Mapeamento de grupos.
Clique em adicionar Adicionar.

Preencha os campos na caixa de diálogo Adicionar mapeamento para mapear a identidade para os parâmetros de controle de acesso da plataforma.

No campo IdP / Grupo de usuários, insira um dos seguintes:
- O endereço de e-mail completo da sua conta de serviço, se a identidade foi configurada usando o Cloud Identity.
- A string principal da Identidade da carga de trabalho, se a identidade foi configurada usando a Federação de identidade de colaboradores.

Configure os seguintes campos de controle de acesso:

Campo	Descrição
Grupos de permissões	Selecione os grupos de permissões para definir a quais módulos e submódulos a identidade pode acessar.
Funções do SOC	Selecione as funções do SOC para definir o papel da identidade (como Nível 1).
Ambientes	Selecione os ambientes ou grupos de ambientes que a identidade pode acessar (como Todos os ambientes).
Participantes do grupo	Insira os e-mails de usuário necessários, se aplicável. Pressione Enter depois de adicionar cada e-mail.
Ações restritas	Selecione as ações restritas para limitar operações específicas nos módulos.

Clique em Adicionar.

Para mais informações sobre o mapeamento de usuários e contas de serviço, consulte Mapear usuários na plataforma usando a identidade de terceiros ou Mapear usuários na plataforma usando o Cloud Identity.

Atualizar a lógica da API

Analise os novos modelos de dados e estruturas de endpoints fornecidos na referência da API. Nem todos os métodos mudaram significativamente, e alguns códigos atuais podem ser reutilizados. 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:

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

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