Referensi API

Halaman ini menyediakan dokumentasi referensi untuk endpoint Metrics Configuration Generator (MCG) API.

Ringkasan endpoint

Bagian berikut menjelaskan endpoint API yang tersedia di MCG.

Konfigurasi metrik

• POST /api/v1/generate_metrics_config: Membuat instance MetricsConfig dari detail permintaan konfigurasi metrik.
• POST /api/v1/get_file_descriptor_set: Menampilkan deskriptor file untuk MetricsConfig tertentu untuk mendekode laporan.
• POST /api/v1/validate_metrics_config: Memvalidasi MetricsConfig yang diteruskan, menampilkan daftar error validasi.

Katalog Sinyal Kendaraan

• POST /api/v1/vs/: Membuat Katalog Sinyal Kendaraan baru atau memperbarui Katalog Sinyal Kendaraan yang ada.
• GET /api/v1/vs/: Mencantumkan semua metadata Katalog Sinyal Kendaraan.
• DELETE /api/v1/vs/{version}: Menghapus Katalog Sinyal Kendaraan yang ditentukan.

Status layanan

• GET /health: Memeriksa kesehatan layanan.

Jenis konten Protobuf

Beberapa endpoint API menerima atau menampilkan data dalam format protocol buffer (protobuf). Dua jenis konten digunakan:

• application/x-protobuf: Menunjukkan data protobuf dalam format kabel biner. Format ini efisien untuk komunikasi antar-mesin, tetapi tidak dapat dibaca oleh manusia.
• text/x-protobuf: Menunjukkan data protobuf dalam format teks, yang dapat dibaca oleh manusia dan berguna untuk proses debug atau pemeriksaan manual.

Jika endpoint mendukung beberapa format protobuf untuk permintaan atau respons, gunakan header Content-Type untuk menentukan format data permintaan, dan header Accept untuk menentukan format data respons yang dipilih. Contoh:

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

Memanggil API

Contoh di halaman ini menggunakan curl untuk memanggil REST API dan mengasumsikan Anda menetapkan variabel lingkungan SERVICE_URL untuk merujuk ke host tempat MCG di-deploy. Saat dijalankan secara lokal, biasanya http://localhost:8005.

Untuk menargetkan instance Cloud Run jarak jauh, tetapkan SERVICE_URL menggunakan gcloud. Kemudian, tambahkan header otorisasi dengan token identitas OpenID Connect (OIDC) ke perintah curl Anda:

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

Konfigurasi metrik

Bagian ini menjelaskan endpoint untuk membuat dan memvalidasi konfigurasi metrik.

POST /api/v1/generate_metrics_config

Membuat instance MetricsConfig dari detail permintaan konfigurasi metrik. Proses ini mencakup validasi, dan jika pembuatan gagal karena pelanggaran skema, referensi tidak valid, dependensi siklik, atau masalah lainnya, API akan menampilkan daftar detail error.

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

Menampilkan deskriptor file untuk MetricsConfig tertentu untuk mendekode laporan.

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

Memvalidasi MetricsConfig yang diberikan, menampilkan daftar error validasi.

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

Katalog Sinyal Kendaraan

Bagian ini menjelaskan endpoint untuk mengelola Katalog Sinyal Kendaraan.

POST /api/v1/vs/

Membuat Katalog Sinyal Kendaraan baru atau memperbarui Katalog Sinyal Kendaraan yang ada.

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

Mencantumkan semua metadata Katalog Sinyal Kendaraan.

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

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

DELETE /api/v1/vs/{version}

Menghapus Katalog Sinyal Kendaraan yang ditentukan.

{"version": "string"}

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

Status layanan

Bagian ini menjelaskan endpoint untuk memeriksa kesehatan layanan.

GET /health

Memeriksa kesehatan layanan.

curl "$SERVICE_URL/health"
      

Respons error

Jika panggilan API menghasilkan error (HTTP status 4xx atau 5xx), isi respons akan berisi objek error dengan struktur berikut:

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