使用手冊

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

輸入和輸出

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

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

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

使用 Web Demo

這個平台包含以 Flutter 為基礎的網頁應用程式，可供示範用途，讓您查看、建立及管理模擬。我們建議您根據自身需求，建構專屬的使用者介面。

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

使用者工作流程

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

API 使用情形

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

驗證部分和端點定義中使用的預留位置 CLOUD_FUNCTION_URL，是指要叫用的 Cloud Functions 基本網址。您可以在 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 Function 或 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」)。重要事項：這必須與基礎架構允許的映像檔對應中定義的標記相符 (例如「latest」、「stable」)。如果系統在 Terraform 中定義 SHA256 對應，就會拒絕不明標記。
    • 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
  • 標題：
    • Content-Type: application/json

  • 要求主體：

    { "id": "sim-a1b2c3d4e5f6" }

  • 成功回應 (200 OK)：空白的 JSON 物件 {}。

讀取模擬資料

如要讀取模擬資料，可以與 simulation-reader 函式互動。這些端點會使用 GET 方法擷取記錄、狀態和系統設定。

1. 列出模擬

擷取模擬的頁面清單，支援篩選和排序。

  • 端點：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"
}

2. 取得特定模擬

透過 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
}

3. 取得系統指標和設定

這些端點可深入瞭解模擬基礎架構目前的負載和設定。

  • 取得執行次數：傳回正在執行的模擬次數。

    • 端點：

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

    • 成功回應 (200 OK)：

      {
  "count": 0
}

  • 取得並行 VM 數量上限：傳回設定的並行執行 VM 數量上限。

    • 端點：

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

    • 成功回應 (200 OK)：

      {
  "max_running_vms": 5
}