Documentation de référence de l'API

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

Présentation d'Endpoints

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

Configuration des métriques

• POST /api/v1/generate_metrics_config : crée une instance MetricsConfig à partir des détails de la demande de configuration des métriques.
• POST /api/v1/get_file_descriptor_set : renvoie les descripteurs de fichier pour un MetricsConfig donné pour le décodage des rapports.
• POST /api/v1/validate_metrics_config : valide le MetricsConfig transmis et renvoie la liste des erreurs de validation.

Catalogues de signaux de véhicules

• POST /api/v1/vs/ : crée ou met à jour le catalogue de signaux de véhicules.
• GET /api/v1/vs/ : répertorie toutes les métadonnées du catalogue de signaux de véhicules.
• 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 Protocol Buffer (protobuf). Deux types de contenus sont utilisés :

• application/x-protobuf : indique les données protobuf dans leur format de communication binaire. Ce format est efficace pour la communication entre machines, mais n'est pas lisible par l'homme.
• text/x-protobuf : indique les données protobuf au format texte, qui sont lisibles par l'homme 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 de l'exécution en local, cette valeur est généralement http://localhost:8005.

Pour cibler une instance Cloud Run distante, définissez SERVICE_URL à l'aide de gcloud. Ensuite, ajoutez un en-tête d'autorisation avec un jeton d'identité OpenID Connect (OIDC) à votre commande 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)"

Configuration des métriques

Cette section décrit les points de terminaison permettant de générer et de valider les 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 de non-respect du schéma, de références non valides, de dépendances cycliques ou d'autres problèmes, l'API renvoie une liste d'informations sur les erreurs.

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 fichier pour un MetricsConfig donné pour les rapports de décodage.

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

Validez le MetricsConfig fourni et renvoyez 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éhicules

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 ou mettez à jour le catalogue de signaux de véhicules.

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