自 2026 年起，为了与我们的主干稳定开发模型保持一致，并确保生态系统的平台稳定性，我们将在第 2 季度和第 4 季度向 AOSP 发布源代码。如需构建 AOSP 并为其贡献代码，请使用 android-latest-release。android-latest-release 清单分支将始终引用推送到 AOSP 的最新版本。如需了解详情，请参阅 AOSP 变更。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

用户指南

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

输入和输出

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

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

输出存储桶包含一个 simulations 目录，该目录按 ID 存储每个模拟。每个模拟目录都包含一个 inputs 文件夹（其中包含复制的输入文件）和一个 outputs 文件夹。outputs 文件夹包含 bugreport、logcat 文件和生成的模拟器文件。

使用 Web 演示

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

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

用户工作流程

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

API 使用

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

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

身份验证

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

用户调用（本地和 CLI）：从本地机器或非 Google Cloud 环境调用 API 时，您必须使用为用户账号获取的 Google 颁发的身份令牌。
```
TOKEN=$(gcloud auth print-identity-token)
```
服务账号调用（在 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")
```

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

端点

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

创建模拟

此端点会创建一个新的模拟请求，并安排其执行。

端点：POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-requests
请求正文：
```
{
  "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。
  
  重要提示：此标记必须与基础架构的允许图像地图中定义的标记匹配，例如 latest、stable。如果在 Terraform 中定义了 SHA256 映射，系统会拒绝未知标记。
- 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
Headers:
- Content-Type: application/json
请求正文：
```
{ "id": "sim-a1b2c3d4e5f6" }
```
成功响应 (200 OK)：纯文本消息 (Request accepted and is being processed)。

读取模拟数据

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

列出模拟

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

端点：GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations
查询参数（均为可选）：
- status（字符串）：按模拟状态（running、Simulation request received、cancelled、completed 或 failed）过滤。
- 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
}
```