API referansı

Bu sayfada, Metrics Configuration Generator (MCG) API uç noktalarıyla ilgili referans belgeleri yer almaktadı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/v2/generate_metrics_config: Metrik yapılandırma isteği ayrıntılarından bir MetricsConfig örneği oluşturun.
• POST /api/v2/get_file_descriptor_set: Raporların kodunu çözmek için belirli bir MetricsConfig ile ilgili dosya tanımlayıcıları döndürür.
• POST /api/v2/validate_metrics_config: Geçirilen MetricsConfig öğesini doğrulayarak doğrulama hatalarının listesini döndürür.

Araç Sinyali Katalogları

• POST /api/v2/vs/: Yeni bir Araç Sinyali Kataloğu oluşturun veya mevcut bir kataloğu güncelleyin.
• GET /api/v2/vs/: Tüm Araç Sinyal Kataloğu meta verilerini listeler.
• DELETE /api/v2/vs/{version}: Belirtilen araç sinyali kataloğunu siler.

Hizmet durumu

• GET /health: Hizmetin durumunu kontrol edin.

Protobuf içerik türleri

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

• application/x-protobuf: Protobuf verilerini ikili kablo biçiminde gösterir. Bu biçim, makineler arası iletişim için verimlidir ancak insanlar tarafından okunamaz.
• text/x-protobuf: Protobuf verilerini metin biçiminde gösterir. Bu biçim, insanlar tarafından okunabilir ve hata ayıklama veya manuel inceleme için kullanışlı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 başlığını, yanıt verilerinin seçilen biçimini belirtmek için ise Accept başlığını 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 MCG'nin dağıtıldığı ana makineye başvurmak için SERVICE_URL ortam değişkenini 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 gcloud kullanarak SERVICE_URL değerini ayarlayın:

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

Uzak Cloud Run uç noktalarını çağırırken curl komutlarınıza aşağıdaki yetkilendirme başlığını ekleyin:

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

Metrik yapılandırması

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

POST /api/v2/generate_metrics_config

Metrik yapılandırma isteği ayrıntılarından bir MetricsConfig örneği oluşturun. Bu işlem doğrulama adımını içerir. Şema ihlalleri, geçersiz referanslar, döngüsel bağımlılıklar veya diğer 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/v2/generate_metrics_config"
      

POST /api/v2/get_file_descriptor_set

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

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

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

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"
      

Araç Sinyali Katalogları

Bu bölümde, Araç Sinyal Kataloglarını yönetmek için kullanılan uç noktalar açıklanmaktadır.

POST /api/v2/vs/

Yeni bir Araç Sinyal Kataloğu oluşturun veya mevcut kataloğu güncelleyin.

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

GET /api/v2/vs/

Tüm Araç Sinyal Kataloğu meta verilerini listeler.

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

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

DELETE /api/v2/vs/{version}

Belirtilen araç sinyal kataloğunu siler.

{"version": "string"}

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

Hizmet durumu

Bu bölümde, hizmet durumunu kontrol etmek için kullanılan 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 gövdesi, aşağıdaki yapıya sahip bir hata nesnesi içerir:

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