Symulacje możesz uruchamiać za pomocą udostępnionej wersji demonstracyjnej w internecie lub przez bezpośrednie wywoływanie interfejsu API REST.
Dane wejściowe i wyjściowe
Pliki wejściowe i wyjściowe korzystają z zasobnika Cloud Storage z konfiguracji Terraform.
Katalog wejściowy musi zawierać pliki metrics_config.zip i publisher_config.zip. W razie potrzeby możesz zdefiniować ścieżkę do niego.
Zasobnik na dane wyjściowe zawiera katalog simulations, w którym każda symulacja jest przechowywana według identyfikatora. Każdy katalog symulacji zawiera folder wejściowy ze skopiowanymi plikami wejściowymi i folder wyjściowy. Folder wyjściowy zawiera raport o błędach, plik logcat i wygenerowane pliki symulatora.
Korzystanie z wersji demonstracyjnej w internecie
Platforma zawiera aplikację internetową opartą na Flutterze, która służy do celów demonstracyjnych i umożliwia wyświetlanie, tworzenie i zarządzanie symulacjami. Zachęcamy do utworzenia własnego interfejsu użytkownika dostosowanego do Twoich potrzeb.
Aplikacja w wersji demonstracyjnej jest wdrażana w App Engine i wymaga zalogowania się na konto Google. Jest ona chroniona za pomocą identyfikatora klienta OAuth 2.0 skonfigurowanego w projekcie w chmurze Google. Zalogowane konto musi mieć uprawnienia do wywoływania wdrożonych funkcji w Cloud Functions. Instrukcje dotyczące przyznawania niezbędnych uprawnień kontom użytkowników, np. roli Wywołujący funkcje Cloud Functions (roles/cloudfunctions.invoker), znajdziesz w artykule Autoryzowanie dostępu za pomocą uprawnień.
Proces użytkownika
- Zaloguj się na konto Google, uwierzytelniając się za pomocą procesu OAuth 2.0.
- Wyświetl symulacje na stronie głównej, która zawiera listę wszystkich symulacji uzyskanych przez wysłanie zapytania do bazy danych Firestore, w której przechowywane są wszystkie informacje o wykonaniu.
- Przejdź do formularza, aby zaplanować nową symulację, klikając przycisk polecenia + w prawym dolnym rogu. Podaj kilka parametrów, w tym ścieżkę wejściową, identyfikator kompilacji i typ instancji. Więcej informacji znajdziesz w artykule Tworzenie symulacji.
- Sprawdź stan monitora na liście symulacji, która pokazuje stan nowej symulacji, np.
PENDING,RUNNING,COMPLETED. - Po zakończeniu symulacji wyświetl wygenerowane raporty i artefakty. Pliki wejściowe, raporty wyjściowe, logi, logcat i raporty o błędach są przechowywane w Cloud Storage.
- Opcjonalnie: anuluj zaplanowaną lub uruchomioną symulację.
Korzystanie z interfejsu API
Do automatyzacji i integracji z innymi systemami możesz używać interfejsu API REST.
Symbol zastępczy CLOUD_FUNCTION_URL
używany w sekcji Uwierzytelnianie i w definicjach punktów końcowych odnosi się do
podstawowego adresu URL wywoływanej funkcji w Cloud Functions. Adresy URL funkcji znajdziesz w konsoli Google Cloud na stronie Cloud Functions. Adres URL każdej funkcji jest widoczny na karcie Wyzwalacz na stronie Szczegóły funkcji. Możesz też znaleźć te adresy URL w danych wyjściowych Terraform, które są wyświetlane po uruchomieniu polecenia apply.
Uwierzytelnianie
Wszystkie żądania wysyłane do interfejsu API muszą być uwierzytelniane za pomocą tokena tożsamości, który potwierdza tożsamość dzwoniącego. Tożsamość (użytkownik lub konto usługi) musi mieć uprawnienia Wywołujący funkcje Cloud Functions do funkcji docelowej.
Wywołanie przez użytkownika (lokalne i interfejs wiersza poleceń): gdy wywołujesz interfejs API z komputera lokalnego lub środowiska innego niż Google Cloud, musisz użyć tokena tożsamości wydanego przez Google, który został uzyskany na potrzeby konta użytkownika.
TOKEN=$(gcloud auth print-identity-token)Wywołanie przez konto usługi (w Google Cloud): gdy wywołujesz interfejs API z zasobu Google Cloud (np. maszyny wirtualnej Compute Engine, innej funkcji w Cloud Functions lub klastra Kubernetes), użyj tożsamości konta usługi dołączonego do zasobu. Token należy pobrać z serwera metadanych zasobu.
TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")
Dołącz pobrany token do nagłówka Authorization w żądaniach jako token Bearer.
Punkty końcowe
Punkty końcowe stosu symulacji telemetrii w chmurze, z których korzystają użytkownicy, umożliwiają tworzenie i usuwanie symulacji oraz odczytywanie informacji o symulacji z bazy danych.
Tworzenie symulacji
Ten punkt końcowy tworzy nowe żądanie symulacji i planuje jego wykonanie.
- Punkt końcowy:
POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-receive-request Treść żądania:
{ "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(ciąg znaków): tag obrazu Dockera agenta, który ma być używany,np.latest.file_path(ciąg znaków): ścieżka w zasobniku GCS do folderu zawierającego plikimetrics_config.zipipublisher_config.zip.instance_type(ciąg znaków): typ maszyny Compute Engine. Ten typ musi obsługiwać zagnieżdżoną wirtualizację, np. serien1,n2lubt2d. Więcej informacji znajdziesz w omówieniu zagnieżdżonej wirtualizacji.owner(ciąg znaków): adres e-mail użytkownika, który inicjuje symulację.max_simulation_time(liczba całkowita): maksymalny czas w sekundach, przez jaki będzie działać symulacja.max_report_count(liczba całkowita): liczba raportów telemetrycznych, po których symulacja się zakończy.
Odpowiedź o powodzeniu (200 OK):
{ "id": "sim-a1b2c3d4e5f6" }
Usuwanie symulacji
Ten punkt końcowy anuluje oczekującą lub uruchomioną symulację i usuwa powiązane z nią zasoby.
- Punkt końcowy:
POST https://CLOUD_FUNCTION_URL/simulation-orchestrator-delete-simulation - Nagłówki:
Content-Type: application/json
Treść żądania:
{ "id": "sim-a1b2c3d4e5f6" }Odpowiedź o powodzeniu (200 OK): pusty obiekt JSON
{}.
Odczytywanie danych symulacji
Aby odczytać dane symulacji, możesz korzystać z funkcji simulation-reader.
Te punkty końcowe używają metody GET do pobierania historii, stanu i konfiguracji systemu.
Wyświetlanie listy symulacji
Pobiera stronicowaną listę symulacji z obsługą filtrowania i sortowania.
- Punkt końcowy:
GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations Parametry zapytania (wszystkie opcjonalne):
status(ciąg znaków): filtr według stanu symulacji (running,Simulation request received,cancelledlubcompleted).owner(ciąg znaków): filtr według adresu e-mail właściciela.sort_by(ciąg znaków): pole, według którego ma być sortowane (received_at,status_updated_at,started_at). Domyślniereceived_at.sort_order(ciąg znaków): kolejność sortowania,asclubdesc. Domyślniedesc.page_size(liczba całkowita): liczba wyników na stronie. Wartość domyślna to 20.page_token(ciąg znaków): token do pobierania następnej strony wyników.
Przykładowe żądanie:
curl -H "Authorization: Bearer $TOKEN" "https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"Odpowiedź o powodzeniu (200 OK):
- Zwraca obiekt JSON zawierający tablicę symulacji i opcjonalny token
next_page_token.
{ "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" }- Zwraca obiekt JSON zawierający tablicę symulacji i opcjonalny token
Pobieranie konkretnej symulacji
Pobiera pełne szczegóły konkretnej symulacji według jej identyfikatora.
Punkt końcowy:
GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/[SIMULATION_ID]Odpowiedź o powodzeniu (200 OK): zwraca obiekt JSON zawierający szczegóły żądanej symulacji.
{ "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 }
Pobieranie danych i konfiguracji systemu
Te punkty końcowe umożliwiają uzyskanie informacji o bieżącym obciążeniu i konfiguracji infrastruktury symulacji.
Pobieranie liczby uruchomionych symulacji: zwraca liczbę uruchomionych symulacji.
Punkt końcowy:
GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/countOdpowiedź o powodzeniu (200 OK):
{ "count": 0 }
Pobieranie maksymalnej liczby równoczesnych maszyn wirtualnych: zwraca skonfigurowaną maksymalną liczbę równoczesnych uruchomionych maszyn wirtualnych.
Punkt końcowy:
GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vmsOdpowiedź o powodzeniu (200 OK):
{ "max_running_vms": 5 }