À partir de 2026, pour nous aligner sur notre modèle de développement stable et garantir la stabilité de la plate-forme pour l'écosystème, nous publierons le code source sur AOSP au deuxième et au quatrième trimestre. Pour créer et contribuer dans AOSP, utilisez android-latest-release. La branche de fichier manifeste android-latest-release fera toujours référence à la version la plus récente envoyée à AOSP. Pour en savoir plus, consultez Modifications apportées à AOSP.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Guide utilisateur

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

Entrée et sortie

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 sorties 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 exige que les utilisateurs se connectent avec un compte Google. Il est protégé à 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. Consultez Gérer l'accès à Cloud Functions pour savoir comment accorder les autorisations nécessaires aux comptes utilisateur, comme le rôle Demandeur Cloud Functions (roles/cloudfunctions.invoker).

Parcours utilisateur

Se connecter : vous vous connectez avec votre compte Google, authentifié à l'aide du processus OAuth 2.0.
Afficher les simulations : la page principale liste toutes les simulations passées et en cours en interrogeant la base de données Firestore, qui contient toutes les informations d'exécution.
Créer une simulation : vous 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'entrée, l'ID de compilation et le type d'instance. Pour en savoir plus, consultez Créer une simulation.
Surveiller l'état : la liste des simulations est mise à jour pour afficher l'état de la nouvelle simulation (PENDING, RUNNING, COMPLETED, etc.).
Afficher les résultats : une fois la simulation terminée, vous pouvez consulter 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.
Supprimer une simulation : vous pouvez annuler 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 points de terminaison fait référence à l'URL de base de la fonction Cloud appelée. Vous trouverez les URL des fonctions sur la page Cloud Functions de la console Google Cloud. L'URL de chaque fonction est indiquée dans l'onglet Déclencheur de la 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. Invocation par l'utilisateur (local et CLI) : lorsque vous appelez l'API depuis une machine locale ou un environnement non Google Cloud, vous devez utiliser un jeton d'identité émis par Google obtenu pour un compte utilisateur.
```
TOKEN=$(gcloud auth print-identity-token)
```
2. Invocation 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), vous devez utiliser 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 orientés 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 demande 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"). Important : Cette valeur doit correspondre à un tag défini dans la carte des images autorisées de l'infrastructure (par exemple, "latest" ou "stable"). Le système rejette les tags inconnus si une carte SHA256 est définie dans Terraform.
- 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 de l'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) : un 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.

1. Lister les simulations

Récupère une liste paginée de simulations avec possibilité de filtrage et de tri.

Point de terminaison : GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations
Paramètres de requête (tous facultatifs) :
- status (chaîne) : filtrez par état de simulation (running, Simulation request received, cancelled ou completed).
- owner (chaîne) : filtrez 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 d'extraire 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"
}

2. Obtenir une simulation spécifique

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

Point de terminaison :

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

Réponse en cas de succès (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
}

3. 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.

Get Running Count (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
}
```