قوائم إشارات المركبات

تتحقّق أداة Metrics Configuration Generator (MCG) من صحة إعدادات المقاييس من خلال التحقّق من أسماء الإشارات وإجراء عمليات التحقّق من النوع على التعبيرات واستنتاج أنواع النتائج. يحتاج MCG إلى الوصول إلى تعريفات رسائل Protocol Buffers (protobuf) لإشارات المركبة لتنفيذ هذه المهام.

في SDV، يتم تحديد إشارات المركبات وخدماتها باستخدام لغة تعريف واجهة خدمة المركبات (VSIDL). تستخدم VSIDL ملفات protobuf لتحديد الرسائل، وتشكّل ملفات protobuf هذه أساس كتالوج الإشارات.

لإتاحة تعريفات الإشارات لخدمة MCG، يجب تجميع ملفات VSIDL protobuf هذه في ملف protobuf FileDescriptorSet وتحميلها إلى خدمة MCG. يستخدم MCG مصطلح كتالوج إشارات المركبات لمجموعات التعريفات التي تم تحميلها وإصدارها (ما يجعل كتالوج إشارات المركبات هو النموذج المجمّع والمحمّل لتعريفات رسائل proto في كتالوج VSIDL).

ما هو Vehicle Signal Catalog؟

يوفّر كتالوج إشارات المركبات لخدمة MCG تعريفات الإشارات للتحقّق من صحتها، ويتم تجميعها كملف protobuf FileDescriptorSet.

في MCG، يتم تحديد الكتالوجات من خلال سلسلة إصدارات يتم تعيينها أثناء التحميل، ما يتيح لك إدارة مجموعات متعددة ومختلفة من تعريفات الإشارات. على سبيل المثال، يمكنك الاحتفاظ بإصدارات مختلفة من الكتالوج لإصدارات البرامج (v1.0 وv1.1 وv2.0) أو لطُرز مختلفة من المركبات أو إعدادات الأجهزة (suv-my2025 وsedan-my2025). يستخدم كل إعداد للمقاييس الحقل vs_version للإشارة إلى كتالوج معيّن يحدّد الإشارات المتاحة كمصادر بيانات ويوفّر تعريفات الإشارات لاستنتاج النوع والتحقّق من صحته.

إنشاء مثيل من FileDescriptorSet

كما هو موضّح في مقالة تحديد الرسائل وخدمات RPC، يتم تحديد إشارات المركبة كرسائل protobuf في ملفات protobuf. إذا كنت تعمل على مشروع SDV، استخدِم ملفات protobuf من كتالوج VSIDL الخاص بمشروعك لإنشاء مثيل من FileDescriptorSet.

لإنشاء كتالوج لـ MCG، عليك تجميع ملفات protobuf في ملف ثنائي FileDescriptorSet باستخدام protoc. إذا كانت جميع ملفات protobuf في مجلد واحد، نفِّذ الأمر التالي لإنشاء vehicle_signals.pb:

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

تحميل الكتالوجات وإدارتها

يتيح لك تحميل مجموعة تعريف الإشارات ككتالوج الإشارة إليها حسب اسم الإصدار في طلبات ضبط المقاييس.

إضافة إصدار من الكتالوج أو تعديله

بعد إنشاء ملف كتالوج vehicle_signals.pb، يمكنك تحميله وإدارته باستخدام نقاط نهاية واجهة برمجة التطبيقات MCG ضمن /api/v1/vs/. تتطلّب نقطة النهاية لإضافة كتالوج أو تعديله، POST /api/v1/vs/، تمرير FileDescriptorSet كسلسلة مرمّزة بترميز base64 في حمولة JSON.

لترميز vehicle_signals.pb لاستخدام واجهة برمجة التطبيقات، استخدِم الأمر base64. تعمل العلامة -w 0 على إيقاف التفاف السطر بحيث تظهر السلسلة المرمّزة في سطر واحد:

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

لتحميل vehicle_signals.pb كإصدار جديد (على سبيل المثال، v1.0) أو لتعديل إصدار حالي، أرسِل طلب POST يتضمّن المحتوى المرمّز بترميز base64 إلى نقطة النهاية /api/v1/vs/ مع اسم إصدار فريد.

يجب أن يكون نص الطلب عبارة عن عنصر JSON يحتوي على سلسلة version وسلسلة vehicle_signals بترميز base64:

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

يوضّح المثال التالي كيفية تحميل vehicle_signals.pb كإصدار v1.0 باستخدام curl. يستخدم المثال printf لإنشاء حمولة JSON وتوجيهها إلى curl، ما يجنّب الحاجة إلى إنشاء ملف JSON يحتوي على سلسلة base64 طويلة جدًا من سطر واحد:

# 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/v1/vs/"

عرض النُسخ وحذفها

يمكنك إدراج جميع إصدارات الكتالوج المتاحة أو حذف إصدار معيّن:

• عرض قائمة بالإصدارات: للاطّلاع على قائمة بمعرّفات جميع إصدارات الكتالوج التي تم تحميلها، أرسِل طلب GET إلى /api/v1/vs/. يُرجى الاطّلاع على GET /api/v1/vs/‎.

• حذف إصدار: لإزالة كتالوج، أرسِل طلب DELETE إلى /api/v1/vs/{version}، حيث يمثّل {version} المعرّف الذي تم تقديمه عند تحميل الكتالوج (على سبيل المثال، v1.0). راجِع DELETE /api/v1/vs/{version}.

للحصول على تفاصيل كاملة حول جميع نقاط النهاية، يُرجى الاطّلاع على مرجع واجهة برمجة التطبيقات.

استخدام كتالوج في إعدادات المقاييس

عند تحميل إصدار الكتالوج، يمكنك الإشارة إليه في إعدادات المقاييس باستخدام الحقل vs_version:

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

عند إرسال عنصر JSON هذا إلى نقاط النهاية /api/v1/generate_metrics_config أو /api/v1/validate_metrics_config، تستخدم MCG تعريفات الإشارات من كتالوج v1.0 لإجراء عملية التحقّق واستنتاج النوع.