Гид пользователя

Вы можете запускать симуляции, используя предоставленную веб-демонстрацию или напрямую вызывая REST API.

Ввод и вывод

Входные и выходные файлы используют хранилище Cloud Storage из настройки Terraform.

В директории ввода должны содержаться файлы metrics_config.zip и publisher_config.zip . Вы можете указать путь к ним по своему усмотрению.

В папке с выходными файлами находится каталог simulations , в котором хранится каждая симуляция по своему идентификатору. Каждый каталог симуляций содержит папку ввода со скопированными входными файлами и папку вывода. Папка вывода содержит отчет об ошибке, файл logcat и сгенерированные файлы симулятора.

Воспользуйтесь веб-демоверсией

Платформа включает в себя веб-приложение на основе Flutter для демонстрационных целей, которое позволяет просматривать, создавать и управлять симуляциями. Вам предлагается разработать собственный пользовательский интерфейс, адаптированный под ваши потребности.

Демонстрационное приложение развернуто в App Engine и требует входа в систему с помощью учетной записи Google. Защита осуществляется с помощью идентификатора клиента OAuth 2.0, настроенного в вашем проекте Google Cloud. У авторизованной учетной записи должны быть разрешения IAM для вызова развернутых облачных функций. См. раздел «Авторизация доступа с помощью IAM» для получения инструкций по предоставлению необходимых разрешений учетным записям пользователей, например, роли «Вызывающий Cloud Functions» ( roles/cloudfunctions.invoker ).

Рабочий процесс пользователя

  1. Войдите в систему, используя свою учетную запись Google, пройдя аутентификацию с помощью процесса OAuth 2.0.
  2. Просмотр результатов моделирования осуществляется на главной странице, где отображаются все результаты моделирования, полученные путем запроса к базе данных Firestore, содержащей всю информацию о выполнении.
  3. Для планирования новой симуляции перейдите к форме, нажав кнопку действия «+» в правом нижнем углу. Вам необходимо указать несколько параметров, включая путь к входным данным, идентификатор сборки и тип экземпляра. Дополнительную информацию см. в разделе «Создание симуляции» .
  4. Проверьте состояние монитора в списке обновлений моделирования, где отображается статус нового моделирования, например, PENDING , RUNNING , COMPLETED .
  5. После завершения моделирования просмотрите сгенерированные отчеты и артефакты. Входные файлы, выходные отчеты, журналы, Logcat и отчеты о сбоях хранятся в облачном хранилище.
  6. Необязательно: Отменить запланированную или уже идущую симуляцию.

использование API

Для автоматизации и интеграции с другими системами можно использовать REST API.

В разделе «Аутентификация» и в определениях конечных точек используется заполнитель CLOUD_FUNCTION_URL который указывает на базовый URL вызываемой облачной функции. URL-адреса функций можно найти в консоли Google Cloud на странице «Облачные функции» ; URL-адрес каждой функции отображается на вкладке «Триггер» на странице сведений о функции . Также эти URL-адреса можно найти в выходных данных Terraform, которые выводятся после выполнения команды apply .

Аутентификация

Все API-запросы должны быть аутентифицированы с помощью токена идентификации, подтверждающего личность вызывающего пользователя. Идентификатор (пользователь или сервисная учетная запись) должен иметь права доступа Cloud Functions Invoker к целевой функции.

  1. Вызов API пользователем (локальный и через командную строку): При вызове API с локального компьютера или из среды, не относящейся к Google Cloud, необходимо использовать токен идентификации, выданный Google и полученный для учетной записи пользователя.

    TOKEN=$(gcloud auth print-identity-token)

  2. Вызов сервисной учетной записи (внутри Google Cloud): При вызове API из ресурса Google Cloud (например, виртуальной машины Compute Engine, другой функции Cloud Function или кластера Kubernetes) используйте идентификатор сервисной учетной записи, прикрепленной к ресурсу. Токен должен быть получен с сервера метаданных ресурса.

    TOKEN=$(curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=CLOUD_FUNCTION_URL" -H "Metadata-Flavor: Google")

Включите полученный токен в заголовок Authorization ваших запросов в качестве токена Bearer .

Конечные точки

Пользовательские интерфейсы стека Cloud Telemetry Simulation позволяют создавать и удалять симуляции, а также считывать информацию о симуляциях из базы данных.

Создайте симуляцию

Этот конечный пункт создает новый запрос на моделирование и планирует его выполнение.

  • Конечная точка: POST https:// CLOUD_FUNCTION_URL /simulation-orchestrator-receive-request

  • Текст запроса:

    {
  "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 (строка): тег используемого образа Docker агента, например, latest .

    • file_path (строка): Путь внутри хранилища GCS к папке, содержащей metrics_config.zip и publisher_config.zip .

    • instance_type (строка): Тип вычислительной машины Compute Engine. Этот тип должен поддерживать вложенную виртуализацию, например, серии n1 , n2 или t2d . Для получения дополнительной информации см. обзор вложенной виртуализации .

    • owner (string): Адрес электронной почты пользователя, инициировавшего симуляцию.

    • max_simulation_time (целое число): Максимальное время выполнения симуляции в секундах.

    • max_report_count (целое число): Количество телеметрических отчетов, после которого моделирование завершается.

  • Успешный ответ (200 OK):

    { "id": "sim-a1b2c3d4e5f6" }

Удалить симуляцию

Этот конечный пункт отменяет ожидающую или запущенную симуляцию и удаляет связанные с ней ресурсы.

  • Конечная точка: POST https:// CLOUD_FUNCTION_URL /simulation-orchestrator-delete-simulation
  • Заголовки:
    • Content-Type: application/json

  • Текст запроса:

    { "id": "sim-a1b2c3d4e5f6" }

  • Успешный ответ (200 OK): Пустой JSON-объект {} .

Прочитайте данные моделирования.

Для чтения данных моделирования можно взаимодействовать с функцией simulation-reader . Эти конечные точки используют метод GET для получения истории, состояния и конфигурации системы.

Список симуляций

Получает постраничный список симуляций с поддержкой фильтрации и сортировки.

  • Конечная точка: GET https:// CLOUD_FUNCTION_URL /simulation-reader/simulations

  • Параметры запроса (все необязательные):

    • status (строка): Фильтр по статусу моделирования ( running , Simulation request received , cancelled или completed ).
    • owner (строка): Фильтр по электронной почте владельца.
    • sort_by (string): Поле для сортировки ( received_at , status_updated_at , started_at ). По умолчанию используется received_at .
    • sort_order (строка): Направление сортировки, asc или desc . По умолчанию используется desc .
    • page_size (целое число): Количество результатов на странице. По умолчанию — 20.
    • page_token (string): Токен для получения следующей страницы результатов.

  • Пример запроса:

    curl -H "Authorization: Bearer $TOKEN"
"https://CLOUD_FUNCTION_URL/simulation-reader/simulations?status=completed&owner=user@example.com&sort_by=status_updated_at"

  • Успешный ответ (200 OK):

    • Возвращает JSON-объект, содержащий массив симуляций и необязательный токен 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"
}
Получите конкретную симуляцию

Получает полную информацию о конкретной симуляции по ее идентификатору.

  • Конечная точка:

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

  • Успешный ответ (200 OK): Возвращает JSON-объект, содержащий подробную информацию о запрошенной симуляции.

    {
  "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
}
Получение системных метрик и конфигурации.

Эти конечные точки позволяют получить представление о текущей нагрузке и конфигурации инфраструктуры моделирования.

  • Получить количество запущенных симуляций: Возвращает количество запущенных симуляций.

    • Конечная точка: 

      GET https://CLOUD_FUNCTION_URL/simulation-reader/simulations/running/count

    • Успешный ответ (200 OK): 

      {
  "count": 0
}

  • Получить максимальное количество одновременно работающих виртуальных машин: Возвращает заданное максимальное количество одновременно запущенных виртуальных машин.

    • Конечная точка: 

      GET https://CLOUD_FUNCTION_URL/simulation-reader/config/max-running-vms

    • Успешный ответ (200 OK): 

      {
  "max_running_vms": 5
}