API リファレンス

このページでは、Metrics Configuration Generator（MCG）API エンドポイントのリファレンス ドキュメントについて説明します。

Endpoints の概要

以降のセクションでは、MCG で使用できる API エンドポイントについて詳しく説明します。

指標の構成

• 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/: すべての車両シグナル カタログのメタデータを一覧表示します。
• DELETE /api/v2/vs/{version}: 指定された車両シグナル カタログを削除します。

サービスのステータス

• GET /health: サービスの健全性を確認します。

Protobuf のコンテンツ タイプ

いくつかの API エンドポイントは、プロトコル バッファ（protobuf）形式でデータを受け入れるか、返します。次の 2 つのコンテンツ タイプが使用されます。

• 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 を呼び出し、MCG がデプロイされているホストを参照するように SERVICE_URL 環境変数を設定していることを前提としています。ローカルで実行する場合、通常は 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/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"
      

サービスのステータス

このセクションでは、Service Health を確認するためのエンドポイントについて説明します。

GET /health

サービスの健全性を確認します。

curl "$SERVICE_URL/health"
      

Error responses（エラー応答）

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