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 de entrada com os arquivos de entrada copiados e uma pasta de saída. A pasta de saída contém o relatório de bugs, o arquivo logcat e os arquivos do simulador gerados.

Usar a demonstração da 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 adaptada às suas necessidades.

O app de demonstração é implantado no App Engine e exige que os usuários façam login com uma Conta do Google. Isso é protegido usando um ID do cliente OAuth 2.0 configurado no seu projeto do Google Cloud. A conta conectada precisa ter permissões do IAM para invocar as funções do Cloud implantadas. Consulte Gerenciar o acesso ao Cloud Functions para 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. Fazer login: você faz login com sua Conta do Google, autenticada usando o processo OAuth 2.0.
  2. Visualizar simulações: a página principal lista todas as simulações anteriores e atuais consultando o banco de dados do Firestore, que contém todas as informações de execução.
  3. Criar uma simulação: navegue até 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 da build e o tipo de instância. Para mais informações, consulte Criar uma simulação.
  4. Monitorar o status: a lista de simulações é atualizada para mostrar o status da nova simulação (PENDING, RUNNING, COMPLETED, etc.).
  5. Visualizar resultados: depois que uma simulação é concluída, é possível visualizar 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. Excluir uma simulação: é possível cancelar uma simulação programada ou em execução.

Uso da API

Para automação e integração com outros sistemas, é possível usar a API REST.

O marcador CLOUD_FUNCTION_URL usado na seção "Autenticação" e nas definições de endpoint se refere ao URL base da função do Cloud que está sendo invocada. É possível encontrar URLs de funções no console do Google Cloud na página Cloud Functions ; o URL de cada função é mostrado na guia Acionador da página Detalhes da função. Como alternativa, é possível encontrar esses URLs nas saídas do Terraform impressas após a execução de 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 (conta de usuário ou 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, é necessário usar um token de identidade emitido pelo Google obtido para uma conta de usuário.

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

  • 2. Invocação da 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 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-request

  • 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"). Importante: ela precisa corresponder a uma tag definida no mapa de imagens permitido da infraestrutura (por exemplo, "latest", "stable"). O sistema rejeita tags desconhecidas se um mapa SHA256 for definido no Terraform.
    • 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 oferecer suporte à 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 está iniciando a simulação.
    • max_simulation_time (inteiro): o tempo máximo em segundos que a simulação é executada.
    • max_report_count (inteiro): o número de relatórios de telemetria após os quais a simulação termina.

  • 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 a ela.

  • 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): um objeto JSON vazio {}.

Ler dados de simulação

Para ler dados de simulação, é possível interagir 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.

1. 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): filtra por status da simulação (running, Simulation request received, cancelled ou completed).
    • owner (string): filtra pelo e-mail do proprietário.
    • sort_by (string): campo para classificar por (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 (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"
}

2. 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 que contém 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
}

3. Receber 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ção: 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
}