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