API-Referenz

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

Übersicht über Endpunkte

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

Messwertkonfiguration

• POST /api/v1/generate_metrics_config: Erstellt eine MetricsConfig-Instanz anhand der Details der Anfrage zur Messwertkonfiguration.
• POST /api/v1/get_file_descriptor_set: Gibt Dateideskriptoren für einen bestimmten MetricsConfig zum Decodieren von Berichten zurück.
• POST /api/v1/validate_metrics_config: Validiert die übergebenen MetricsConfig und gibt eine Liste aller Validierungsfehler zurück.

Fahrzeugsignalkataloge

• POST /api/v1/vs/: Erstellen Sie einen neuen oder aktualisieren Sie einen vorhandenen Fahrzeugsignal-Katalog.
• GET /api/v1/vs/: Alle Metadaten des Vehicle Signal Catalog auflisten.
• DELETE /api/v1/vs/{version}: Löscht den angegebenen Fahrzeugsignal-Katalog.

Dienststatus

• GET /health: Den Zustand des Dienstes prüfen.

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 effizient für die Kommunikation zwischen Maschinen, aber nicht für Menschen lesbar.
• text/x-protobuf: Gibt Protobuf-Daten im Textformat an, das für Menschen lesbar und für das Debugging oder die manuelle Überprüfung nützlich ist.

Wenn ein Endpunkt mehrere Protobuf-Formate für eine Anfrage oder Antwort unterstützt, verwenden Sie den Content-Type-Header, um das Format der Anfragedaten anzugeben, und den Accept-Header, 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 wird. Bei der lokalen Ausführung ist dies in der Regel http://localhost:8005.

Wenn Sie eine Remote-Cloud Run-Instanz als Ziel verwenden möchten, legen Sie SERVICE_URL mit gcloud fest. Hängen Sie dann einen Autorisierungsheader mit einem OpenID Connect-Identitätstoken (OIDC) an den curl-Befehl an:

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)"

Messwertkonfiguration

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

POST /api/v1/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 Schemas, ungültigen Referenzen, zyklischen Abhängigkeiten oder anderen Problemen fehlschlägt, gibt die API eine Liste mit Fehlerdetails zurück.

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

Gibt Dateideskriptoren für eine bestimmte MetricsConfig zum Decodieren von Berichten zurück.

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

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

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

Fahrzeugsignalkataloge

In diesem Abschnitt werden Endpunkte zum Verwalten von Fahrzeugsignalkatalogen beschrieben.

POST /api/v1/vs/

Erstellen Sie einen neuen oder aktualisieren Sie einen vorhandenen Fahrzeugsignalkatalog.

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

Alle Metadaten des Vehicle Signal Catalog auflisten.

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

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

DELETE /api/v1/vs/{version}

Löscht den angegebenen Fahrzeugsignalkatalog.

{"version": "string"}

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

Dienststatus

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

GET /health

Prüfen Sie den Status des Dienstes.

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