Referensi API

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

Ringkasan endpoint

Bagian berikut menjelaskan endpoint API yang tersedia di MCG.

Konfigurasi metrik

Katalog Sinyal Kendaraan

Status layanan

Jenis konten Protobuf

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

  • application/x-protobuf: Menunjukkan data protobuf dalam format kabel binernya. Format ini efisien untuk komunikasi mesin ke mesin, tetapi tidak dapat dibaca manusia.
  • text/x-protobuf: Menunjukkan data protobuf dalam format teksnya, yang dapat dibaca 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 bahwa Anda menetapkan variabel lingkungan SERVICE_URL untuk merujuk ke host tempat MCG di-deploy. Saat dijalankan secara lokal, ini biasanya http://localhost:8005.

Untuk menargetkan instance Cloud Run jarak jauh, tetapkan SERVICE_URL menggunakan gcloud:

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

Saat memanggil endpoint Cloud Run jarak jauh, tambahkan header otorisasi berikut ke perintah curl Anda:

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

Konfigurasi metrik

Bagian ini menjelaskan endpoint untuk membuat dan memvalidasi konfigurasi metrik.

POST /api/v2/generate_metrics_config

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

Detail endpoint
Parameter kueri ignore_validation: boolean
Opsional. Jika true, abaikan error validasi dan tampilkan MetricsConfig.
Isi permintaan Isi permintaan harus berisi detail permintaan konfigurasi metrik dalam format JSON.
Respons berhasil Isi respons berisi pesan MetricsConfig dalam format application/x-protobuf atau text/x-protobuf.
Header Metrics-Config-Size berisi ukuran konfigurasi dalam byte.
Contoh
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

Menampilkan deskriptor file untuk MetricsConfig tertentu guna mendekode laporan.

Detail endpoint
Isi permintaan Isi permintaan harus berisi pesan google.sdv.telemetry.MetricsConfig dalam format application/x-protobuf atau text/x-protobuf.
Respons berhasil Isi respons berisi pesan google.protobuf.FileDescriptorSet dalam format application/x-protobuf atau text/x-protobuf.
Contoh
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

Memvalidasi MetricsConfig yang diberikan, menampilkan daftar error validasi.

Detail endpoint
Parameter kueri return_config: boolean
Opsional. Jika true, tampilkan MetricsConfig setelah validasi berhasil.
Isi permintaan Isi permintaan harus berisi pesan google.sdv.telemetry.MetricsConfig dalam format application/x-protobuf atau text/x-protobuf.
Respons berhasil Isi respons berisi objek kosong (default) atau MetricsConfig (jika return_config adalah true).
Header Metrics-Config-Size berisi ukuran konfigurasi dalam byte.
Contoh
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"
      

Katalog Sinyal Kendaraan

Bagian ini menjelaskan endpoint untuk mengelola Katalog Sinyal Kendaraan.

POST /api/v2/vs/

Membuat Katalog Sinyal Kendaraan baru atau memperbarui yang sudah ada.

Detail endpoint
Isi permintaan Isi permintaan harus berisi objek JSON dengan string version dan FileDescriptorSet berenkode base64 untuk vehicle_signals.
{
  "version": "string",
  "vehicle_signals": "string"
}
Respons berhasil Jika berhasil, API akan menampilkan application/json dengan versi katalog yang ditambahkan atau diperbarui:
{"version": "string"}
Contoh Untuk mengetahui petunjuk tentang cara membuat FileDescriptorSet berenkode base64 untuk kolom vehicle_signals, lihat Katalog Sinyal Kendaraan.
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/

Mencantumkan semua metadata Vehicle Signal Catalog.

Detail endpoint
Respons berhasil Jika berhasil, API akan menampilkan application/json yang berisi daftar versi katalog:
{"versions": [{"version": "string"}]}
Contoh
curl "$SERVICE_URL/api/v2/vs/"
      

DELETE /api/v2/vs/{version}

Menghapus Vehicle Signal Catalog yang ditentukan.

Detail endpoint
Parameter jalur version: string
Wajib diisi. ID Katalog Sinyal Kendaraan yang akan dihapus, seperti yang diberikan di kolom version permintaan POST.
Respons berhasil Jika berhasil, API akan menampilkan application/json dengan versi katalog yang dihapus:
{"version": "string"}
Contoh
curl --request DELETE "$SERVICE_URL/api/v2/vs/v1.0"
      

Status layanan

Bagian ini menjelaskan endpoint untuk memeriksa kondisi layanan.

GET /health

Periksa kondisi layanan.

Detail endpoint
Respons berhasil Jika responsif, layanan akan menampilkan kode status 200 OK.
Contoh
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"
          }
        ]
      }
    ]
  }
}
Kolom error
code int32
Kode status HTTP (misalnya, 400, 404, atau 500).
status string
Kode status kanonis RPC Google (misalnya, INVALID_ARGUMENT, NOT_FOUND, atau INTERNAL).
message string
Pesan error yang ditampilkan kepada developer dalam bahasa Inggris.
details Array<object>
Array objek yang berisi detail error lebih lanjut, yang diidentifikasi oleh anggota @type-nya.