ユーザーガイド

シミュレーションは、提供されているウェブ デモを使用するか、REST API を直接呼び出すことで実行できます。

入力と出力

入力ファイルと出力ファイルは、Terraform 設定の Cloud Storage バケットを使用します。

入力ディレクトリには、metrics_config.zip ファイルと publisher_config.zip ファイルが含まれている必要があります。必要に応じてパスを定義できます。

出力用のバケットには simulations ディレクトリが含まれており、各シミュレーションは ID ごとに保存されます。各シミュレーション ディレクトリには、コピーされた入力ファイルを含む入力フォルダと出力フォルダが含まれます。出力フォルダには、バグレポート、logcat ファイル、生成されたシミュレータ ファイルが含まれます。

ウェブ デモを使用する

このプラットフォームには、シミュレーションの表示、作成、管理を行うためのデモ用の Flutter ベースのウェブ アプリケーションが含まれています。ニーズに合わせて独自のユーザー インターフェースを構築することをおすすめします。

デモアプリは App Engine にデプロイされ、ユーザーは Google アカウントでログインする必要があります。これは、Google Cloud プロジェクトで構成された OAuth 2.0 クライアント ID を使用して保護されます。ログインしているアカウントには、デプロイされた Cloud Functions を呼び出すための IAM 権限が必要です。Cloud Functions 起動元ロール（roles/cloudfunctions.invoker）など、ユーザー アカウントに必要な権限を付与する手順については、Cloud Functions へのアクセスを管理するをご覧ください。

ユーザー ワークフロー

  1. ログイン: OAuth 2.0 プロセスを使用して認証された Google アカウントでログインします。
  2. シミュレーションを表示する: メインページには、すべての実行情報が保持されている Firestore データベースをクエリして、過去と現在のすべてのシミュレーションが一覧表示されます。
  3. シミュレーションを作成する: 右下の + 操作ボタンをクリックして、新しいシミュレーションをスケジュールするフォームに移動します。入力パス、ビルド ID、インスタンス タイプなど、いくつかのパラメータを指定します。詳細については、シミュレーションを作成するをご覧ください。
  4. ステータスをモニタリングする: シミュレーション リストが更新され、新しいシミュレーションのステータス（PENDING、RUNNING、COMPLETED など）が表示されます。
  5. 結果を表示: シミュレーションが完了すると、生成されたレポートとアーティファクトを表示できます。入力ファイル、出力レポート、ログ、Logcat、バグレポートは Cloud Storage に保存されます。
  6. シミュレーションを削除する: スケジュールされたシミュレーションまたは実行中のシミュレーションをキャンセルできます。

API 使用量

自動化や他のシステムとの統合には、REST API を使用できます。

認証セクションとエンドポイント定義で使用されているプレースホルダ CLOUD_FUNCTION_URL は、呼び出される Cloud Functions のベース URL を指します。関数の URL は、Google Cloud コンソールの [Cloud Functions] ページで確認できます。各関数の URL は、[関数の詳細] ページの [トリガー] タブに表示されます。または、apply コマンドの実行後に表示される Terraform 出力でこれらの URL を確認することもできます。

認証

すべての API リクエストは、呼び出し元の ID を証明するID トークンで認証する必要があります。ID（ユーザーまたはサービス アカウント）には、ターゲット関数に対する Cloud Functions 起動元権限が必要です。

  • 1. ユーザー呼び出し（ローカルと CLI）ローカルマシンまたは Google Cloud 以外の環境から API を呼び出す場合は、ユーザー アカウント用に取得した Google 発行の ID トークンを使用する必要があります。

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

  • 2. サービス アカウントの呼び出し（Google Cloud 内） Google Cloud リソース（Compute Engine VM、別の Cloud Functions、Kubernetes クラスタなど）から API を呼び出す場合は、リソースに接続されたサービス アカウントの ID を使用する必要があります。トークンは、リソースのメタデータ サーバーから取得する必要があります。

    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（文字列）: metrics_config.zip と publisher_config.zip を含むフォルダの GCS バケット内のパス。
    • 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）:

    • シミュレーションの配列とオプションの next_page_token を含む JSON オブジェクトを返します。
    {
  "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
}