ユーザー ガイド

提供されているウェブ デモを使用するか、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）など、ユーザー アカウントに必要な権限を付与する手順については、IAM によるアクセス権の承認をご覧ください。

ユーザー ワークフロー

  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 など）。

    • 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 メソッドを使用して履歴、ステータス、システム構成を取得します。

シミュレーションを一覧表示する

フィルタリングと並べ替えをサポートするシミュレーションのページ分割されたリストを取得します。

  • エンドポイント: 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（整数）: 1 ページあたりの結果数。デフォルトは 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"
}
特定のシミュレーションを取得する

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
}

  • 同時実行 VM の最大数を取得する: 構成された同時実行 VM の最大数を返します。

    • エンドポイント:

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

    • 成功レスポンス（200 OK）:

      {
  "max_running_vms": 5
}