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

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

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

כדי שהגדרות האותות יהיו זמינות ל-MCG, צריך לארוז את קובצי ה-VSIDL protobuf האלה ב-protobuf FileDescriptorSet ולהעלות אותם לשירות MCG. ב-MCG משתמשים במונח Vehicle Signal Catalog לקבוצות ההגדרות האלה שהועלו ונוספה להן גרסה (בעצם, Vehicle Signal Catalog הוא הטופס המקומפל שהועלה של הגדרות ההודעות של הפרוטוקול בקטלוג ה-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, אפשר להעלות ולנהל אותו באמצעות נקודות קצה ל-API של MCG ב-/api/v2/vs/. נקודת הקצה להוספה או לעדכון של קטלוג, POST /api/v2/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/v2/vs/ עם שם גרסה ייחודי.

גוף הבקשה חייב להיות אובייקט JSON שמכיל את המחרוזת version ואת המחרוזת vehicle_signals בקידוד base64:

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

בדוגמה הבאה אפשר לראות איך להעלות את vehicle_signals.pb כגרסה v1.0 באמצעות curl. בדוגמה נעשה שימוש ב-printf כדי ליצור את המטען הייעודי (payload) של ה-JSON, והוא מועבר בצינור עיבוד נתונים (pipe) אל 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/v2/vs/"

הצגה ומחיקה של גרסאות

אתם יכולים להציג את כל הגרסאות הזמינות של הקטלוג או למחוק גרסה ספציפית:

• הצגת רשימת גרסאות: כדי לראות רשימה של מזהים לכל גרסאות הקטלוג שהועלו, שולחים בקשת GET אל /api/v2/vs/. אפשר לעיין ב-GET /api/v2/vs/.

• מחיקת גרסה: כדי להסיר קטלוג, שולחים בקשת DELETE אל /api/v2/vs/{version}, כאשר {version} הוא המזהה שסופק כשהקטלוג הועלה (לדוגמה, v1.0). אפשר לעיין ב-DELETE /api/v2/vs/{version}.

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

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

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

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

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