Documentation de référence de l'API

Cette page fournit une documentation de référence sur les points de terminaison de l'API Metrics Configuration Generator (MCG).

Présentation d'Endpoints

Les sections suivantes décrivent les points de terminaison de l'API disponibles dans MCG.

Configuration des métriques

• POST /api/v1/generate_metrics_config : créez une instance MetricsConfig à partir des détails de la requête de configuration des métriques.
• POST /api/v1/get_file_descriptor_set : renvoie les descripteurs de fichier d'un MetricsConfig donné pour décoder les rapports.
• POST /api/v1/validate_metrics_config : valide l'élément MetricsConfig transmis et renvoie une liste des erreurs de validation.

Catalogues de signaux de véhicule

• POST /api/v1/vs/ : créez un catalogue de signaux de véhicule ou mettez à jour un catalogue existant.
• GET /api/v1/vs/ : lister toutes les métadonnées du catalogue de signaux de véhicule.
• DELETE /api/v1/vs/{version} : supprime le catalogue de signaux de véhicule spécifié.

État du service

• GET /health : vérifiez l'état du service.

Types de contenus Protobuf

Plusieurs points de terminaison d'API acceptent ou renvoient des données au format de tampon de protocole (protobuf). Deux types de contenu sont utilisés :

• application/x-protobuf : indique les données protobuf dans leur format de communication binaire. Ce format est efficace pour la communication de machine à machine, mais n'est pas lisible par l'humain.
• text/x-protobuf : indique les données protobuf au format texte, qui sont lisibles par l'humain et utiles pour le débogage ou l'inspection manuelle.

Lorsqu'un point de terminaison accepte plusieurs formats protobuf pour une requête ou une réponse, utilisez l'en-tête Content-Type pour spécifier le format des données de requête et l'en-tête Accept pour spécifier le format sélectionné des données de réponse. Exemple :

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

Appeler l'API

Les exemples de cette page utilisent curl pour appeler l'API REST et supposent que vous avez défini la variable d'environnement SERVICE_URL pour faire référence à l'hôte sur lequel MCG est déployé. Lors d'une exécution locale, il s'agit généralement de http://localhost:8005.

Pour cibler une instance Cloud Run distante, définissez SERVICE_URL à l'aide de gcloud :

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

Lorsque vous appelez des points de terminaison Cloud Run distants, ajoutez l'en-tête d'autorisation suivant à vos commandes curl :

-H "Authorization: Bearer $(gcloud auth print-identity-token)"

Configuration des métriques

Cette section décrit les points de terminaison permettant de générer et de valider des configurations de métriques.

POST /api/v1/generate_metrics_config

Créez une instance MetricsConfig à partir des détails de la requête de configuration des métriques. Ce processus inclut la validation. Si la génération échoue en raison d'infractions au schéma, de références non valides, de dépendances cycliques ou d'autres problèmes, l'API renvoie une liste de détails sur l'erreur.

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

Renvoie les descripteurs de fichiers d'un MetricsConfig donné pour décoder les rapports.

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

Valide le MetricsConfig fourni et renvoie une liste des erreurs de validation.

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

Catalogues de signaux de véhicule

Cette section décrit les points de terminaison permettant de gérer les catalogues de signaux de véhicules.

POST /api/v1/vs/

Créez un catalogue de signaux de véhicule ou mettez à jour un catalogue existant.

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

Répertoriez toutes les métadonnées du catalogue de signaux de véhicules.

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

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

DELETE /api/v1/vs/{version}

Supprime le catalogue de signaux de véhicule spécifié.

{"version": "string"}

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

État du service

Cette section décrit les points de terminaison permettant de vérifier l'état du service.

GET /health

Vérifiez l'état du service.

curl "$SERVICE_URL/health"
      

Réponses d'erreur

Lorsqu'un appel d'API génère une erreur (HTTP status 4xx ou 5xx), le corps de la réponse contient un objet d'erreur ayant la structure suivante :

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