用户指南

您可以使用提供的 Web 演示或直接调用 REST API 来运行模拟。

输入和输出

输入和输出文件使用 Terraform 设置中的 Cloud Storage 存储分区。

输入目录必须包含 metrics_config.zip 和 publisher_config.zip 文件。您可以根据需要定义其路径。

输出结果的存储分区包含一个 simulations 目录，其中按 ID 存储每次模拟。每个模拟目录都包含一个包含已复制输入文件的输入文件夹和一个输出文件夹。输出文件夹包含 bug 报告、logcat 文件和生成的模拟器文件。

使用 Web 演示版

该平台包含一个基于 Flutter 的 Web 应用，用于演示目的，可让您查看、创建和管理模拟。建议您根据自己的需求构建自己的界面。

演示版应用已部署到 App Engine，需要您使用 Google 账号登录。此 API 受 Google Cloud 项目中配置的 OAuth 2.0 客户端 ID 保护。登录的账号必须具有调用已部署 Cloud Functions 函数的 IAM 权限。如需了解如何向用户账号授予必要的权限（例如 Cloud Functions 函数调用者角色 [roles/cloudfunctions.invoker]），请参阅使用 IAM 授权访问权限。

用户工作流程

  1. 使用您的 Google 账号登录，并通过 OAuth 2.0 流程进行身份验证。
  2. 在主页面上查看模拟，该页面会通过查询 Firestore 数据库（其中包含所有执行信息）列出所有模拟。
  3. 点击右下角的 + 操作按钮，前往相应表单以安排新的模拟。您需要提供多个参数，包括输入路径、build ID 和实例类型。如需了解详情，请参阅创建模拟。
  4. 查看模拟列表更新中的监控器状态，其中会显示新模拟的状态，例如 PENDING、RUNNING、COMPLETED。
  5. 模拟完成后，查看生成的报告和制品。输入文件、输出报告、日志、Logcat 和 bug 报告存储在 Cloud Storage 中。
  6. 可选：取消已安排或正在运行的模拟。

API 使用

如需实现自动化并与其他系统集成，您可以使用 REST API。

身份验证部分和端点定义中使用的占位符 CLOUD_FUNCTION_URL 是指所调用的 Cloud Functions 函数的基本网址。您可以在 Google Cloud 控制台的 Cloud Functions 页面上找到函数网址；每个函数的网址都显示在其函数详情页面的触发器标签页上。或者，您也可以在运行 apply 命令后显示的 Terraform 输出中找到这些网址。

身份验证

所有 API 请求都必须通过身份令牌进行身份验证，以证明调用者的身份。身份（用户或服务账号）必须拥有目标函数的 Cloud Functions Invoker 权限。

  1. 用户调用（本地和 CLI）：从本地机器或非 Google Cloud 环境调用 API 时，您必须使用为用户账号获取的 Google 颁发的身份令牌。

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

  2. 服务账号调用（在 Google Cloud 中）：从 Google Cloud 资源（例如 Compute Engine 虚拟机、其他 Cloud Functions 或 Kubernetes 集群）调用 API 时，请使用资源所关联的服务账号的身份。应从资源的元数据服务器提取令牌。

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

在请求的 Authorization 标头中添加检索到的令牌，作为 Bearer 令牌。

端点

Cloud Telemetry Simulation 堆栈面向用户的端点可让您创建和删除模拟，或从数据库中读取模拟信息。

创建模拟

此端点会创建新的模拟请求并安排其执行时间。

  • 端点： POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request

  • 请求正文：

    {
  "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（字符串）：要使用的代理 Docker 映像的标记，例如 latest。

    • file_path（字符串）：GCS 存储分区中包含 metrics_config.zip 和 publisher_config.zip 的文件夹的路径。

    • instance_type（字符串）：Compute Engine 机器类型。此类必须支持嵌套虚拟化，例如 n1、n2 或 t2d 系列。如需了解详情，请参阅嵌套虚拟化概览。

    • owner（字符串）：发起模拟的用户的电子邮件地址。

    • max_simulation_time（整数）：模拟运行的最长时间（以秒为单位）。

    • max_report_count（整数）：在生成多少个遥测报告后结束模拟。

  • 成功响应 (200 OK)：

    { "id": "sim-a1b2c3d4e5f6" }

删除模拟

此端点用于取消待处理或正在运行的模拟，并删除其关联的资源。

  • 端点： POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • 标头：
    • Content-Type: application/json

  • 请求正文：

    { "id": "sim-a1b2c3d4e5f6" }

  • 成功响应 (200 OK)：一个空的 JSON 对象 {}。

读取模拟数据

如需读取模拟数据，您可以与 simulation-reader 函数互动。这些端点使用 GET 方法来检索历史记录、状态和系统配置。

列出模拟

检索分页的模拟列表，支持过滤和排序。

  • 端点： GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • 查询参数（均为可选）：

    • status（字符串）：按模拟状态（running、Simulation request received、cancelled 或 completed）过滤。
    • owner（字符串）：按所有者的电子邮件地址过滤。
    • sort_by（字符串）：要排序的字段（received_at、status_updated_at、started_at）。默认为 received_at。
    • sort_order（字符串）：排序方向，asc 或 desc。默认值为 desc。
    • page_size（整数）：每页的结果数。默认值为 20。
    • page_token（字符串）：用于获取下一页结果的令牌。

  • 示例请求：

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

  • 成功响应 (200 OK)：

    • 返回一个 JSON 对象，其中包含模拟数组和一个可选的 next_page_token。
    {
  "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"
}
获取特定模拟

根据 ID 检索特定模拟的完整详细信息。

  • 端点：

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

  • 成功响应 (200 OK)：返回一个 JSON 对象，其中包含所请求模拟的详细信息。

    {
  "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
}
获取系统指标和配置

这些端点可深入了解模拟基础架构的当前负载和配置。

  • 获取正在运行的模拟次数：返回正在运行的模拟次数。

    • 端点：

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

    • 成功响应 (200 OK)：

      {
  "count": 0
}

  • 获取最大并发虚拟机数：返回配置的最大并发运行虚拟机数。

    • 端点：

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

    • 成功响应 (200 OK)：

      {
  "max_running_vms": 5
}