API 参考

本页面提供了 Metrics Configuration Generator (MCG) API 端点的参考文档。

端点概览

以下部分详细介绍了 MCG 中提供的 API 端点。

指标配置

• POST /api/v1/generate_metrics_config：根据指标配置请求详细信息创建 MetricsConfig 实例。
• POST /api/v1/get_file_descriptor_set：返回给定 MetricsConfig 的文件描述符，以便解码报告。
• POST /api/v1/validate_metrics_config：验证传递的 MetricsConfig，并返回验证错误列表。

车辆信号目录

• POST /api/v1/vs/：创建新的车辆信号目录或更新现有车辆信号目录。
• GET /api/v1/vs/：列出所有车辆信号目录元数据。
• DELETE /api/v1/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

本页面上的示例使用 curl 调用 REST API，并假设您将 SERVICE_URL 环境变量设置为引用部署 MCG 的主机。在本地运行时，此值通常为 http://localhost:8005。

如需定位到远程 Cloud Run 实例，请使用 gcloud 设置 SERVICE_URL：

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/v1/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/v1/generate_metrics_config"
      

POST /api/v1/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/v1/get_file_descriptor_set"
      

POST /api/v1/validate_metrics_config

验证提供的 MetricsConfig，并返回所有验证错误的列表。

curl -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v1/validate_metrics_config"
      

车辆信号目录

本部分介绍了用于管理车辆信号目录的端点。

POST /api/v1/vs/

创建新的车辆信号目录或更新现有车辆信号目录。

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

{"version": "string"}

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

GET /api/v1/vs/

列出所有车辆信号目录元数据。

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

curl "$SERVICE_URL/api/v1/vs/"
      

DELETE /api/v1/vs/{version}

删除指定的车辆信号目录。

{"version": "string"}

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

服务状态

本部分介绍了用于检查 Service Health 的端点。

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"
          }
        ]
      }
    ]
  }
}