Riferimento API

Questa pagina fornisce la documentazione di riferimento per gli endpoint API del generatore di configurazione delle metriche (MCG).

Panoramica degli endpoint

Le sezioni seguenti descrivono in dettaglio gli endpoint API disponibili in MCG.

Configurazione delle metriche

• POST /api/v1/generate_metrics_config: crea un'istanza MetricsConfig dai dettagli della richiesta di configurazione delle metriche.
• POST /api/v1/get_file_descriptor_set: restituisce i descrittori di file per un determinato MetricsConfig per la decodifica dei report.
• POST /api/v1/validate_metrics_config: convalida il valore MetricsConfig e restituisce un elenco di eventuali errori di convalida.

Cataloghi di segnali per veicoli

• POST /api/v1/vs/: crea un nuovo catalogo di segnali del veicolo o aggiorna quello esistente.
• GET /api/v1/vs/: elenca tutti i metadati del catalogo dei segnali del veicolo.
• DELETE /api/v1/vs/{version}: elimina il catalogo dei segnali del veicolo specificato.

Stato del servizio

• GET /health: controlla l'integrità del servizio.

Tipi di contenuti Protobuf

Diversi endpoint API accettano o restituiscono dati nel formato buffer di protocollo (protobuf). Vengono utilizzati due tipi di contenuti:

• application/x-protobuf: Indica i dati protobuf nel formato binario. Questo formato è efficiente per la comunicazione da macchina a macchina, ma non è leggibile da persone.
• text/x-protobuf: indica i dati protobuf nel formato di testo, che è leggibile e utile per il debug o l'ispezione manuale.

Quando un endpoint supporta più formati protobuf per una richiesta o una risposta, utilizza l'intestazione Content-Type per specificare il formato dei dati della richiesta e l'intestazione Accept per specificare il formato selezionato dei dati della risposta. Ad esempio:

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

Chiama l'API

Gli esempi in questa pagina utilizzano curl per chiamare l'API REST e presuppongono che tu abbia impostato la variabile di ambiente SERVICE_URL in modo che faccia riferimento all'host in cui è stato eseguito il deployment di MCG. Quando viene eseguito localmente, questo valore è in genere http://localhost:8005.

Per scegliere come target un'istanza Cloud Run remota, imposta SERVICE_URL utilizzando gcloud. Poi, aggiungi un'intestazione di autorizzazione con un token di identità OpenID Connect (OIDC) al 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)"

Configurazione delle metriche

Questa sezione descrive gli endpoint per la generazione e la convalida delle configurazioni delle metriche.

POST /api/v1/generate_metrics_config

Crea un'istanza MetricsConfig dai dettagli della richiesta di configurazione delle metriche. Questo processo include la convalida e, se la generazione non va a buon fine a causa di violazioni dello schema, riferimenti non validi, dipendenze cicliche o altri problemi, l'API restituisce un elenco di dettagli degli errori.

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

Restituisce i descrittori di file per un determinato MetricsConfig per i report di decodifica.

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

Convalida il MetricsConfig fornito, restituendo un elenco di eventuali errori di convalida.

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

Cataloghi di segnali per veicoli

Questa sezione descrive gli endpoint per la gestione dei cataloghi di segnali del veicolo.

POST /api/v1/vs/

Crea un nuovo catalogo dei segnali del veicolo o aggiornane uno esistente.

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

Elenca tutti i metadati del catalogo dei segnali del veicolo.

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

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

DELETE /api/v1/vs/{version}

Elimina il catalogo dei segnali del veicolo specificato.

{"version": "string"}

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

Stato del servizio

Questa sezione descrive gli endpoint per il controllo dell'integrità del servizio.

GET /health

Controlla l'integrità del servizio.

curl "$SERVICE_URL/health"
      

Risposte di errore

Quando una chiamata API genera un errore (HTTP status 4xx o 5xx), il corpo della risposta contiene un oggetto di errore con la seguente struttura:

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