Araç Sinyali Katalogları

Metrik Yapılandırma Oluşturucu (MCG), sinyal adlarını kontrol ederek, ifadelerde tür kontrolü yaparak ve çıkış türlerini tahmin ederek metrik yapılandırmalarını doğrular. MCG'nin bu görevleri gerçekleştirebilmesi için araç sinyallerine yönelik protokol arabelleği (protobuf) mesaj tanımlarına erişmesi gerekir.

SDV'de araç sinyalleri ve hizmetleri, Araç Hizmet Arayüzü Tanım Dili (VSIDL) kullanılarak tanımlanır. VSIDL, mesajları belirtmek için protobuf dosyalarını kullanır ve bu protobuf dosyaları bir sinyal kataloğunun temelini oluşturur.

Sinyal tanımlarını MCG'de kullanılabilir hale getirmek için bu VSIDL protobuf dosyalarını bir protobuf FileDescriptorSet içinde paketlemeniz ve MCG hizmetine yüklemeniz gerekir. MCG, yüklenen ve sürümlendirilen bu tanım kümeleri için Araç Sinyal Kataloğu terimini kullanır (Araç Sinyal Kataloğu, VSIDL kataloğunuzdaki proto mesaj tanımlarının derlenmiş ve yüklenmiş biçimidir).

Araç Sinyal Kataloğu nedir?

Araç Sinyal Kataloğu, MCG'ye doğrulama için sinyal tanımları sağlar. Bu tanımlar, protobuf FileDescriptorSet olarak paketlenir.

MCG'de kataloglar, yükleme sırasında atadığınız bir sürüm dizesiyle tanımlanır. Bu sayede birden fazla farklı sinyal tanımı grubunu yönetebilirsiniz. Örneğin, yazılım sürümleri (v1.0, v1.1, v2.0) veya farklı araç modelleri ya da donanım yapılandırmaları (suv-my2025, sedan-my2025) için farklı katalog sürümleri kullanabilirsiniz. Her metrik yapılandırması, belirli bir kataloğa referans vermek için vs_version alanını kullanır. Bu alan, veri kaynağı olarak kullanılabilen sinyalleri tanımlar ve tür çıkarımı ile doğrulama için sinyal tanımları sağlar.

FileDescriptorSet örneği oluşturma

Mesajları ve RPC hizmetlerini tanımlama bölümünde açıklandığı gibi, araç sinyalleri protobuf dosyalarında protobuf mesajları olarak tanımlanır. Bir SDV projesinde yer alıyorsanız projenizin VSIDL kataloğundaki protobuf dosyalarını kullanarak FileDescriptorSet örneği oluşturun.

MCG için katalog oluşturmak istiyorsanız protobuf dosyalarınızı protoc kullanarak bir FileDescriptorSet ikili program dosyası halinde paketleyin. Tüm protobuf dosyalarınız tek bir klasördeyse vehicle_signals.pb dosyasını oluşturmak için aşağıdaki komutu çalıştırın:

protoc --include_imports --descriptor_set_out=vehicle_signals.pb path/to/your/protos/*.proto

Katalog yükleme ve yönetme

Sinyal tanım kümenizi katalog olarak yüklediğinizde, metrik yapılandırma isteklerinde sürüm adına göre referans verebilirsiniz.

Katalog sürümü ekleme veya güncelleme

vehicle_signals.pb katalog dosyasını oluşturduktan sonra /api/v2/vs/ altındaki MCG API uç noktalarını kullanarak dosyayı yükleyip yönetebilirsiniz. Katalog ekleme veya güncelleme uç noktası olan POST /api/v2/vs/, FileDescriptorSet değerinin JSON yükünde base64 kodlu dize olarak iletilmesini gerektirir.

API kullanımı için vehicle_signals.pb kodlamasını yapmak üzere base64 komutunu kullanın. -w 0 işareti, kodlanmış dizenin tek bir satırda görünmesi için satır sarmayı devre dışı bırakır:

VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

vehicle_signals.pb öğesini yeni bir sürüm (ör. v1.0) olarak yüklemek veya mevcut bir sürümü güncellemek için base64 ile kodlanmış içeriği içeren bir POST isteğini benzersiz bir sürüm adıyla /api/v2/vs/ uç noktasına gönderin.

İstek gövdesi, version dizesini ve base64 kodlu vehicle_signals dizesini içeren bir JSON nesnesi olmalıdır:

{
  "version": "v1.0",
  "vehicle_signals": "Q2lSb1pYB3jCRkRt..."
}

Aşağıdaki örnekte, curl kullanılarak vehicle_signals.pb dosyasının v1.0 sürümü olarak nasıl yükleneceği gösterilmektedir. Örnekte, JSON yükünü oluşturmak için printf kullanılır ve bu yük, curl komutuna yönlendirilir. Böylece, çok uzun tek satırlı bir base64 dizesi içeren bir JSON dosyası oluşturma ihtiyacı ortadan kalkar:

# 1. Encode the FileDescriptorSet to a Base64 string
VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

# 2. Define catalog version and build JSON payload
VERSION="v1.0"
JSON_PAYLOAD=$(jq -n --arg v "$VERSION" --arg d "$VEHICLE_SIGNALS_BASE64" \
  '{version: $v, vehicle_signals: $d}')

# 3. POST the data to the API endpoint
echo "$JSON_PAYLOAD" | curl -H "Content-Type: application/json" --data-binary @- "$SERVICE_URL/api/v2/vs/"

Sürümleri listeleme ve silme

Mevcut tüm katalog sürümlerini listeleyebilir veya belirli bir sürümü silebilirsiniz:

• Sürümleri listeleme: Yüklenen tüm katalog sürümlerinin tanımlayıcılarının listesini görmek için /api/v2/vs/ adresine bir GET isteği gönderin. GET /api/v2/vs/ bölümüne bakın.

• Sürüm silme: Bir kataloğu kaldırmak için /api/v2/vs/{version} adresine DELETE isteği gönderin. Burada {version}, katalog yüklenirken sağlanan tanımlayıcıdır (örneğin, v1.0). DELETE /api/v2/vs/{version} bölümüne bakın.

Tüm uç noktalarla ilgili ayrıntılı bilgi için API referansını inceleyin.

Metrik yapılandırmalarında katalog kullanma

Yüklendikten sonra, vs_version alanını kullanarak metrik yapılandırmalarında bir katalog sürümüne referans verin:

{ "vs_version": "v1.0", ... }

Bu JSON nesnesi /api/v2/generate_metrics_config veya /api/v2/validate_metrics_config uç noktalarına gönderildiğinde MCG, doğrulama ve tür çıkarımı yapmak için v1.0 kataloğundaki sinyal tanımlarını kullanır.