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 호출

이 페이지의 예시에서는 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"
          }
        ]
      }
    ]
  }
}