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。然後，在 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"
          }
        ]
      }
    ]
  }
}