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

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

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

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

ما هو "كتالوج إشارات المركبات"؟

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

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

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

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

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

protoc --include_imports --descriptor_set_out=vehicle_signals.pb <var label="path to folder with .proto files">path/to/your/protos</var>/*.proto

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

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

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

بعد إنشاء ملف vehicle_signals.pb، يمكنك تحميله وإدارته باستخدام نقاط نهاية MCG API ضمن /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="<var label="catalog version">v1.0</var>"
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، تستخدم خدمة "مطابقة العملاء" تعريفات الإشارات من فهرس v1.0 لإجراء عملية التحقّق واستنتاج النوع.