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

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

Ввод и вывод

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

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

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

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

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

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

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

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

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

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

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

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

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

  • 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"). Важно : он должен совпадать с тегом, определенным в разрешенной карте образов инфраструктуры (например, "latest", "stable"). Система отклоняет неизвестные теги, если в Terraform определена карта SHA256.
    • 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 для получения истории, состояния и конфигурации системы.

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

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

  • Конечная точка : 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"
}

2. Получите конкретную симуляцию.

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

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

    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
}

3. Получение системных метрик и конфигурации.

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

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

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

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

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

      {
  "count": 0
}

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

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

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

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

      {
  "max_running_vms": 5
}