API Referansı

Bu sayfada, Metrics Configuration Generator (MCG) API uç noktalarıyla ilgili referans belgeleri sağlanmaktadır.

Uç noktalara genel bakış

Aşağıdaki bölümlerde, MCG'de kullanılabilen API uç noktaları ayrıntılı olarak açıklanmaktadır.

Metrik yapılandırması

• POST /api/v1/generate_metrics_config: Metrik yapılandırma isteği ayrıntılarından MetricsConfig örneği oluşturun.
• POST /api/v1/get_file_descriptor_set: Raporların kodunu çözmek için belirli bir MetricsConfig ile ilgili dosya tanımlayıcılarını döndürür.
• POST /api/v1/validate_metrics_config: Geçirilenleri doğrulayın MetricsConfig ve doğrulama hatalarının listesini döndürün.

Araç Sinyali Katalogları

• POST /api/v1/vs/: Yeni araç sinyali kataloğu oluşturun veya mevcut olanı güncelleyin.
• GET /api/v1/vs/: Tüm Araç Sinyali Kataloğu meta verilerini listeleyin.
• DELETE /api/v1/vs/{version}: Belirtilen Araç Sinyali Kataloğu'nu siler.

Hizmet durumu

• GET /health: Hizmetin durumunu kontrol edin.

Protobuf içerik türleri

Çeşitli API uç noktaları, protokol arabelleği (protobuf) biçimindeki verileri kabul eder veya döndürür. İki içerik türü kullanılır:

• application/x-protobuf: İkili kablo biçimindeki protobuf verilerini gösterir. Bu biçim, makine-makine iletişimi için verimlidir ancak insanlar tarafından okunamaz.
• text/x-protobuf: Metin biçimindeki protobuf verilerini gösterir. Bu veriler, insanlar tarafından okunabilir ve hata ayıklama veya manuel inceleme için yararlıdır.

Bir uç nokta istek veya yanıt için birden fazla protobuf biçimini desteklediğinde, istek verilerinin biçimini belirtmek için Content-Type üstbilgisini, yanıt verilerinin seçilen biçimini belirtmek için ise Accept üstbilgisini kullanın. Örneğin:

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

API'yi çağırma

Bu sayfadaki örneklerde REST API'yi çağırmak için curl kullanılır ve SERVICE_URL ortam değişkenini, MCG'nin dağıtıldığı ana makineye referans verecek şekilde ayarladığınız varsayılır. Yerel olarak çalıştırıldığında bu genellikle http://localhost:8005 olur.

Uzak bir Cloud Run örneğini hedeflemek için SERVICE_URL değerini gcloud kullanarak ayarlayın. Ardından, curl komutunuza OpenID Connect (OIDC) kimlik jetonu içeren bir yetkilendirme başlığı ekleyin:

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

Metrik yapılandırması

Bu bölümde, metrik yapılandırmalarını oluşturma ve doğrulama uç noktaları açıklanmaktadır.

POST /api/v1/generate_metrics_config

Metrik yapılandırma isteği ayrıntılarından MetricsConfig örneği oluşturun. Bu süreçte doğrulama da yer alır. Şema ihlalleri, geçersiz referanslar, döngüsel bağımlılıklar veya başka sorunlar nedeniyle oluşturma işlemi başarısız olursa API, hata ayrıntılarının listesini döndürür.

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

Raporların kodunu çözmek için belirli bir MetricsConfig ile ilgili dosya tanımlayıcılarını döndürür.

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

Sağlanan MetricsConfig öğesini doğrulayarak doğrulama hatalarının listesini döndürür.

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

Araç Sinyali Katalogları

Bu bölümde, Araç Sinyali Katalogları'nı yönetmeye yönelik uç noktalar açıklanmaktadır.

POST /api/v1/vs/

Yeni araç sinyali kataloğu oluşturun veya mevcut olanları güncelleyin.

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

Tüm Araç Sinyali Kataloğu meta verilerini listeleyin.

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

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

DELETE /api/v1/vs/{version}

Belirtilen Araç Sinyali Kataloğu'nu silin.

{"version": "string"}

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

Hizmet durumu

Bu bölümde, hizmet durumunu kontrol etmeye yönelik uç noktalar açıklanmaktadır.

GET /health

Hizmetin durumunu kontrol edin.

curl "$SERVICE_URL/health"
      

Hata yanıtları

Bir API çağrısı hatayla (HTTP status 4xx veya 5xx) sonuçlandığında yanıt metninde aşağıdaki yapıya sahip bir hata nesnesi bulunur:

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