Referencia de la API

En esta página, se proporciona documentación de referencia para los extremos de la API de Metrics Configuration Generator (MCG).

Descripción general de los extremos

En las siguientes secciones, se detallan los extremos de la API disponibles en MCG.

Configuración de métricas

• POST /api/v1/generate_metrics_config: Crea una instancia de MetricsConfig a partir de los detalles de la solicitud de configuración de métricas.
• POST /api/v1/get_file_descriptor_set: Muestra los descriptores de archivos para un MetricsConfig determinado para decodificar informes.
• POST /api/v1/validate_metrics_config: Valida el MetricsConfig pasado y muestra una lista de los errores de validación.

Catálogos de señales de vehículos

• POST /api/v1/vs/: Crea un catálogo de señales de vehículos nuevo o actualiza uno existente.
• GET /api/v1/vs/: Enumera todos los metadatos del catálogo de señales de vehículos.
• DELETE /api/v1/vs/{version}: Borra el catálogo de señales de vehículos especificado.

Estado del servicio

• GET /health: Verifica el estado del servicio.

Tipos de contenido de búfer de protocolo

Varios extremos de la API aceptan o muestran datos en formato de búfer de protocolo (protobuf). Se usan dos tipos de contenido:

• application/x-protobuf: Indica datos de protobuf en su formato de transmisión binario. Este formato es eficiente para la comunicación de máquina a máquina, pero no es legible para las personas.
• text/x-protobuf: Indica datos de protobuf en su formato de texto, que es legible para las personas y útil para la depuración o la inspección manual.

Cuando un extremo admite varios formatos de protobuf para una solicitud o respuesta, usa el encabezado Content-Type para especificar el formato de los datos de la solicitud y el encabezado Accept para especificar el formato seleccionado de los datos de la respuesta. Por ejemplo:

• -H 'Content-Type: application/x-protobuf'
• -H 'Accept: text/x-protobuf'

Llama a la API

En los ejemplos de esta página, se usa curl para llamar a la API de REST y se supone que estableciste la variable de entorno SERVICE_URL para hacer referencia al host en el que se implementa MCG. Cuando se ejecuta de forma local, suele ser http://localhost:8005.

Para segmentar una instancia remota de Cloud Run, establece SERVICE_URL con gcloud. Luego, agrega un encabezado de autorización con un token de identidad de OpenID Connect (OIDC) a tu comando 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)"

Configuración de métricas

En esta sección, se describen los extremos para generar y validar configuraciones de métricas.

POST /api/v1/generate_metrics_config

Crea una instancia de MetricsConfig a partir de los detalles de la solicitud de configuración de métricas. Este proceso incluye la validación y, si la generación falla debido a incumplimientos de esquema, referencias no válidas, dependencias cíclicas o cualquier otro problema, la API muestra una lista de detalles del error.

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

Muestra los descriptores de archivos para un MetricsConfig determinado para decodificar informes.

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

Valida el MetricsConfig proporcionado y muestra una lista de los errores de validación.

curl -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v1/validate_metrics_config"
      

Catálogos de señales de vehículos

En esta sección, se describen los extremos para administrar catálogos de señales de vehículos.

POST /api/v1/vs/

Crea un catálogo de señales de vehículos nuevo o actualiza uno existente.

{
  "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/

Enumera todos los metadatos del catálogo de señales de vehículos.

{"versions": [{"version": "string"}]}

curl "$SERVICE_URL/api/v1/vs/"
      

DELETE /api/v1/vs/{version}

Borra el catálogo de señales de vehículos especificado.

{"version": "string"}

curl --request DELETE "$SERVICE_URL/api/v1/vs/v1.0"
      

Estado del servicio

En esta sección, se describen los extremos para verificar el estado del servicio.

GET /health

Verifica el estado del servicio.

curl "$SERVICE_URL/health"
      

Respuestas de error

Cuando una llamada a la API genera un error (HTTP status 4xx o 5xx), el cuerpo de la respuesta contiene un objeto de error con la siguiente estructura:

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Request validation failed",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "fieldName",
            "description": "error description"
          }
        ]
      }
    ]
  }
}