Symulacje możesz przeprowadzać za pomocą udostępnionej wersji demonstracyjnej w internecie lub bezpośrednio wywołując interfejs API REST.
Dane wejściowe i wyjściowe
Pliki wejściowe i wyjściowe używają zasobnika Cloud Storage z konfiguracji Terraform.
Katalog wejściowy musi zawierać pliki metrics_config.zip i publisher_config.zip. Możesz zdefiniować ścieżkę do niego zgodnie z potrzebami.
Zasobnik na dane wyjściowe zawiera katalog simulations, w którym przechowywane są poszczególne symulacje według ich identyfikatorów. Każdy katalog symulacji zawiera folder inputs ze skopiowanymi plikami wejściowymi oraz folder outputs. Folder outputs zawiera raport o błędzie, plik logcat i wygenerowane pliki symulatora.
Korzystanie z wersji demonstracyjnej w przeglądarce
Platforma zawiera aplikację internetową opartą na Flutterze do celów demonstracyjnych, która umożliwia wyświetlanie symulacji, tworzenie ich i zarządzanie nimi. Zachęcamy do utworzenia własnego interfejsu dostosowanego do Twoich potrzeb.
Aplikacja demonstracyjna jest wdrażana w App Engine i wymaga zalogowania się na konto Google. Jest on chroniony za pomocą identyfikatora klienta OAuth 2.0 skonfigurowanego w projekcie Google Cloud. Zalogowane konto musi mieć uprawnienia do wywoływania wdrożonych funkcji w Cloud Functions. Instrukcje przyznawania niezbędnych uprawnień kontom użytkowników, takich jak rola wywołującego funkcje w Cloud Functions (roles/cloudfunctions.invoker), znajdziesz w artykule Autoryzowanie dostępu za pomocą uprawnień.
Proces użytkownika
- Zaloguj się na konto Google, uwierzytelnione za pomocą procesu OAuth 2.0.
- Wyświetl symulacje na stronie głównej, która zawiera listę wszystkich symulacji, wysyłając zapytanie do bazy danych Firestore, która zawiera wszystkie informacje o wykonaniu.
- Przejdź do formularza, aby zaplanować nową symulację, klikając przycisk polecenia + w prawym dolnym rogu. Podajesz 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 w aktualizacjach listy symulacji, które pokazują 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 typu REST.
Zmienna CLOUD_FUNCTION_URL używana w sekcji uwierzytelniania 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 Aktywator 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 do interfejsu API muszą być uwierzytelniane za pomocą tokena tożsamości, który potwierdza tożsamość elementu wywołującego. Tożsamość (użytkownik lub konto usługi) musi mieć uprawnienia wywołującego Cloud Functions w funkcji docelowej.
Wywołanie przez użytkownika (lokalne i w interfejsie wiersza poleceń): podczas wywoływania interfejsu API z komputera lokalnego lub środowiska spoza Google Cloud musisz użyć tokena tożsamości wydanego przez Google dla konta użytkownika.
TOKEN=$(gcloud auth print-identity-token)Wywołanie konta usługi (w Google Cloud): podczas wywoływania interfejsu 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 powinien zostać pobrany 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 w nagłówku Authorization żądań jako token Bearer.
Punkty końcowe
Punkty końcowe stosu symulacji Cloud Telemetry dla użytkowników umożliwiają tworzenie i usuwanie symulacji oraz odczytywanie informacji o symulacjach 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-requests 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 zostać użyty, na przykładlatest.file_path(ciąg tekstowy): ścieżka w zasobniku GCS do folderu zawierającego plikimetrics_config.zipipublisher_config.zip.instance_type(ciąg tekstowy): typ maszyny Compute Engine. Ten typ musi obsługiwać zagnieżdżoną wirtualizację, jak 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 rozpoczyna symulację.max_simulation_time(liczba całkowita): maksymalny czas symulacji w sekundach.max_report_count(liczba całkowita): liczba raportów telemetrycznych, po których symulacja się koń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 - Headers:
Content-Type: application/json
Treść żądania:
{ "id": "sim-a1b2c3d4e5f6" }Odpowiedź o powodzeniu (200 OK): wiadomość w formacie zwykłego tekstu (
Request accepted and is being processed).
Odczytywanie danych symulacji
Aby odczytać dane symulacji, możesz wejść w interakcję z funkcją simulation-reader.
Te punkty końcowe używają metody GET do pobierania historii, stanu i konfiguracji systemu.
Wyświetlanie listy symulacji
Pobiera listę symulacji z podziałem na strony, 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): filtruj według stanu symulacji (running,Simulation request received,cancelled,completedlubfailed).owner(ciąg tekstowy): filtruj według adresu e-mail właściciela.sort_by(ciąg znaków): pole, według którego ma być wykonywane sortowanie (received_at,status_updated_at,started_at). Wartość domyślna toreceived_at.sort_order(ciąg znaków): kierunek sortowania,asclubdesc. Domyślna wartość todesc.page_size(liczba całkowita): liczba wyników na stronę. 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 parametr
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 parametr
Pobieranie konkretnej symulacji
Pobiera pełne szczegóły konkretnej symulacji na podstawie 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 wskaźników i konfiguracji systemu
Te punkty końcowe zapewniają wgląd w bieżące obciążenie i konfigurację infrastruktury symulacji.
Get running count: zwraca liczbę uruchomionych symulacji.
Punkt końcowy:
GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/countOdpowiedź o powodzeniu (200 OK):
{ "count": 0 }
Get max concurrent VMs (Pobierz maksymalną liczbę równoczesnych maszyn wirtualnych): zwraca skonfigurowaną maksymalną liczbę równocześnie działających maszyn wirtualnych.
Punkt końcowy:
GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vmsOdpowiedź o powodzeniu (200 OK):
{ "max_running_vms": 5 }