Dokumentacja API

Ta strona zawiera dokumentację referencyjną punktów końcowych interfejsu API generatora konfiguracji wskaźników (MCG).

Omówienie punktów końcowych

W sekcjach poniżej znajdziesz szczegółowe informacje o punktach końcowych interfejsu API dostępnych w MCG.

Konfiguracja wskaźników

• POST /api/v1/generate_metrics_config: utwórz instancję MetricsConfig na podstawie szczegółów żądania konfiguracji danych.
• POST /api/v1/get_file_descriptor_set: zwraca deskryptory plików dla danego MetricsConfig na potrzeby dekodowania raportów.
• POST /api/v1/validate_metrics_config: sprawdza przekazane MetricsConfig i zwraca listę błędów weryfikacji.

Katalogi sygnałów pojazdów

• POST /api/v1/vs/: tworzenie nowego lub aktualizowanie istniejącego katalogu sygnałów pojazdu.
• GET /api/v1/vs/: wyświetl wszystkie metadane katalogu sygnałów pojazdu.
• DELETE /api/v1/vs/{version}: usuwa określony katalog sygnałów pojazdu.

Stan usługi

• GET /health: sprawdź stan usługi.

Typy treści Protobuf

Kilka punktów końcowych interfejsu API akceptuje lub zwraca dane w formacie bufora protokołu (protobuf). Używane są 2 typy treści:

• application/x-protobuf: wskazuje dane protobuf w binarnym formacie przesyłania. Ten format jest wydajny w komunikacji między urządzeniami, ale nie jest czytelny dla człowieka.
• text/x-protobuf: wskazuje dane protobuf w formacie tekstowym, który jest czytelny dla człowieka i przydatny do debugowania lub ręcznego sprawdzania.

Jeśli punkt końcowy obsługuje wiele formatów protobuf dla żądania lub odpowiedzi, użyj nagłówka Content-Type, aby określić format danych żądania, oraz nagłówka Accept, aby określić wybrany format danych odpowiedzi. Przykład:

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

Wywoływanie interfejsu API

Przykłady na tej stronie używają curl do wywoływania interfejsu API REST i zakładają, że zmienna środowiskowa SERVICE_URL została ustawiona tak, aby odwoływać się do hosta, na którym wdrożono MCG. W przypadku uruchamiania lokalnego jest to zwykle http://localhost:8005.

Aby kierować żądania do zdalnej instancji Cloud Run, ustaw SERVICE_URL za pomocą gcloud. Następnie do polecenia curl dołącz nagłówek autoryzacji z tokenem tożsamości OpenID Connect (OIDC):

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

Konfiguracja wskaźników

W tej sekcji opisujemy punkty końcowe służące do generowania i weryfikowania konfiguracji danych.

POST /api/v1/generate_metrics_config

Utwórz MetricsConfig na podstawie szczegółów żądania konfiguracji wskaźników. Ten proces obejmuje weryfikację. Jeśli generowanie się nie powiedzie z powodu naruszenia schematu, nieprawidłowych odwołań, zależności cyklicznych lub innych problemów, interfejs API zwraca listę szczegółów błędu.

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

Zwraca deskryptory plików dla danego MetricsConfig na potrzeby dekodowania raportów.

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

Sprawdza podany MetricsConfig i zwraca listę błędów weryfikacji.

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

Katalogi sygnałów pojazdów

W tej sekcji opisujemy punkty końcowe do zarządzania katalogami sygnałów pojazdów.

POST /api/v1/vs/

Tworzenie nowego lub aktualizowanie istniejącego katalogu sygnałów pojazdu.

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

Wyświetl wszystkie metadane katalogu sygnałów pojazdu.

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

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

DELETE /api/v1/vs/{version}

Usuń określony katalog sygnałów pojazdu.

{"version": "string"}

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

Stan usługi

Ta sekcja zawiera opis punktów końcowych do sprawdzania stanu usługi.

GET /health

Sprawdź stan usługi.

curl "$SERVICE_URL/health"
      

Odpowiedzi na błędy

Gdy wywołanie interfejsu API spowoduje błąd (HTTP status 4xx lub 5xx), treść odpowiedzi zawiera obiekt błędu o tej strukturze:

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