Guia do usuário

É possível executar simulações usando a demonstração da Web fornecida ou chamando a API REST diretamente.

Entrada e saída

Os arquivos de entrada e saída usam o bucket do Cloud Storage da configuração do Terraform.

O diretório de entrada precisa conter os arquivos metrics_config.zip e publisher_config.zip. É possível definir o caminho para ele conforme necessário.

O bucket de saídas contém um diretório simulations, que armazena cada simulação pelo ID. Cada diretório de simulação contém uma pasta inputs com os arquivos de entrada copiados e uma pasta outputs. A pasta outputs contém o bugreport, o arquivo logcat e os arquivos de simulador gerados.

Usar a demonstração na Web

A plataforma inclui um aplicativo da Web baseado em Flutter para fins de demonstração, que permite visualizar, criar e gerenciar simulações. Recomendamos que você crie sua própria interface do usuário personalizada de acordo com suas necessidades.

O app de demonstração é implantado no App Engine e exige que você faça login com uma Conta do Google. Ele é protegido por um ID do cliente OAuth 2.0 configurado no projeto do Google Cloud. A conta conectada precisa ter permissões do IAM para invocar as funções do Cloud implantadas. Consulte Autorizar o acesso com o IAM para ver instruções sobre como conceder as permissões necessárias às contas de usuário, como o papel de invocador do Cloud Functions (roles/cloudfunctions.invoker).

Fluxo de trabalho do usuário

  1. Faça login com sua Conta do Google, autenticada usando o processo do OAuth 2.0.
  2. Confira as simulações na página principal, que lista todas as simulações consultando o banco de dados do Firestore, que contém todas as informações de execução.
  3. Acesse um formulário para programar uma nova simulação clicando no botão de ação + no canto inferior direito. Você fornece vários parâmetros, incluindo o caminho de entrada, o ID do build e o tipo de instância. Para mais informações, consulte Criar uma simulação.
  4. Verifique o status do monitor nas atualizações da lista de simulações, que mostram o status da nova simulação, por exemplo, PENDING, RUNNING, COMPLETED.
  5. Depois que uma simulação for concluída, confira os relatórios e artefatos gerados. Os arquivos de entrada, relatórios de saída, registros, Logcat e relatórios de bugs são armazenados no Cloud Storage.
  6. Opcional: cancelar uma simulação programada ou em execução.

Uso da API

Para automação e integração com outros sistemas, use a API REST.

O marcador de posição CLOUD_FUNCTION_URL usado na seção "Autenticação" e nas definições de endpoint se refere ao URL de base da função do Cloud que está sendo invocada. É possível encontrar URLs de função no console do Google Cloud na página Cloud Functions. O URL de cada função é mostrado na guia Gatilho da página Detalhes da função. Como alternativa, é possível encontrar esses URLs nas saídas do Terraform que são impressas depois de executar um comando apply.

Autenticação

Todas as solicitações de API precisam ser autenticadas com um token de identidade que comprove a identidade do autor da chamada. A identidade (usuário ou conta de serviço) precisa ter permissões de invocador do Cloud Functions na função de destino.

  1. Invocação do usuário (local e CLI): ao invocar a API de uma máquina local ou de um ambiente que não seja do Google Cloud, use um token de identidade emitido pelo Google para uma conta de usuário.

    TOKEN=$(gcloud auth print-identity-token)

  2. Invocação de conta de serviço (no Google Cloud): ao invocar a API de um recurso do Google Cloud (por exemplo, uma VM do Compute Engine, outra função do Cloud ou um cluster do Kubernetes), use a identidade da conta de serviço anexada ao recurso. O token precisa ser buscado no servidor de metadados do recurso.

    TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")

Inclua o token recuperado no cabeçalho Authorization das suas solicitações como um token Bearer.

Endpoints

Os endpoints voltados ao usuário da pilha de simulação de telemetria do Cloud permitem criar e excluir simulações ou ler informações de simulação do banco de dados.

Criar uma simulação

Esse endpoint cria uma nova solicitação de simulação e a programa para execução.

  • Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-requests

  • Corpo da solicitação:

    {
  "build_id": "latest",
  "file_path": "inputs/my-test-case/",
  "instance_type": "n1-standard-8",
  "owner": "user@example.com",
  "max_simulation_time": 300,
  "max_report_count": 5
}

    • build_id (string): a tag da imagem Docker do agente a ser usada, por exemplo,latest.

    • file_path (string): o caminho no bucket do GCS para a pasta que contém metrics_config.zip e publisher_config.zip.

    • instance_type (string): o tipo de máquina do Compute Engine. Esse tipo precisa ser compatível com a virtualização aninhada, como as séries n1, n2 ou t2d. Para mais informações, consulte a visão geral da virtualização aninhada.

    • owner (string): o e-mail do usuário que iniciou a simulação.

    • max_simulation_time (número inteiro): o tempo máximo em segundos que a simulação é executada.

    • max_report_count (número inteiro): o número de relatórios de telemetria após os quais a simulação é concluída.

  • Resposta de sucesso (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Excluir uma simulação

Esse endpoint cancela uma simulação pendente ou em execução e exclui os recursos associados.

  • Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Cabeçalhos:
    • Content-Type: application/json

  • Corpo da solicitação:

    { "id": "sim-a1b2c3d4e5f6" }

  • Resposta de sucesso (200 OK): uma mensagem de texto simples (Request accepted and is being processed).

Ler dados de simulação

Para ler dados de simulação, interaja com a função simulation-reader. Esses endpoints usam o método GET para recuperar o histórico, o status e a configuração do sistema.

Listar simulações

Recupera uma lista paginada de simulações com suporte para filtragem e classificação.

  • Endpoint: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • Parâmetros de consulta (todos opcionais):

    • status (string): filtre por status da simulação (running, Simulation request received, cancelled, completed ou failed).
    • owner (string): filtra pelo e-mail do proprietário.
    • sort_by (string): campo para classificação (received_at, status_updated_at, started_at). O padrão é received_at.
    • sort_order (string): direção de classificação, asc ou desc. O padrão é desc.
    • page_size (número inteiro): número de resultados por página. O padrão é 20.
    • page_token (string): token para buscar a próxima página de resultados.

  • Exemplo de solicitação:

    curl -H "Authorization: Bearer $TOKEN"
"https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"

  • Resposta de sucesso (200 OK):

    • Retorna um objeto JSON que contém uma matriz de simulações e um next_page_token opcional.
    {
  "simulations": [
    {
      "id": "1234-abcd",
      "owner": "some@email.com",
      "status": "completed",
      "status_updated_at": "2025-12-05T14:50:00.952Z",
      "received_at": "2025-12-05T14:46:43.106Z",
      "started_at": "2025-12-05T14:47:05.848Z",
      "ended_at": "0001-01-01T00:00:00Z",
      "instance_id": "sim-1234-abcd",
      "ip": "10.156.15.230",
      "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
      "instance_type": "n1-standard-8",
      "file_path": "gs://your-project-simulation_files/path/",
      "max_simulation_time": 60,
      "max_report_count": 1
    },
    {
      "id": "5678-efgh",
      "owner": "some@email.com",
      "status": "completed",
      "status_updated_at": "2025-11-07T14:49:54.25Z",
      "received_at": "2025-11-07T14:46:54.959Z",
      "started_at": "2025-11-07T14:47:13.714Z",
      "ended_at": "0001-01-01T00:00:00Z",
      "instance_id": "sim-5678-efgh",
      "ip": "10.156.15.221",
      "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
      "instance_type": "n1-standard-8",
      "file_path": "gs://your-project-simulation_files/path/",
      "max_simulation_time": 60,
      "max_report_count": 1
    }
  ],
  "next_page_token": "M7bydGsAptLncj8SOCb1"
}
Receber uma simulação específica

Recupera os detalhes completos de uma simulação específica pelo ID.

  • Endpoint:

    GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]

  • Resposta de sucesso (200 OK): retorna um objeto JSON com os detalhes da simulação solicitada.

    {
  "id": "1234-abcd",
  "owner": "some@email.com",
  "status": "completed",
  "status_updated_at": "2025-12-05T14:50:00.952Z",
  "received_at": "2025-12-05T14:46:43.106Z",
  "started_at": "2025-12-05T14:47:05.848Z",
  "ended_at": "0001-01-01T00:00:00Z",
  "instance_id": "sim-1234-abcd",
  "ip": "10.156.15.230",
  "build_id": "europe-west3-docker.pkg.dev/your-project/simulation/simulation-agent:latest",
  "instance_type": "n1-standard-8",
  "file_path": "gs://your-project-simulation_files/path/",
  "max_simulation_time": 60,
  "max_report_count": 1
}
Acessar métricas e configuração do sistema

Esses endpoints fornecem insights sobre a carga e a configuração atuais da infraestrutura de simulação.

  • Receber contagem de execuções: retorna a contagem de simulações em execução.

    • Endpoint:

      GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count

    • Resposta de sucesso (200 OK):

      {
  "count": 0
}

  • Receber o número máximo de VMs simultâneas: retorna o número máximo configurado de VMs em execução simultânea.

    • Endpoint:

      GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms

    • Resposta de sucesso (200 OK):

      {
  "max_running_vms": 5
}