Guide de l'utilisateur

Vous pouvez exécuter des simulations à l'aide de la démo Web fournie ou en appelant directement l'API REST.

Entrées et sorties

Les fichiers d'entrée et de sortie utilisent le bucket Cloud Storage de la configuration Terraform.

Le répertoire d'entrée doit contenir les fichiers metrics_config.zip et publisher_config.zip. Vous pouvez définir le chemin d'accès selon vos besoins.

Le bucket de sortie contient un répertoire simulations, qui stocke chaque simulation par son ID. Chaque répertoire de simulation contient un dossier d'entrée avec les fichiers d'entrée copiés et un dossier de sortie. Le dossier de sortie contient le rapport de bug, le fichier logcat et les fichiers de simulateur générés.

Utiliser la démo Web

La plate-forme inclut une application Web basée sur Flutter à des fins de démonstration, qui vous permet d'afficher, de créer et de gérer des simulations. Nous vous encourageons à créer votre propre interface utilisateur adaptée à vos besoins.

L'application de démonstration est déployée sur App Engine et nécessite que vous vous connectiez avec un compte Google. Elle est protégée à l'aide d'un ID client OAuth 2.0 configuré dans votre projet Google Cloud. Le compte connecté doit disposer des autorisations IAM pour appeler les fonctions Cloud déployées. Pour savoir comment accorder les autorisations nécessaires aux comptes utilisateur, telles que le rôle Demandeur Cloud Functions (roles/cloudfunctions.invoker), consultez Autoriser l'accès avec IAM.

Processus utilisateur

  1. Connectez-vous avec votre compte Google, authentifié à l'aide du processus OAuth 2.0.
  2. Affichez les simulations sur la page principale, qui répertorie toutes les simulations en interrogeant la base de données Firestore, qui contient toutes les informations d'exécution.
  3. Accédez à un formulaire pour planifier une nouvelle simulation en cliquant sur le bouton d'action + en bas à droite. Vous fournissez plusieurs paramètres, y compris le chemin d'accès d'entrée, l'ID de build et le type d'instance. Pour en savoir plus, consultez Créer une simulation.
  4. Vérifiez l'état du moniteur sur les mises à jour de la liste des simulations, qui indiquent l'état de la nouvelle simulation, par exemple PENDING, RUNNING ou COMPLETED.
  5. Une fois la simulation terminée, affichez les rapports et les artefacts générés. Les fichiers d'entrée, les rapports de sortie, les journaux, Logcat et les rapports de bug sont stockés dans Cloud Storage.
  6. Facultatif : annulez une simulation planifiée ou en cours d'exécution.

Utilisation de l'API

Pour l'automatisation et l'intégration à d'autres systèmes, vous pouvez utiliser l'API REST.

L'espace réservé CLOUD_FUNCTION_URL utilisé dans la section Authentification et dans les définitions de point de terminaison fait référence à l' URL de base de la fonction Cloud appelée. Vous trouverez les URL des fonctions dans la console Google Cloud sur la page Cloud Functions. L'URL de chaque fonction s'affiche dans l'onglet Déclencheur de sa page Informations sur la fonction. Vous pouvez également trouver ces URL dans les sorties Terraform qui s'affichent après l'exécution d'une commande apply.

Authentification

Toutes les requêtes API doivent être authentifiées avec un jeton d'identité qui prouve l'identité de l'appelant. L'identité (utilisateur ou compte de service) doit disposer des autorisations Demandeur Cloud Functions sur la fonction cible.

  1. Appel utilisateur (local et CLI) : lorsque vous appelez l'API à partir d'une machine locale ou d'un environnement non Google Cloud, vous devez utiliser un jeton d'identité émis par Google et obtenu pour un compte utilisateur.

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

  2. Appel de compte de service (dans Google Cloud) : lorsque vous appelez l'API à partir d'une ressource Google Cloud (par exemple, une VM Compute Engine, une autre fonction Cloud ou un cluster Kubernetes), utilisez l'identité du compte de service associé à la ressource. Le jeton doit être récupéré à partir du serveur de métadonnées de la ressource.

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

Incluez le jeton récupéré dans l'en-tête Authorization de vos requêtes en tant que jeton Bearer.

Points de terminaison

Les points de terminaison utilisateur de la pile Cloud Telemetry Simulation vous permettent de créer et de supprimer des simulations, ou de lire des informations de simulation à partir de la base de données.

Créer une simulation

Ce point de terminaison crée une requête de simulation et la planifie pour l'exécution.

  • Point de terminaison : POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request

  • Corps de la requête :

    {
  "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 (chaîne) : tag de l'image Docker de l'agent à utiliser, par exemple latest.

    • file_path (chaîne) : chemin d'accès dans le bucket GCS au dossier contenant metrics_config.zip et publisher_config.zip.

    • instance_type (chaîne) : type de machine Compute Engine. Ce type doit être compatible avec la virtualisation imbriquée, comme les séries n1, n2 ou t2d. Pour en savoir plus, consultez la présentation de la virtualisation imbriquée.

    • owner (chaîne) : adresse e-mail de l'utilisateur qui lance la simulation.

    • max_simulation_time (entier) : durée maximale d'exécution de la simulation en secondes.

    • max_report_count (entier) : nombre de rapports de télémétrie après lesquels la simulation se termine.

  • Réponse de réussite (200 OK) :

    { "id": "sim-a1b2c3d4e5f6" }

Supprimer une simulation

Ce point de terminaison annule une simulation en attente ou en cours d'exécution, et supprime les ressources associées.

  • Point de terminaison : POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation
  • En-têtes
    • Content-Type: application/json

  • Corps de la requête :

    { "id": "sim-a1b2c3d4e5f6" }

  • Réponse de réussite (200 OK) : objet JSON vide {}.

Lire les données de simulation

Pour lire les données de simulation, vous pouvez interagir avec la fonction simulation-reader. Ces points de terminaison utilisent la méthode GET pour récupérer l'historique, l'état et la configuration du système.

Lister les simulations

Récupère une liste paginée de simulations avec prise en charge du filtrage et du tri.

  • Point de terminaison : GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations

  • Paramètres de requête (tous facultatifs) :

    • status (chaîne) : filtre par état de la simulation (running, Simulation request received, cancelled ou completed).
    • owner (chaîne) : filtre par adresse e-mail du propriétaire.
    • sort_by (chaîne) : champ de tri (received_at, status_updated_at, started_at). La valeur par défaut est received_at.
    • sort_order (chaîne) : ordre de tri, asc ou desc. La valeur par défaut est desc.
    • page_size (entier) : nombre de résultats par page. La valeur par défaut est 20.
    • page_token (chaîne) : jeton permettant de récupérer la page de résultats suivante.

  • Exemple de requête :

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

  • Réponse de réussite (200 OK) :

    • Renvoie un objet JSON contenant un tableau de simulations et un next_page_token facultatif.
    {
  "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"
}
Obtenir une simulation spécifique

Récupère tous les détails d'une simulation spécifique par son ID.

  • Point de terminaison :

    GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]

  • Réponse de réussite (200 OK) : renvoie un objet JSON contenant les détails de la simulation demandée.

    {
  "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
}
Obtenir les métriques et la configuration du système

Ces points de terminaison fournissent des informations sur la charge et la configuration actuelles de l'infrastructure de simulation.

  • Obtenir le nombre d'exécutions : renvoie le nombre de simulations en cours d'exécution.

    • Point de terminaison :

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

    • Réponse de réussite (200 OK) :

      {
  "count": 0
}

  • Obtenir le nombre maximal de VM simultanées : renvoie le nombre maximal configuré de VM en cours d'exécution simultanément.

    • Point de terminaison :

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

    • Réponse de réussite (200 OK) :

      {
  "max_running_vms": 5
}