API 参考文档

本页提供了指标配置生成器 (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。然后，在 curl 命令中附加包含 OpenID Connect (OIDC) 身份令牌的授权标头：

SERVICE_URL=$(gcloud run services describe mcg-service --region=<var label="Google Cloud region">GCP_REGION</var> --format='value(status.url)')

# Authorization header to append to curl command:
-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"
      

服务状态

本部分介绍了用于检查服务健康状况的端点。

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