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

Neste documento, descrevemos as etapas e considerações para ajudar você a atualizar as referências da API programática para os endpoints de API SOAR como parte da API Chronicle.

A plataforma da API 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.

A API SOAR legada e as chaves de API vão continuar disponíveis até 31 de março de 2027. Depois disso, elas vão deixar de funcionar.

Integrações de resposta prontas para uso

Se você estiver usando uma versão de integração desatualizada que chama as APIs SOAR legadas, atualize o pacote de integração antes de 31 de março de 2027:

Integrações do Content Hub: abra o Content Hub no Google Security Operations e atualize as integrações comerciais desatualizadas para as versões mais recentes. Para mais informações, consulte Visão geral do Content Hub.
Complemento do Splunk: se você usa o complemento do Chronicle SOAR para o Splunk, faça upgrade do TA-Siemplify no Splunk para a versão mais recente. Depois de fazer o upgrade, reconfigure o complemento para usar o endpoint regional da API Chronicle e as credenciais da conta de serviço do Google Cloud .

Pré-requisitos

Antes de migrar as chamadas de API do SOAR para a API Chronicle, conclua a Etapa 1 da migração (Google.com aparece ao lado da versão do sistema em Configurações do SOAR > Gerenciamento de licenças). É possível testar e migrar chamadas de API programáticas do Chronicle antes ou depois de ativar o Google Cloud Identity and Access Management (IAM) para grupos de permissões do SOAR.

Principais mudanças e melhorias

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

Área do recurso	API antiga	Nova API	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 planas	Design voltado a recursos	Esse novo design melhora a consistência dos dados e simplifica a manipulação de objetos.
Nomeação de endpoints	Inconsistente	RESTful e padronizado	A nomenclatura consistente torna a API mais intuitiva e fácil de integrar.

Programação da descontinuação

A superfície da API siemplify-soar.com legada e a autenticação AppKey vão continuar disponíveis até 31 de março de 2027. Depois disso, elas vão deixar de funcionar.

Até 31 de março de 2027, as APIs legadas do SOAR vão continuar funcionando em paralelo com a API Chronicle, mesmo depois que você ativar o Google Cloud IAM. Assim, você pode migrar e validar gradualmente cada componente no seu próprio ritmo, sem interromper os fluxos de trabalho ativos.

Como a API SOAR legada é menos eficiente que a API Chronicle, recomendamos migrar para as substitutas da API Chronicle o quanto antes e antes de 31 de março de 2027 para evitar interrupções no serviço.

Etapas da migração

Nesta seção, descrevemos as etapas para migrar seus aplicativos para a API Chronicle:

Consulte a documentação

Conheça 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 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 ou ação personalizada, o Google recomenda que você envie as mudanças para uma integração de teste primeiro. Esse processo permite que você teste 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 modo de testes de integração, consulte Testar integrações no modo de testes.

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. O Chronicle é um serviço regional e só aceita 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 o seguinte:

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. Use v1 quando disponível ou use v1beta ou v1alpha se v1 ainda não estiver disponível (consulte a tabela de mapeamento da API SOAR para saber qual versão é compatível com cada endpoint).
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 de cliente do Google Security Operations SIEM.

Endereços regionais:

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
nós: https://us-chronicle.googleapis.com
eu: https://eu-chronicle.googleapis.com

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

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

Atualizar o método de autenticação

A API Chronicle usa o IAM do Google Cloud para autenticação. Atualize suas integrações personalizadas ou aplicativos externos para implementar esse fluxo de autenticação. Verifique se o usuário ou a conta de serviço que executa o script tem as permissões necessárias para os endpoints de destino. Para mais informações, consulte Autenticar na API Chronicle.

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

Se você estiver usando uma conta de serviço ou uma federação de identidade de 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 aos papéis e ambientes do SOC.

Para conceder acesso à conta de serviço ou acesso à federação de identidade de carga de trabalho ao Google SecOps, é necessário mapear 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 aos papéis do SOC e aos ambientes necessários para realizar tarefas automatizadas ou operações de API.

Observação: conceder papéis do IAM do Google Cloud a uma conta de serviço ou principal é necessário, mas não suficiente para o acesso à API SOAR do Google SecOps. Se a conta de serviço não estiver explicitamente mapeada em Mapeamento de grupo, as solicitações de API vão falhar com um erro 401 UNAUTHENTICATED, mesmo quando todos os papéis do IAM necessários para envolvidos no projeto estiverem configurados.

Acesse Configurações > Gerenciamento de acesso > Mapeamento de grupos.
Clique em add 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 uma das seguintes opções:
- O endereço de e-mail completo da sua conta de serviço, se a identidade tiver sido configurada usando o Cloud Identity.
- A string principal da Identidade da carga de trabalho, se a identidade tiver sido 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 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 dos usuários 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 como mapear 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 as estruturas de endpoint fornecidos na referência da API. Nem todos os métodos mudaram significativamente, e alguns códigos 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.

Migrar chamadas de API personalizadas para a API Chronicle

Observação: em breve, o Google vai lançar em etapas o suporte à plataforma e as instruções de migração de autoatendimento para chamadas HTTP manuais no código Python personalizado do SOAR. Não modifique o código Python personalizado interno até que essas instruções sejam publicadas. As chamadas legadas de siemplify.API_ROOT e siemplify.api_key vão continuar funcionando até 31 de março de 2027. Quando a migração interna de código personalizado for iniciada, os scripts que chamam endpoints de API Chronicle que não são do SDK vão representar uma conta de serviço de destino que tenha as permissões necessárias do IAM e esteja autorizada em Configurações do SOAR > Avançado > Mapeamento de grupo (consulte Mapear a conta de serviço ou a Identidade da carga de trabalho para os parâmetros do SOAR). Os scripts externos executados fora do Google SecOps podem ser migrados agora usando as etapas nas seções anteriores.

Nem todo código Python personalizado no Google SecOps exige mudanças:

Os métodos de SDK integrados não exigem mudanças no código: o código Python personalizado em integrações personalizadas, ações de playbook, conectores e jobs que usam métodos de SDK integrados padrão, como siemplify.add_comment(), siemplify.get_case_comments() ou siemplify.update_alerts_additional_data(), não exigem modificações no código. O Google SecOps encaminha automaticamente os métodos integrados do SDK do Siemplify pela superfície de API unificada.
Somente as solicitações HTTP manuais precisam de atualizações: você só precisa atualizar os scripts Python personalizados que criam manualmente solicitações HTTP para APIs SOAR legadas usando propriedades do SDK. Por exemplo, criar um URL com siemplify.API_ROOT e autenticar com siemplify.api_key usando requests ou siemplify.session. Para identificar os componentes personalizados afetados, execute resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" na Análise de registros (inspecionando labels.integration_name, labels.action_name, labels.connector_name, labels.job_name e labels.playbook_name) ou verifique a lista CustomCode no relatório de resumo de uso da API legada.

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.
Executar testes: realize testes automatizados e manuais para confirmar a precisão e a validade.
Monitorar o desempenho: avalie o desempenho do aplicativo com a nova API.

Cotas e limites de taxa

A API Chronicle aplica Google Cloud cotas no nível do projeto para manter a disponibilidade do serviço e evitar o tráfego descontrolado:

Cotas padrão: a API Chronicle aplica limites de solicitações por minuto (RPM) no nível do projeto do Google Cloud , normalmente 6.000 RPM por projeto, com sub-limites regionais de API.
Erros de limitação de taxa (HTTP 429): se uma integração ou um script externo exceder a cota do projeto, a API Chronicle vai retornar HTTP 429 (RESOURCE_EXHAUSTED ou TooManyRequestsException).

Para conferir o uso atual da cota da API Chronicle ou solicitar um limite maior, siga estas etapas:

No console do Google Cloud , acesse IAM e administrador > Cotas e limites do sistema:

Acesse Cotas e limites do sistema
Clique em Filtrar, selecione Serviço e insira chronicle.googleapis.com para inspecionar o uso e os limites atuais. Para mais informações, consulte Ver cotas no console do Google Cloud .
Se a integração de ingestão, automação ou emissão de tíquetes de produção exigir limites mais altos, marque a caixa de seleção ao lado da cota relevante e clique em Editar (ou Editar cotas) para solicitar um aumento. Para ver as etapas detalhadas, consulte Solicitar um ajuste de cota. Também é possível enviar uma solicitação de aumento de cota pelo Cloud Customer Care ou pelo seu representante do Google SecOps.

Auditar o uso restante da API legada

É possível identificar as chamadas de API legadas do SOAR restantes usando o Logging, as notificações do sistema no produto ou o endpoint de resumo de uso da API legada.

Registro de consultas

Os avisos de descontinuação da API legada (labels.auth_deprecation="true") são emitidos como registros operacionais do SOAR com gravidade WARNING em resource.labels.namespace_name="chronicle-soar" (consulte Coletar registros da plataforma SOAR), em vez de nos Registros de Auditoria do Cloud. Somente os avisos que exigem ação do cliente (labels.actionable_by="Customer") são exportados para o projeto do Google Cloud . As chamadas de sistema e a interface interna do Google são filtradas automaticamente.

Execute as seguintes consultas na Análise de registros:

Atribuição de agente remoto (labels.is_remote="true"): indica chamadas legadas de código em execução em um agente remoto. Primeiro, faça upgrade do agente remoto para a versão 2.6.2 ou mais recente e migre-o para a autenticação da conta de serviço (consulte Migrar a infraestrutura de autenticação do agente remoto). Depois que o agente remoto é atualizado e configurado com uma conta de serviço do Google Cloud , a própria sondagem do plano de controle do agente usa o OAuth 2.0. A atribuição completa de rótulos de componentes para chamadas do SDK do agente remoto está sendo lançada em etapas na produção. Se as entradas continuarem após a migração do agente, verifique se há integrações desatualizadas ou código personalizado em execução nesse agente.
Verificação de conclusão de zero registro em 30 dias (todas as chamadas legadas que exigem ação do cliente):
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
```
A migração da API estará concluída quando essa consulta não retornar nenhum registro por 30 dias consecutivos.
Scripts externos e ferramentas de terceiros que chamam APIs legadas diretamente (AppKey):
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="false"
```
Os campos emitidos incluem labels.app_key (o identificador de chave de API legado), labels.via_xlb ("true" para entrada externa) e a rota HTTP chamada em textPayload (Deprecated direct AppKey authentication detected (Route: ROUTE).).
Integrações desatualizadas do Content Hub: para verificar se as integrações comerciais instaladas ainda chamam APIs SOAR legadas, execute a consulta a seguir para listar as entradas de descontinuação correspondentes (consulte Integrações de resposta prontas para uso):
```
resource.labels.namespace_name="chronicle-soar"
labels.auth_deprecation="true"
labels.is_system="true"
labels.is_custom="false"
```
Figura 1. Resultados da consulta da Análise de registros listando entradas de descontinuação para uma integração comercial desatualizada.

Expanda uma entrada de registro correspondente para ver labels.integration_name, labels.integration_version, labels.latest_integration_version e o componente acionador (labels.action_name, labels.connector_name, labels.job_name ou labels.playbook_name):

Figura 2. Entrada de registro de descontinuação expandida mostrando as versões de integração comercial instaladas e mais recentes.

Você também pode verificar a lista de OutdatedIntegrations no relatório de resumo de uso da API legada.
Código Python personalizado que faz chamadas HTTP manuais: execute resource.labels.namespace_name="chronicle-soar" AND labels.auth_deprecation="true" AND labels.is_custom="true" (consulte Migrar chamadas de API personalizadas para a API Chronicle).

Verificar as notificações do sistema no produto

À medida que esse recurso é disponibilizado nas instâncias do Google SecOps, as notificações do sistema mostram um resumo das chamadas de API legadas que exigem ação do cliente nas últimas 24 horas em integrações desatualizadas do Content Hub, componentes personalizados do ambiente de desenvolvimento integrado e chaves de API externas, como no exemplo a seguir:

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

Consultar o endpoint de resumo de uso da API legada

Também é possível consultar GET /api/external/v1/logging/non-1p-api-usage diretamente para recuperar um relatório JSON agregado de chamadas de API legadas recentes:

Em Configurações do SOAR > Avançado > Chaves de API, crie ou selecione uma chave de API legada atribuída a um grupo de permissões que inclua a permissão Configurações. Para instruções, consulte Autenticar na API SOAR legada.

Envie uma solicitação GET com o cabeçalho AppKey (defina hoursBack entre 1 e 168; o padrão é 24):

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

A resposta agrupa os avisos de descontinuação que exigem ação do cliente nas seguintes seções:

OutdatedIntegrations: lista as integrações comerciais do Content Hub em que InstalledVersion é mais antigo que LatestVersion, incluindo IntegrationName, InstalledVersion, LatestVersion, ActionNeeded, InvocationCount, FirstUsedTimestamp, LastUsedTimestamp e os componentes afetados (AffectedActions, AffectedConnectors, AffectedJobs, AffectedPlaybooks), de forma semelhante ao exemplo a seguir:

{
  "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: lista componentes personalizados do SDK (ComponentType: Action, Connector, Job, Playbook ou Custom Script) que fazem chamadas de API legadas manuais, incluindo ComponentName, IntegrationName, AffectedPlaybooks, RoutesUsed, InvocationCount, FirstUsedTimestamp e LastUsedTimestamp.

DirectAppKeys: lista chamadas externas diretas de AppKey feitas fora do SDK, incluindo AppKey, ActionNeeded, RoutesUsed, InvocationCount, FirstUsedTimestamp e LastUsedTimestamp, como no exemplo a seguir:

{
  "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 e TopRoutes): resume as identidades legadas do AppKey e as rotas HTTP (método e rota HTTP) mais usadas para ajudar você a priorizar o trabalho de migração.

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