Справочник по API

На этой странице представлена справочная документация по конечным точкам Metrics Configuration Generator (MCG) API.

Обзор конечных точек

В следующих разделах подробно описаны конечные точки API, доступные в MCG.

Настройка показателей

• POST /api/v2/generate_metrics_config: создание экземпляра MetricsConfig на основе сведений о запросе конфигурации показателя.
• POST /api/v2/get_file_descriptor_set – возвращает дескрипторы файлов для заданного MetricsConfig, чтобы декодировать отчеты.
• POST /api/v2/validate_metrics_config: проверяет переданный объект MetricsConfig и возвращает список ошибок.

Каталоги сигналов автомобиля

• POST /api/v2/vs/: создать новый или обновить существующий каталог сигналов автомобиля.
• GET /api/v2/vs/: список всех метаданных Vehicle Signal Catalog.
• DELETE /api/v2/vs/{version} – удаляет указанный каталог сигналов транспортного средства.

Состояние сервиса

• GET /health – проверьте статус сервиса.

Типы контента Protobuf

Некоторые конечные точки API принимают или возвращают данные в формате буфера протокола (protobuf). Используются два типа контента:

• application/x-protobuf – указывает на данные protobuf в двоичном формате. Этот формат удобен для межмашинного взаимодействия, но не предназначен для чтения человеком.
• text/x-protobuf – указывает на данные protobuf в текстовом формате, который удобен для чтения и полезен для отладки или ручной проверки.

Если конечная точка поддерживает несколько форматов protobuf для запроса или ответа, используйте заголовок Content-Type, чтобы указать формат данных запроса, и заголовок Accept, чтобы указать выбранный формат данных ответа. Пример:

• -H 'Content-Type: application/x-protobuf'
• -H 'Accept: text/x-protobuf'

Вызов API

В примерах на этой странице для вызова REST API используется curl. Предполагается, что вы настроили переменную среды SERVICE_URL для ссылки на хост, на котором развернут MCG. При локальном запуске это обычно http://localhost:8005.

Чтобы настроить таргетинг на удаленный экземпляр Cloud Run, задайте SERVICE_URL с помощью gcloud:

SERVICE_URL=$(gcloud run services describe mcg-service \
  --region=GCP_REGION \
  --format='value(status.url)')

При вызове удаленных конечных точек Cloud Run добавьте следующий заголовок авторизации к командам curl:

-H "Authorization: Bearer $(gcloud auth print-identity-token)"

Настройка показателей

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

POST /api/v2/generate_metrics_config

Создайте экземпляр MetricsConfig на основе сведений о запросе конфигурации показателей. Этот процесс включает проверку. Если генерация не удалась из-за нарушений схемы, недействительных ссылок, циклических зависимостей или других проблем, API возвращает список сведений об ошибках.

curl -H "Content-Type: application/json" \
  -H "Accept: text/x-protobuf" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v2/generate_metrics_config"
      

POST /api/v2/get_file_descriptor_set

Возвращает дескрипторы файлов для заданного MetricsConfig, чтобы декодировать отчеты.

curl -H "Content-Type: application/x-protobuf" \
  -H "Accept: application/x-protobuf" \
  --data-binary @PATH_TO_METRICS_CONFIG_PB \
  "$SERVICE_URL/api/v2/get_file_descriptor_set"
      

POST /api/v2/validate_metrics_config

Проверяет указанный объект MetricsConfig и возвращает список ошибок.

curl -H "Content-Type: application/x-protobuf" \
  -H "Accept: application/json" \
  --data-binary @PATH_TO_METRICS_CONFIG_PB \
  "$SERVICE_URL/api/v2/validate_metrics_config"
      

Каталоги сигналов автомобиля

В этом разделе описываются конечные точки для управления каталогами сигналов транспортных средств.

POST /api/v2/vs/

Создайте новый или обновите существующий каталог сигналов автомобиля.

{
  "version": "string",
  "vehicle_signals": "string"
}

{"version": "string"}

curl -H "Content-Type: application/json" \
  --data-binary @- "$SERVICE_URL/api/v2/vs/" << EOF
{
  "version": "v1.0",
  "vehicle_signals": "VEHICLE_SIGNALS_BASE64"
}
EOF
      

GET /api/v2/vs/

Получить список всех метаданных каталога сигналов транспортного средства.

{"versions": [{"version": "string"}]}

curl "$SERVICE_URL/api/v2/vs/"
      

DELETE /api/v2/vs/{version}

Удаляет указанный каталог сигналов транспортных средств.

{"version": "string"}

curl --request DELETE "$SERVICE_URL/api/v2/vs/v1.0"
      

Состояние сервиса

В этом разделе описываются конечные точки для проверки работоспособности сервиса.

GET /health

Проверьте состояние сервиса.

curl "$SERVICE_URL/health"
      

Ответы при ошибках

Если вызов API приводит к ошибке (HTTP status 4xx или 5xx), тело ответа содержит объект ошибки со следующей структурой:

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Request validation failed",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "fieldName",
            "description": "error description"
          }
        ]
      }
    ]
  }
}