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）形式でデータを受け渡しします。次の 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 の呼び出し

このページの例では、REST API の呼び出しに curl を使用し、MCG がデプロイされているホストを参照するように SERVICE_URL 環境変数を設定していることを前提としています。ローカルで実行する場合、通常は http://localhost:8005 です。

リモート Cloud Run インスタンスをターゲットにするには、gcloud を使用して SERVICE_URL を設定します。次に、OpenID Connect（OIDC）ID トークンを含む認証ヘッダーを curl コマンドに追加します。

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