Puoi eseguire simulazioni utilizzando la demo web fornita o chiamando direttamente l'API REST.
Input e output
I file di input e di output utilizzano il bucket Cloud Storage della configurazione di Terraform.
La directory di input deve contenere i file metrics_config.zip e publisher_config.zip. Puoi definire il percorso in base alle tue esigenze.
Il bucket per gli output contiene una directory simulations, che memorizza ogni simulazione in base al relativo ID. Ogni directory di simulazione contiene una cartella inputs con i file di input copiati e una cartella outputs. La cartella outputs contiene
la segnalazione di bug, il file logcat e i file del simulatore generati.
Utilizza la demo web
La piattaforma include un'applicazione web basata su Flutter a scopo dimostrativo che ti consente di visualizzare, creare e gestire le simulazioni. Ti invitiamo a creare la tua interfaccia utente personalizzata in base alle tue esigenze.
Il deployment dell'app demo viene eseguito in App Engine e richiede l'accesso con un Account Google. Questo è protetto utilizzando un ID client OAuth 2.0 configurato nel tuo progetto Google Cloud. L'account che ha eseguito l'accesso deve disporre delle autorizzazioni IAM per richiamare le funzioni Cloud Functions di cui è stato eseguito il deployment. Consulta Autorizza l'accesso con IAM per istruzioni su come concedere le autorizzazioni necessarie agli account utente, ad esempio il ruolo Cloud Functions Invoker (roles/cloudfunctions.invoker).
Workflow utente
- Accedi con il tuo Account Google, autenticato tramite la procedura OAuth 2.0.
- Visualizza le simulazioni nella pagina principale, che elenca tutte le simulazioni eseguendo una query sul database Firestore, che contiene tutte le informazioni sull'esecuzione.
- Vai a un modulo per pianificare una nuova simulazione facendo clic sul pulsante di azione + nell'angolo in basso a destra. Devi fornire diversi parametri, tra cui il percorso di input, l'ID build e il tipo di istanza. Per saperne di più, consulta Crea una simulazione.
- Controlla lo stato del monitoraggio negli aggiornamenti dell'elenco delle simulazioni, che mostrano lo stato della nuova simulazione, ad esempio
PENDING,RUNNING,COMPLETED. - Al termine di una simulazione, visualizza i report e gli artefatti generati. I file di input, i report di output, i log, Logcat e i report sui bug vengono archiviati in Cloud Storage.
- (Facoltativo) Annulla una simulazione pianificata o in esecuzione.
Utilizzo delle API
Per l'automazione e l'integrazione con altri sistemi, puoi utilizzare l'API REST.
Il segnaposto CLOUD_FUNCTION_URL utilizzato nella sezione Autenticazione e nelle definizioni degli endpoint fa riferimento all'URL di base della funzione Cloud Functions richiamata. Puoi trovare gli URL delle funzioni nella console Google Cloud nella pagina Cloud Functions. L'URL di ogni funzione viene visualizzato nella scheda Trigger della pagina Dettagli funzione. In alternativa, puoi trovare questi URL negli output di Terraform stampati dopo l'esecuzione di un comando apply.
Autenticazione
Tutte le richieste API devono essere autenticate con un token ID che dimostri l'identità del chiamante. L'identità (utente o service account) deve disporre delle autorizzazioni Cloud Functions Invoker per la funzione di destinazione.
Chiamata utente (locale e CLI): quando chiami l'API da una macchina locale o da un ambiente non Google Cloud, devi utilizzare un token ID emesso da Google ottenuto per un account utente.
TOKEN=$(gcloud auth print-identity-token)Chiamata del service account (all'interno di Google Cloud): quando chiami l'API da una risorsa Google Cloud (ad esempio una VM Compute Engine, un'altra funzione Cloud Functions o un cluster Kubernetes), utilizza l'identità del service account collegato alla risorsa. Il token deve essere recuperato dal server di metadati della risorsa.
TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")
Includi il token recuperato nell'intestazione Authorization delle tue richieste come token Bearer.
Endpoint
Gli endpoint rivolti agli utenti dello stack di simulazione di Cloud Telemetry ti consentono di creare ed eliminare simulazioni o di leggere le informazioni di simulazione dal database.
Crea una simulazione
Questo endpoint crea una nuova richiesta di simulazione e ne pianifica l'esecuzione.
- Endpoint:
POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-requests Corpo della richiesta:
{ "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(stringa): il tag dell'immagine Docker dell'agente da utilizzare, ad esempiolatest.file_path(stringa): il percorso all'interno del bucket GCS della cartella contenentemetrics_config.zipepublisher_config.zip.instance_type(stringa): il tipo di macchina Compute Engine. Questo tipo deve supportare la virtualizzazione nidificata, ad esempio le serien1,n2ot2d. Per saperne di più, consulta la panoramica della virtualizzazione nidificata.owner(stringa): l'indirizzo email dell'utente che avvia la simulazione.max_simulation_time(numero intero): il tempo massimo in secondi durante il quale viene eseguita la simulazione.max_report_count(integer): il numero di report di telemetria dopo i quali la simulazione termina.
Risposta di esito positivo (200 OK):
{ "id": "sim-a1b2c3d4e5f6" }
Elimina una simulazione
Questo endpoint annulla una simulazione in attesa o in esecuzione ed elimina le risorse associate.
- Endpoint:
POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation - Intestazioni:
Content-Type: application/json
Corpo della richiesta:
{ "id": "sim-a1b2c3d4e5f6" }Risposta di esito positivo (200 OK): un messaggio di testo normale (
Request accepted and is being processed).
Lettura dei dati di simulazione
Per leggere i dati di simulazione, puoi interagire con la funzione simulation-reader.
Questi endpoint utilizzano il metodo GET per recuperare la cronologia, lo stato e la configurazione del sistema.
Elenca simulazioni
Recupera un elenco impaginato di simulazioni con supporto per l'applicazione di filtri e l'ordinamento.
- Endpoint:
GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations Parametri di query (tutti facoltativi):
status(stringa): filtra in base allo stato della simulazione (running,Simulation request received,cancelled,completedofailed).owner(stringa): filtra in base all'indirizzo email del proprietario.sort_by(stringa): campo in base al quale ordinare (received_at,status_updated_at,started_at). Il valore predefinito èreceived_at.sort_order(stringa): direzione di ordinamento,ascodesc. Il valore predefinito èdesc.page_size(integer): numero di risultati per pagina. Il valore predefinito è 20.page_token(stringa): token per recuperare la pagina di risultati successiva.
Esempio di richiesta:
curl -H "Authorization: Bearer $TOKEN" "https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"Risposta di esito positivo (200 OK):
- Restituisce un oggetto JSON contenente un array di simulazioni e un
next_page_tokenfacoltativo.
{ "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" }- Restituisce un oggetto JSON contenente un array di simulazioni e un
Ottieni una simulazione specifica
Recupera i dettagli completi di una simulazione specifica in base al suo ID.
Endpoint:
GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]Risposta di esito positivo (200 OK): restituisce un oggetto JSON contenente i dettagli della simulazione richiesta.
{ "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 }
Ottieni metriche e configurazione di sistema
Questi endpoint forniscono informazioni sul carico e sulla configurazione attuali dell'infrastruttura di simulazione.
Recupera conteggio in esecuzione: restituisce il conteggio delle simulazioni in esecuzione.
Endpoint:
GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/countRisposta di esito positivo (200 OK):
{ "count": 0 }
Recupera il numero massimo di VM contemporanee: restituisce il numero massimo configurato di VM in esecuzione contemporaneamente.
Endpoint:
GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vmsRisposta di esito positivo (200 OK):
{ "max_running_vms": 5 }