À 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 utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Guide de l'utilisateur

Vous pouvez exécuter des simulations à l'aide de la démonstration 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 pour les sorties contient un répertoire simulations, qui stocke chaque simulation par son ID. Chaque répertoire de simulation contient un dossier inputs avec les fichiers d'entrée copiés et un dossier outputs. Le dossier outputs contient le rapport de bug, le fichier logcat et les fichiers de simulateur générés.

Utiliser la démonstration 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. Il est protégé par 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 Functions déployées. Consultez Autoriser l'accès avec IAM pour savoir comment accorder les autorisations nécessaires aux comptes utilisateur, telles que le rôle Demandeur Cloud Functions (roles/cloudfunctions.invoker).

Processus utilisateur

Connectez-vous avec votre compte Google, authentifié à l'aide du processus OAuth 2.0.
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.
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 compilation et le type d'instance. Pour en savoir plus, consultez Créer une simulation.
Vérifiez l'état de la surveillance dans les mises à jour de la liste des simulations, qui indiquent l'état de la nouvelle simulation, par exemple PENDING, RUNNING, COMPLETED.
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.
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 points 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 est affiché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 de demandeur Cloud Functions sur la fonction cible.

Appel 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)
```
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 visibles par l'utilisateur de la pile de simulation de télémétrie Cloud 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 planifie son exécution.

Point de terminaison : POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-requests
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 le mappage d'images autorisé de l'infrastructure, par exemple latest, stable. Le système rejette les tags inconnus si un mappage SHA256 est défini dans Terraform.
- file_path (chaîne) : chemin d'accès au dossier contenant metrics_config.zip et publisher_config.zip dans le bucket GCS.
- 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 lequel 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) : message en texte brut (Request accepted and is being processed).

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 simulation (running, Simulation request received, cancelled, completed ou failed).
- 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). Valeur par défaut : 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"
}

Obtenir une simulation spécifique

Récupère les détails complets d'une simulation spécifique à l'aide de 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 exécutées 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
}
```