קטלוגים של אותות רכב

הכלי Metrics Configuration Generator (MCG) מאמת את הגדרות המדדים על ידי בדיקת שמות האותות, ביצוע בדיקת סוגים בביטויים והסקת סוגי הפלט. כדי לבצע את המשימות האלה, ל-MCG צריכה להיות גישה להגדרות של הודעות מאגר אחסון לפרוטוקולים (protobuf) עבור אותות רכב.

ב-SDV, האותות והשירותים של הרכב מוגדרים באמצעות שפה להגדרת ממשק שירות לרכב (VSIDL). ב-VSIDL נעשה שימוש בקובצי protobuf כדי לציין הודעות, והקובצי protobuf האלה מהווים את הבסיס לקטלוג אותות.

כדי להפוך את הגדרות האותות לזמינות ב-MCG, צריך לארוז את קובצי ה-VSIDL protobuf האלה ב-protobuf FileDescriptorSet ולהעלות אותו לשירות MCG. ב-MCG משתמשים במונח Vehicle Signal Catalog (קטלוג אותות רכב) כדי לתאר את קבוצות ההגדרות האלה שהועלו ונוספו להן גרסאות (בעצם, קטלוג אותות רכב הוא הצורה המהודרת והמועלית של הגדרות הודעות הפרוטו בקטלוג VSIDL).

מהו קטלוג אותות הרכב?

קטלוג אותות הרכב מספק ל-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 <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 במטען הייעודי (payload) של JSON.

כדי לקודד את vehicle_signals.pb לשימוש ב-API, משתמשים בפקודה 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 הייעודי (payload) ולהעביר אותו ל-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}.

פרטים מלאים על כל נקודות הקצה מופיעים בהפניית ה-API.

שימוש בקטלוג בהגדרות של מדדים

כשמעלים קטלוג, צריך להוסיף הפניה לגרסת הקטלוג בהגדרות המדדים באמצעות השדה vs_version:

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

כששולחים את אובייקט ה-JSON הזה לנקודות הקצה /api/v1/generate_metrics_config או /api/v1/validate_metrics_config, מערכת MCG משתמשת בהגדרות האותות מקטלוג v1.0 כדי לבצע אימות והסקת סוג.