使用手冊

您可以使用提供的網頁試用版，或直接呼叫 REST API 來執行模擬。

輸入和輸出

輸入和輸出檔案會使用 Terraform 設定中的 Cloud Storage bucket。

輸入目錄必須包含 metrics_config.zip 和 publisher_config.zip 檔案。您可以視需要定義路徑。

輸出內容的 bucket 包含 simulations 目錄，會依 ID 儲存各項模擬。每個模擬目錄都包含一個 inputs 資料夾 (內含複製的輸入檔案) 和一個 outputs 資料夾。outputs 資料夾包含錯誤報告、logcat 檔案和產生的模擬器檔案。

使用網頁版試用

這個平台包含一個以 Flutter 為基礎的網頁應用程式，用於示範如何查看、建立及管理模擬。建議您根據需求建構自己的使用者介面。

示範應用程式會部署至 App Engine，您必須使用 Google 帳戶登入。這項設定會使用 Google Cloud 雲端專案中設定的 OAuth 2.0 用戶端 ID 保護。登入的帳戶必須具備 IAM 權限，才能叫用已部署的 Cloud Functions。如要瞭解如何將必要權限 (例如 Cloud Functions 叫用者角色 (roles/cloudfunctions.invoker)) 授予使用者帳戶，請參閱「使用 IAM 授權存取權」。

使用者操作流程

  1. 使用 Google 帳戶登入，並透過 OAuth 2.0 程序進行驗證。
  2. 在主頁面查看模擬作業，該頁面會查詢 Firestore 資料庫，列出所有模擬作業，其中包含所有執行資訊。
  3. 按一下右下角的「+」動作按鈕，前往表單安排新的模擬。您需要提供多個參數，包括輸入路徑、建構 ID 和執行個體類型。詳情請參閱「建立模擬作業」。
  4. 查看模擬清單更新中的監控狀態，其中會顯示新模擬的狀態，例如 PENDING、RUNNING、COMPLETED。
  5. 模擬完成後，請查看生成的報告和構件。輸入檔案、輸出報表、記錄、Logcat 和 Bugreport 都會儲存在 Cloud Storage 中。
  6. 選用：取消已排定或執行中的模擬作業。

API 使用

如要自動化及整合其他系統，可以使用 REST API。

「Authentication」部分和端點定義中使用的預留位置 CLOUD_FUNCTION_URL，是指叫用的 Cloud 函式基準網址。您可以在 Google Cloud 控制台的「Cloud Functions」頁面中找到函式網址；每個函式的網址都會顯示在「Function details」(函式詳細資料) 頁面的「Trigger」(觸發條件) 分頁中。或者，您也可以在執行 apply 指令後輸出的 Terraform 輸出內容中找到這些網址。

驗證

所有 API 要求都必須使用身分權杖進行驗證，證明呼叫端的身分。身分 (使用者或服務帳戶) 必須具備目標函式的 Cloud Functions 叫用者權限。

  1. 使用者叫用 (本機和 CLI)：從本機電腦或非 Google Cloud 環境叫用 API 時，必須使用為使用者帳戶取得的 Google 核發身分權杖。

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

  2. 服務帳戶叫用 (在 Google Cloud 內)：從 Google Cloud 資源 (例如 Compute Engine VM、其他 Cloud 函式或 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-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。

    • file_path (字串)：GCS bucket 中包含 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 max concurrent VMs：傳回設定的並行執行 VM 數量上限。

    • 端點：

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

    • 成功回應 (200 OK)：

      {
  "max_running_vms": 5
}