Referencia de la API

En esta página, se proporciona documentación de referencia para los endpoints de API del generador de configuración de métricas (MCG).

Descripción general de Endpoints

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

Configuración de métricas

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

Catálogos de indicadores de vehículos

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

Estado del servicio

• GET /health: Verifica el estado del servicio.

Tipos de contenido de Protobuf

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

• application/x-protobuf: Indica los 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 por humanos.
• text/x-protobuf: Indica los datos de protobuf en su formato de texto, que es legible por humanos 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 configuraste 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 orientar una instancia remota de Cloud Run, configura SERVICE_URL con gcloud:

SERVICE_URL=$(gcloud run services describe mcg-service \
  --region=GCP_REGION \
  --format='value(status.url)')

Cuando llames a extremos remotos de Cloud Run, agrega el siguiente encabezado de autorización a tus comandos de curl:

-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 parámetros de configuración de métricas.

POST /api/v2/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 del esquema, referencias no válidas, dependencias cíclicas o cualquier otro problema, la API devuelve 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/v2/generate_metrics_config"
      

POST /api/v2/get_file_descriptor_set

Muestra 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/v2/get_file_descriptor_set"
      

POST /api/v2/validate_metrics_config

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

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"
      

Catálogos de indicadores de vehículos

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

POST /api/v2/vs/

Crea un catálogo de indicadores 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/v2/vs/" << EOF
{
  "version": "v1.0",
  "vehicle_signals": "VEHICLE_SIGNALS_BASE64"
}
EOF
      

GET /api/v2/vs/

Enumera todos los metadatos del catálogo de indicadores de vehículos.

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

curl "$SERVICE_URL/api/v2/vs/"
      

DELETE /api/v2/vs/{version}

Borra el catálogo de indicadores de vehículos especificado.

{"version": "string"}

curl --request DELETE "$SERVICE_URL/api/v2/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"
          }
        ]
      }
    ]
  }
}