Panduan pengguna

Anda dapat menjalankan simulasi menggunakan demo web yang disediakan atau dengan memanggil REST API secara langsung.

Input dan output

File input dan output menggunakan bucket Cloud Storage dari penyiapan Terraform.

Direktori input harus berisi file metrics_config.zip dan publisher_config.zip. Anda dapat menentukan jalur ke file tersebut sesuai kebutuhan.

Bucket untuk output berisi direktori simulations, yang menyimpan setiap simulasi berdasarkan ID-nya. Setiap direktori simulasi berisi folder inputs dengan file input yang disalin dan folder outputs. Folder outputs berisi laporan bug, file logcat, dan file simulator yang dihasilkan.

Menggunakan demo web

Platform ini menyertakan aplikasi web berbasis Flutter untuk tujuan demonstrasi yang memungkinkan Anda melihat, membuat, dan mengelola simulasi. Anda dianjurkan untuk membangun antarmuka pengguna Anda sendiri yang disesuaikan dengan kebutuhan Anda.

Aplikasi demo di-deploy ke App Engine dan mengharuskan Anda login dengan Akun Google. Hal ini dilindungi menggunakan Client ID OAuth 2.0 yang dikonfigurasi di project Google Cloud Anda. Akun yang login harus memiliki izin IAM untuk memanggil Cloud Functions yang di-deploy. Lihat Memberikan otorisasi akses dengan IAM untuk mengetahui petunjuk tentang cara memberikan izin yang diperlukan ke akun pengguna, seperti peran Cloud Functions Invoker (roles/cloudfunctions.invoker).

Alur kerja pengguna

  1. Login dengan Akun Google Anda, yang diautentikasi menggunakan proses OAuth 2.0.
  2. Lihat simulasi di halaman utama, yang mencantumkan semua simulasi dengan mengkueri database Firestore, yang menyimpan semua informasi eksekusi.
  3. Buka formulir untuk menjadwalkan simulasi baru dengan mengklik tombol tindakan + di pojok kanan bawah. Anda memberikan beberapa parameter, termasuk jalur input, ID build, dan jenis instance. Untuk mengetahui informasi selengkapnya, lihat Membuat simulasi.
  4. Periksa status monitor pada pembaruan daftar simulasi, yang menampilkan status simulasi baru, misalnya, PENDING, RUNNING, COMPLETED.
  5. Setelah simulasi selesai, lihat laporan dan artefak yang dihasilkan. File input, laporan output, log, Logcat, dan Laporan bug disimpan di Cloud Storage.
  6. Opsional: Batalkan simulasi yang dijadwalkan atau sedang berjalan.

Penggunaan API

Untuk otomatisasi dan integrasi dengan sistem lain, Anda dapat menggunakan REST API.

Placeholder CLOUD_FUNCTION_URL yang digunakan di bagian Authentication dan dalam definisi endpoint mengacu pada URL dasar Cloud Function yang dipanggil. Anda dapat menemukan URL fungsi di Konsol Google Cloud pada halaman Cloud Functions; URL untuk setiap fungsi ditampilkan di tab Trigger pada halaman Function details. Atau, Anda dapat menemukan URL ini di output Terraform yang dicetak setelah Anda menjalankan perintah apply.

Autentikasi

Semua permintaan API harus diautentikasi dengan token identitas yang membuktikan identitas pemanggil. Identitas (pengguna atau akun layanan) harus memiliki izin Cloud Functions Invoker pada fungsi target.

  1. Pemanggilan pengguna (lokal dan CLI): Saat memanggil API dari mesin lokal atau lingkungan non-Google Cloud, Anda harus menggunakan token identitas yang dikeluarkan Google yang diperoleh untuk akun pengguna.

    TOKEN=$(gcloud auth print-identity-token)
    
  2. Pemanggilan akun layanan (dalam Google Cloud): Saat memanggil API dari resource Google Cloud (misalnya, VM Compute Engine, Cloud Function lain, atau cluster Kubernetes), gunakan identitas Akun Layanan yang terpasang pada resource. Token harus diambil dari server metadata resource.

    TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")
    

Sertakan token yang diambil di header Authorization permintaan Anda sebagai token Bearer.

Endpoint

Endpoint yang ditampilkan kepada pengguna dari stack Simulasi Telemetri Cloud memungkinkan Anda membuat dan menghapus simulasi atau membaca informasi simulasi dari database.

Membuat simulasi

Endpoint ini membuat permintaan simulasi baru dan menjadwalkannya untuk dieksekusi.

  • Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-requests
  • Isi permintaan:

    {
      "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 (string): Tag image Docker agen yang akan digunakan, misalnya,latest.

    • file_path (string): Jalur dalam bucket GCS ke folder yang berisi metrics_config.zip dan publisher_config.zip.

    • instance_type (string): Jenis mesin Compute Engine. Jenis ini harus mendukung virtualisasi bertingkat, seperti seri n1, n2, atau t2d. Untuk mengetahui informasi selengkapnya, lihat ringkasan virtualisasi bertingkat.

    • owner (string): Email pengguna yang memulai simulasi.

    • max_simulation_time (bilangan bulat): Waktu maksimum dalam detik saat simulasi berjalan.

    • max_report_count (bilangan bulat): Jumlah laporan telemetri setelah simulasi selesai.

  • Respons berhasil (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }
    

Menghapus simulasi

Endpoint ini membatalkan simulasi yang tertunda atau berjalan dan menghapus resource terkait.

  • Endpoint: POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • Header:
    • Content-Type: application/json
  • Isi permintaan:

    { "id": "sim-a1b2c3d4e5f6" }
    
  • Respons berhasil (200 OK): Pesan teks biasa (Request accepted and is being processed).

Membaca data simulasi

Untuk membaca data simulasi, Anda dapat berinteraksi dengan fungsi simulation-reader. Endpoint ini menggunakan metode GET untuk mengambil histori, status, dan konfigurasi sistem.

Mencantumkan simulasi

Mengambil daftar simulasi yang diberi nomor halaman dengan dukungan untuk pemfilteran dan pengurutan.

  • Endpoint: GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations
  • Parameter kueri (semua opsional):

    • status (string): Filter menurut status simulasi (running, Simulation request received, cancelled, completed, atau failed).
    • owner (string): Filter menurut email pemilik.
    • sort_by (string): Kolom yang akan diurutkan (received_at, status_updated_at, started_at). Default-nya adalah received_at.
    • sort_order (string): Arah pengurutan, asc atau desc. Nilai defaultnya adalah desc.
    • page_size (bilangan bulat): Jumlah hasil per halaman. Default-nya adalah 20.
    • page_token (string): Token untuk mengambil halaman hasil berikutnya.
  • Contoh permintaan:

    curl -H "Authorization: Bearer $TOKEN"
    "https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"
    
  • Respons berhasil (200 OK):

    • Menampilkan objek JSON yang berisi array simulasi dan next_page_token opsional.
    {
      "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"
    }
    
Mendapatkan simulasi tertentu

Mengambil detail lengkap simulasi tertentu berdasarkan ID-nya.

  • Endpoint:

    GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]
    
  • Respons berhasil (200 OK): Menampilkan objek JSON yang berisi detail simulasi yang diminta.

    {
      "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
    }
    
Mendapatkan metrik dan konfigurasi sistem

Endpoint ini memberikan insight tentang beban dan konfigurasi infrastruktur simulasi saat ini.

  • Mendapatkan jumlah yang berjalan: Menampilkan jumlah simulasi yang berjalan.

    • Endpoint:

      GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count
      
    • Respons berhasil (200 OK):

      {
        "count": 0
      }
      
  • Mendapatkan VM serentak maksimum: Menampilkan jumlah maksimum VM yang berjalan serentak yang dikonfigurasi.

    • Endpoint:

      GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms
      
    • Respons berhasil (200 OK):

      {
        "max_running_vms": 5
      }