API-Referenz

Auf dieser Seite finden Sie die Referenzdokumentation für die API-Endpunkte des Metrics Configuration Generator (MCG).

Endpunkte – Übersicht

In den folgenden Abschnitten werden die in MCG verfügbaren API-Endpunkte beschrieben.

Messwertkonfiguration

Kataloge für Fahrzeugsignale

Dienststatus

Protobuf-Inhaltstypen

Mehrere API-Endpunkte akzeptieren oder geben Daten im Protokollzwischenspeicherformat (protobuf) zurück. Es werden zwei Inhaltstypen verwendet:

  • application/x-protobuf: Gibt Protobuf-Daten im binären Wire-Format an. Dieses Format ist für die Kommunikation zwischen Maschinen effizient, aber nicht menschenlesbar.
  • text/x-protobuf: Gibt Protobuf-Daten im Textformat an, das menschenlesbar und nützlich für die Fehlerbehebung oder manuelle Prüfung ist.

Wenn ein Endpunkt mehrere Protobuf-Formate für eine Anfrage oder Antwort unterstützt, verwenden Sie den Header Content-Type, um das Format der Anfragedaten anzugeben, und den Header Accept, um das ausgewählte Format der Antwortdaten anzugeben. Beispiel:

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

API aufrufen

In den Beispielen auf dieser Seite wird curl zum Aufrufen der REST API verwendet. Außerdem wird davon ausgegangen, dass Sie die Umgebungsvariable SERVICE_URL so festgelegt haben, dass sie auf den Host verweist, auf dem MCG bereitgestellt ist. Bei lokaler Ausführung ist dies normalerweise http://localhost:8005.

Wenn Sie eine Remote-Cloud Run-Instanz als Ziel verwenden möchten, legen Sie SERVICE_URL mit gcloud fest:

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

Wenn Sie Remote-Cloud Run-Endpunkte aufrufen, hängen Sie den folgenden Autorisierungsheader an Ihre curl-Befehle an:

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

Messwertkonfiguration

In diesem Abschnitt werden Endpunkte zum Generieren und Validieren von Messwertkonfigurationen beschrieben.

POST /api/v2/generate_metrics_config

Erstellen Sie eine MetricsConfig-Instanz aus den Details der Anfrage zur Messwertkonfiguration. Dieser Prozess umfasst die Validierung. Wenn die Generierung aufgrund von Schemaverletzungen, ungültigen Verweisen, zyklischen Abhängigkeiten oder anderen Problemen fehlschlägt, gibt die API eine Liste mit Fehlerdetails zurück.

Endpunktdetails
Suchparameter ignore_validation: boolean
Optional. Wenn true, werden Validierungsfehler ignoriert und MetricsConfig wird zurückgegeben.
Anfragetext Der Anfragetext muss Details zur Anfrage für die Messwertkonfiguration im JSON-Format enthalten.
Erfolgreiche Antwort Der Antworttext enthält eine MetricsConfig-Nachricht im Format application/x-protobuf oder text/x-protobuf.
Der Header Metrics-Config-Size enthält die Konfigurationsgröße in Byte.
Beispiel
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

Gibt Dateideskriptoren für einen bestimmten MetricsConfig zum Decodieren von Berichten zurück.

Endpunktdetails
Anfragetext Der Anfragetext muss eine google.sdv.telemetry.MetricsConfig-Nachricht im Format application/x-protobuf oder text/x-protobuf enthalten.
Erfolgreiche Antwort Der Antworttext enthält eine google.protobuf.FileDescriptorSet-Nachricht im Format application/x-protobuf oder text/x-protobuf.
Beispiel
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

Validiert die angegebene MetricsConfig und gibt eine Liste aller Validierungsfehler zurück.

Endpunktdetails
Suchparameter return_config: boolean
Optional. Wenn true, wird nach erfolgreicher Validierung MetricsConfig zurückgegeben.
Anfragetext Der Anfragetext muss eine google.sdv.telemetry.MetricsConfig-Nachricht im Format application/x-protobuf oder text/x-protobuf enthalten.
Erfolgreiche Antwort Der Antworttext enthält ein leeres Objekt (Standard) oder MetricsConfig (wenn return_config den Wert true hat).
Der Metrics-Config-Size-Header enthält die Konfigurationsgröße in Byte.
Beispiel
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"
      

Kataloge für Fahrzeugsignale

In diesem Abschnitt werden Endpunkte zum Verwalten von Fahrzeugsignalkatalogen beschrieben.

POST /api/v2/vs/

Erstellen Sie einen neuen Fahrzeugsignalkatalog oder aktualisieren Sie einen vorhandenen.

Endpunktdetails
Anfragetext Der Anfragetext muss ein JSON-Objekt mit einem version-String und einem base64-codierten FileDescriptorSet für vehicle_signals enthalten.
{
  "version": "string",
  "vehicle_signals": "string"
}
Erfolgreiche Antwort Wenn der Vorgang erfolgreich ist, gibt die API application/json mit der Version des Katalogs zurück, der hinzugefügt oder aktualisiert wurde:
{"version": "string"}
Beispiel Eine Anleitung zum Generieren des base64-codierten FileDescriptorSet für das Feld vehicle_signals finden Sie unter Vehicle Signal Catalogs.
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/

Alle Metadaten des Vehicle Signal Catalog auflisten.

Endpunktdetails
Erfolgreiche Antwort Wenn der Vorgang erfolgreich war, gibt die API application/json mit einer Liste von Katalogversionen zurück:
{"versions": [{"version": "string"}]}
Beispiel
curl "$SERVICE_URL/api/v2/vs/"
      

DELETE /api/v2/vs/{version}

Löscht den angegebenen Fahrzeugsignalkatalog.

Endpunktdetails
Pfadparameter version: string
Erforderlich. Die Kennung des zu löschenden Fahrzeugsignalkatalogs, wie im Feld version der POST-Anfrage angegeben.
Erfolgreiche Antwort Bei Erfolg gibt die API application/json mit der Version des gelöschten Katalogs zurück:
{"version": "string"}
Beispiel
curl --request DELETE "$SERVICE_URL/api/v2/vs/v1.0"
      

Dienststatus

In diesem Abschnitt werden Endpunkte zum Prüfen des Dienststatus beschrieben.

GET /health

Prüfen Sie den Status des Dienstes.

Endpunktdetails
Erfolgreiche Antwort Wenn der Dienst fehlerfrei ist, gibt er den Statuscode 200 OK zurück.
Beispiel
curl "$SERVICE_URL/health"
      

Fehlerantworten

Wenn ein API-Aufruf zu einem Fehler (HTTP status 4xx oder 5xx) führt, enthält der Antworttext ein Fehlerobjekt mit der folgenden Struktur:

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Request validation failed",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "fieldName",
            "description": "error description"
          }
        ]
      }
    ]
  }
}
Fehlerfelder
code int32
Der HTTP-Statuscode (z. B. 400, 404 oder 500).
status string
Der kanonische Google-RPC-Statuscode (z. B. INVALID_ARGUMENT, NOT_FOUND oder INTERNAL).
message string
Eine an Entwickler gerichtete Fehlermeldung auf Englisch.
details Array<object>
Ein Array von Objekten, die weitere Fehlerdetails enthalten, die durch ihr @type-Mitglied identifiziert werden.