Dokumentacja API

Na tej stronie znajdziesz dokumentację referencyjną punktów końcowych interfejsu Metrics Configuration Generator (MCG) API.

Przegląd 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/v2/generate_metrics_config: utwórz instancję MetricsConfig na podstawie szczegółów żądania konfiguracji danych.
• POST /api/v2/get_file_descriptor_set: zwraca deskryptory plików dla danego MetricsConfig na potrzeby dekodowania raportów.
• POST /api/v2/validate_metrics_config: sprawdza przekazany obiekt MetricsConfig i zwraca listę błędów weryfikacji.

Katalogi sygnałów pojazdów

• POST /api/v2/vs/: utwórz nowy lub zaktualizuj istniejący katalog sygnałów pojazdu.
• GET /api/v2/vs/: wyświetla listę wszystkich metadanych Vehicle Signal Catalog.
• DELETE /api/v2/vs/{version}: usuń 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 wire. Ten format jest wydajny w przypadku komunikacji między maszynami, ale nie jest zrozumiały dla człowieka.
• text/x-protobuf: wskazuje dane protobuf w formacie tekstowym, który jest zrozumiały 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, i 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 REST API i zakładają, że zmienna środowiskowa SERVICE_URL odnosi się do hosta, na którym wdrożono MCG. W przypadku uruchamiania lokalnego jest to zwykle http://localhost:8005.

Aby kierować na zdalną instancję Cloud Run, ustaw SERVICE_URL za pomocą gcloud:

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

Podczas wywoływania zdalnych punktów końcowych Cloud Run do poleceń curl dołącz ten nagłówek autoryzacji:

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

Konfiguracja wskaźników

W tej sekcji opisujemy punkty końcowe do generowania i weryfikowania konfiguracji danych.

POST /api/v2/generate_metrics_config

Utwórz instancję MetricsConfig na podstawie szczegółów żądania konfiguracji wskaźników. Ten proces obejmuje weryfikację. Jeśli generowanie nie powiedzie się z powodu naruszenia schematu, nieprawidłowych odwołań, zależności cyklicznych lub innych problemów, interfejs API zwróci 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/v2/generate_metrics_config"
      

POST /api/v2/get_file_descriptor_set

Zwróć deskryptory plików dla danego MetricsConfig, aby dekodować raporty.

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

Sprawdź podany obiekt MetricsConfig i zwróć listę błędów weryfikacji.

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"
      

Katalogi sygnałów pojazdów

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

POST /api/v2/vs/

Utwórz nowy lub zaktualizuj istniejący katalog sygnałów pojazdu.

{
  "version": "string",
  "vehicle_signals": "string"
}

{"version": "string"}

curl -H "Content-Type: application/json" \
  --data-binary @- "$SERVICE_URL/api/v2/vs/" << EOF
{
  "version": "v1.0",
  "vehicle_signals": "VEHICLE_SIGNALS_BASE64"
}
EOF
      

thought GET /api/v2/vs/

Wyświetl listę wszystkich metadanych katalogu sygnałów pojazdu.

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

curl "$SERVICE_URL/api/v2/vs/"
      

thought DELETE /api/v2/vs/{version}

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

{"version": "string"}

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

Stan usługi

W tej sekcji opisano punkty końcowe do sprawdzania Service Health.

GET /health

Sprawdź stan usługi.

curl "$SERVICE_URL/health"
      

Odpowiedzi na błędy

Gdy wywołanie interfejsu API powoduje błąd (HTTP status 4xx lub 5xx), treść odpowiedzi zawiera obiekt błędu o następującej 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"
          }
        ]
      }
    ]
  }
}