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

במדריך הזה מפורט הפורמט של בקשת JSON לנקודת הקצה /api/v2/generate_metrics_config של הכלי Metrics Configuration Generator ‏ (MCG). הפורמט הזה מאפשר להגדיר קמפיין טלמטריה – לציין איסוף נתונים, עיבוד במכשיר ויצירת דוחות – במבנה קריא לאנשים.

כלי ה-MCG מאמת את אובייקט ה-JSON הזה, בודק אם יש בעיות כמו אי-התאמות בסוגים, תלויות מעגליות או הפניות לא מוגדרות, ואז מקמפל אותו להודעת מאגר אחסון לפרוטוקולים (protobuf) של MetricsConfig. ההודעה הזו של MetricsConfig היא הפורמט הבינארי ששירות הטלמטריה במכשיר מפעיל כדי להריץ את הקמפיין.

דרישות מוקדמות: אתם צריכים להכיר סכימות JSON,‏ protobuf ומבני נתונים בסיסיים. לסקירה כללית של המושגים, קראו את המאמר מושגים שקשורים להגדרת מדדים.

איך כותבים תיאור של הגדרה

כדי לתכנן קמפיין לאיסוף מדדים, פועלים לפי השלבים הבאים:

1. מציינים מקורות נתונים: מגדירים מאיפה הנתונים מגיעים.
2. הגדרת לוגיקה ועיבוד: מגדירים כללים לגבי מתי לאסוף נתונים ואיך לעבד אותם.
3. יצירת פלט: אריזת הנתונים שעובדו להודעה סופית.
4. שדות ברמה העליונה: מוסיפים שדות ברמה העליונה כמו UUID, הגדרות של אותות ובקרת מחזור חיים.

ציון מקורות נתונים

הטלמטריה תומכת באיסוף נתונים משירותי SDV (דרך SDV Middleware) ומבעלי תוכן דיגיטלי שמבוססים על Configurable Publisher Registry.

• שירותי SDV (מבוססי Pub/Sub): הנתונים זמינים מערוצי Pub/Sub שמוגדרים ב-VSIDL.

• שירותי SDV (מבוססי-RPC): הנתונים זמינים אם השירות חושף CreateSubscription או GetLatestMessage RPCs.

• בעלי תוכן דיגיטלי שרשומים ב-Configurable Publisher Registry: הנתונים זמינים אם האפליקציה רשומה באמצעות ממשק Android Binder של IConfigurablePublisherRegistry או ספריית Configurable Publisher Registry מ-Telemetry SDK.

כדי להשתמש בנתונים ב-SDV, מגדירים מקור נתונים (concept) ומוסיפים אותו למערך data_sources.

לא כל האפשרויות זמינות לכל סוגי מקורות הנתונים. מידע מפורט זמין במדריך לשילוב מקורות נתונים.

הפורמט של source_identifier

שירות הטלמטריה מקבל כמה פורמטים של מזהי מקור. לסקירה כללית, קראו את המאמר הגדרת מקור נתונים בהגדרות של מדדים.

‫MCG מסיק את סוג ההודעה של protobuf מ-source_identifier רק אם הוא משתמש בפורמט Unit Type Name. אם אתם משתמשים ב-FQIN או בשם מותאם אישית (מ-Configurable Publisher Registry), המערכת של MCG לא יכולה להסיק את הסוג. במקרים כאלה, צריך לספק data_source_message_types. אם הסוג לא נמצא בקטלוג, צריך לספק גם את ההגדרה שלו ב-descriptor_protos.

{
  "name": "SpeedSource",
  "source_identifier": "mcg.test.subpkg.speed_msg",
  "connection_type": "SUBSCRIPTION",
  "sub_sampling_interval_ms": 1000 // Limit updates to 1 per second
}

הגדרת הלוגיקה והעיבוד

הלוגיקה מנוהלת על ידי שני רכיבים שפועלים יחד: טריגרים (מושג) שמגדירים מתי משהו קורה. אגרגטורים (מושג) מגדירים איך הנתונים מעובדים על סמך הטריגרים האלה. מכיוון שביטויים (מושג) הם המפתח לתנאי הטריגר וללוגיקת הצבירה, בקטע הזה קודם מתואר איך לכתוב אותם.

הבעות

ביטויים מאפשרים להגדיר חישובים ותנאים באמצעות תחביר קריא לאנשים. ‫MCG מקמפל את המחרוזות האלה לפורמט שניתן להפעלה, שעבר אופטימיזציה להערכה במכשיר.

ביטויים יכולים לבטא חישובים אריתמטיים, תנאים לוגיים והשוואות נתונים. התחביר המלא, כולל אופרטורים ופונקציות, מפורט במאמר תחביר של ביטויים.

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

• ‫SUBSCRIPTION: משתמש בהודעה האחרונה שהתקבלה ונשמרה במטמון של שירות הטלמטריה. (הערה: אם מוגדר sub_sampling_interval_ms, יכול להיות שההודעה תהיה שונה מההודעה האחרונה שפורסמה).
• ‫ON_DEMAND: מפעיל קריאה מיידית לאחזור ההודעה החדשה מהשירות.

אילוצי סוגים

• מערכים: אין תמיכה בגישה ישירה לאינדקס של מערך (לדוגמה, my_data_source.my_array[0]).
• מניעת שגיאות הקלדה: חשוב לוודא שמשווים בין סוגים תואמים (לדוגמה, לא להשוות בין שדה מחרוזת לרשימה של מספרים שלמים).

טריגרים: הגדרת הזמן שבו הפעולות מתרחשות

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

טריגר נתונים

מופעל כשמקור נתונים מסוג SUBSCRIPTION מספק הודעה חדשה (קונספט).

{
  "name": "OnNewSpeed",
  "data": {
    "source_name": "SpeedSource" // Reference to the defined data source
  }
}

טריגר תקופתי

מופעל במרווחי זמן קבועים (קונספט).

{
  "name": "EveryMinute",
  "periodic": {
    "period_ms": 60000 // 60,000 ms = 60 seconds
  }
}

טריגר מותנה

מופעל על סמך הערכה של ביטוי (קונספט). כדי להתחיל את ההערכה, צריך טריגר הורה אחד או יותר. לרוב מדובר בטריגר של נתונים למקורות הנתונים או לאגרגטורים בביטוי, או בטריגר תקופתי לדגימת נתונים.

סוגי התנאים

המילון condition_type חייב להכיל בדיוק אחד מסוגי התנאים הזמינים כמפתח. מידע נוסף זמין במאמר טריגרים מותנים.

אפשרויות קצה

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

{
  "name": "SpeedingFor5Seconds",
  "conditional": {
    "triggers": ["OnNewSpeed"],
    "expression": "SpeedSource.speed > 27.7",
    "condition_type": {
      "rising_edge": {
        "rising_options": {
          "min_duration_ms": 5000 // Condition must hold for 5s in new state
        }
      }
    }
  }
}

אגרגטורים: הגדרת אופן עיבוד הנתונים

שימוש באגרגטור לעיבוד נתונים זמניים עם שמירת מצב (מושג). מגדירים אגרגטור ומוסיפים אותו למערך aggregators.

הוא משנה את הנתונים ומאפשר להשתמש בהם בדוחות ובאגרגטורים אחרים.

הכלי ליצירת הודעות

אובייקט message_builder מגדיר את מבנה הודעת הפלט ואת הלוגיקה של הצבירה שמשמשת לחישוב השדות שלה. הוא משמש גם לצבירת נתונים וגם להגדרות של דוחות.

{
  "name": "SpeedAggregator",
  "trigger_names": ["OnNewSpeed"], // Update aggregation on new speed data
  "reset_on_get": true, // Reset stats after they are read by the report configuration
  "message_builder": {
    "field_assignments": [
      {
        "field_name": "average_speed",
        "aggregation": {
          "@type": "avg",
          "expression": "SpeedSource.speed"
        }
      },
      {
        "field_name": "speed_reading_count",
        "aggregation": {
          "@type": "count" // Counts triggers (that is, processed speed readings) since last reset
        }
      },
      {
        "field_name": "speed_history_last5",
        "aggregation": {
          "@type": "vector",
          "expression": "SpeedSource.speed",
          "max_length": 5 // Keep last 5 readings
        }
      }
    ]
  }
}

יצירת פלט

כדי להגדיר את הפלט הסופי של קמפיין הטלמטריה, מוסיפים אובייקטים למערך report_configs (קונספט). ההגדרות האלה קובעות איך הנתונים המעובדים נארזים ומתי הם נוצרים. אתם יכולים להגדיר כמה דוחות בהגדרת מדדים אחת כדי להשתמש שוב ברכיבים.

אתם יכולים לשלוט ביצירת הדוחות באמצעות השדה trigger_names. בנוסף, אפשר להשתמש ב-report_initial כדי ליצור דוח מיד כשההגדרה מופעלת, וב-report_incomplete כדי ליצור דוח סופי כשיש הפרעה באיסוף הנתונים.

הערה: כדי לחבר את העיבוד לפלט, משתמשים בסוג הצבירה none (@type: "none") כדי לקרוא ערכים שחושבו מראש מ-Aggregator. בדרך כלל, דוחות הם תמונות מצב בלי שמירת מצב, ולכן הלוגיקה המורכבת של שמירת המצב נשארת בתוך האגרגטורים, והדוחות משמשים רק לעיצוב.

{
  "name": "MinuteReport",
  "trigger_names": ["EveryMinute"], // Generate report every minute
  "message_builder": {
    "field_assignments": [
      {
        "field_name": "average_speed",
        "aggregation": {
          "@type": "none", // Read the value directly from the aggregator
          "expression": "SpeedAggregator.average_speed"
        }
      },
      {
        "field_name": "reading_count",
        "aggregation": {
          "@type": "none",
          "expression": "SpeedAggregator.speed_reading_count"
        }
      }
    ]
  }
}

שדות ברמה העליונה

בנוסף למערכים data_sources,‏ aggregators,‏ triggers ו-report_configs, התיאור של הגדרת המדדים דורש הפניה לקטלוג האותות. אפשר גם לכלול שדות אופציונליים כדי להקצות UUID ספציפי ולנהל את מחזור החיים של האוסף.

הגדרת UUID

לכל MetricsConfig נדרש מזהה ייחודי אוניברסלי (UUID). אם תספקו existing_uuid, המערכת תשתמש בו. אחרת, המערכת יוצרת מזהה אקראי. כדי לשמור על עקביות בין פריסות וכלים, צריך לציין existing_uuid.

המחרוזת חייבת להיות UUID תקין עם מקפים, שמכיל רק אותיות קטנות.

"existing_uuid": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",

הגדרות של אותות

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

מציינים את גרסת הקטלוג בשדה vs_version של אובייקט ה-JSON:

"vs_version": "v1.0",

הגדרת טריגרים של מחזור חיים

בהקשר של קמפיין טלמטריה, מחזור החיים של MetricsConfig קובע מתי הנתונים נרשמים בפועל. בזמן שמערכת ניהול הקמפיינים פורסת ומפעילה את ההגדרות במכשיר, אתם יכולים להשתמש בטריגרים של מחזור חיים כדי לקבוע בדיוק מתי הנתונים ייאספו במסגרת הפריסה הזו.

כך אפשר להתאים את איסוף הנתונים לדפוסי השימוש ברכב, כמו "נסיעה" (IgnitionOn עד IgnitionOff) או "סשן טעינה", בלי להשבית את ההגדרות האישיות.

• שליטה בסשן (התחלה/השהיה): משתמשים ב-start_trigger_name וב-stop_trigger_name כדי לשלוט במועד האיסוף. לדוגמה, כדי לאסוף נתונים רק כשהרכב בנסיעה, משתמשים ב-IgnitionOn כטריגר להתחלה וב-IgnitionOff כטריגר לעצירה. ההגדרה נשארת פעילה במכשיר, אבל למעשה היא "מושהית" (מפסיקה לאסוף ולעבד נתונים) כשהטריגר להפסקה מופעל, ומתחדשת רק כשהטריגר להפעלה מופעל שוב.

  חשוב: הפעולה הזו רק משהה את האיסוף. היא לא מגדירה חלונות לוגיים, קבוצות נתונים נפרדות או כל השפעה אחרת. ערכי הצבירה לא מתאפסים כשהאיסוף מושהה או מתחדש.

• זיהוי חד-פעמי (סיום): משתמשים ב-deactivate_trigger_name אם ההגדרה צריכה לפעול רק פעם אחת (לדוגמה, כדי לזהות את המופע הראשון של קוד שגיאה ספציפי) ואז להשבית את עצמה באופן סופי במכשיר הזה, גם אם הקמפיין עדיין פעיל מבחינה טכנית.

אם לא תציינו טריגרים של מחזור חיים, איסוף הנתונים יתחיל מיד כשההגדרה תופעל על ידי הקמפיין, ויימשך עד שהקמפיין יסתיים.

מתקדם: הגדרות proto בהתאמה אישית

יש שני מקרים עיקריים שבהם vs_version לבדו לא מספיק כדי ש-MCG יבין את כל סוגי ההודעות בתיאור של הגדרת המדדים:

1. כשל בהסקת סוג: כפי שמוסבר בפורמט source_identifier, MCG לא יכול להסיק את הסוג כש-source_identifier משתמש ב-FQIN או בשם מותאם אישית.
2. הודעות בהתאמה אישית: התיאור של הגדרת המדדים משתמש בהודעות protobuf שלא נמצאות בקטלוג VSIDL שצוין ב-vs_version. זה קורה כשמגדירים את message_type ב-message_builder לפורמט של דוח בהתאמה אישית.

במקרים כאלה, משתמשים ב-data_source_message_types כדי לעזור ל-MCG להסיק סוגים וב-descriptor_protos כדי לספק הגדרות של הודעות.

data_source_message_types

ממפים את המחרוזת source_identifier לסוג ההודעה המלא של protobuf. המפתח ב-data_source_message_types צריך להתאים לערך של source_identifier מהרשומה של data_sources:

"data_source_message_types": {
  "MyCustomSpeedService": "com.sdv.example.SampleMessage"
}

descriptor_protos

צריך לספק הגדרות לכל סוגי ההודעות שנעשה בהם שימוש ב-data_source_message_types או ב-message_builder, שלא נמצאים ב-vs_version שהוגדר.

מעבירים את הערך של descriptorpb.FileDescriptorSet בקידוד Base64 במערך descriptor_protos. אפשר ליצור את זה מקובצי .proto באמצעות המהדר של Protobuf‏ protoc.

"descriptor_protos": [
  "Cu8BCiZtY2cvdGVzdGRhdGEvbWF4YXZnY3..." // Base64 string
]

{
  "existing_uuid": "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8", // Unique identifier for the configuration
  "vs_version": "example_version", // Version of the VSIDL catalog to use
  "data_sources": [
    {
      "name": "SpeedSource",
      "source_identifier": "mcg.test.subpkg.speed_msg",
      "connection_type": "SUBSCRIPTION",
      "sub_sampling_interval_ms": 1000
    }
  ],
  "aggregators": [
    {
      "name": "SpeedAggregator",
      "trigger_names": ["OnNewSpeed"],
      "reset_on_get": true,
      "message_builder": {
        "field_assignments": [
          {
            "field_name": "average_speed",
            "aggregation": {
              "@type": "avg",
              "expression": "SpeedSource.speed"
            }
          },
          {
            "field_name": "speed_reading_count",
            "aggregation": { "@type": "count" }
          },
          {
            "field_name": "speed_history_last5",
            "aggregation": {
              "@type": "vector",
              "expression": "SpeedSource.speed",
              "max_length": 5
            }
          }
        ]
      }
    }
  ],
  "triggers": [
    {
      "name": "OnNewSpeed",
      "data": { "source_name": "SpeedSource" }
    },
    {
      "name": "EveryMinute",
      "periodic": { "period_ms": 60000 }
    }
  ],
  "report_configs": [
    {
      "name": "MinuteReport",
      "trigger_names": ["EveryMinute"],
      "message_builder": {
        "field_assignments": [
          {
            "field_name": "average_speed",
            "aggregation": {
              "@type": "none",
              "expression": "SpeedAggregator.average_speed"
            }
          },
          {
            "field_name": "reading_count",
            "aggregation": {
              "@type": "none",
              "expression": "SpeedAggregator.speed_reading_count"
            }
          }
        ]
      }
    }
  ]
}

תבנית של קובץ עזר

הגדרת ה-API מופיעה במאמרי העזרה של ה-API.

בקטעים הבאים מפורטות כל ההגדרות של המדדים. אפשר להשתמש בו כמדריך ליצירת תיאור משלכם להגדרת מדדים.

שדות ברמה העליונה

{
  "existing_uuid": "1cbec8e6-46f5-4649-9fa2-09f81bc93f8b", // Optional
  "vs_version": "example_version", // Optional
  "descriptor_protos": ["..."], // Optional. Base64 encoded FileDescriptorSet
  "data_source_message_types": {
    "ExampleServiceName": "com.example.ProtoMessage"
  }, // Optional
  "start_trigger_name": "DataTriggerExample", // Optional
  "stop_trigger_name": "ConditionalTriggerExample", // Optional
  "deactivate_trigger_name": "PeriodicTriggerExample" // Optional
}

קלט: מקורות נתונים ואגרגטורים

{
  "data_sources": [
    {
      "name": "SubscriptionExample",
      "source_identifier": "com.example.sdv.ExampleMessage|example-unit",
      "connection_type": "SUBSCRIPTION", // Options: SUBSCRIPTION (default), ON_DEMAND
      "sub_sampling_interval_ms": 100, // Optional
      "fetch_last_message": false // Optional. Default: false
    },
    {
      "name": "RegistryExample",
      // Configurable Publisher Registry-based publisher (matches data_source_message_types)
      "source_identifier": "ExampleServiceName",
      "connection_type": "SUBSCRIPTION"
    },
    {
      "name": "GetterExample",
      "source_identifier": "com.example.sdv.ExampleConfig|example-unit",
      "connection_type": "ON_DEMAND",
      "configuration": {
        "type_url": "type.googleapis.com/example.Config",
        "value_json": {} // Or value_textproto, value (base64)
      }
    }
  ],
  "aggregators": [
    {
      "name": "AggregatorExample",
      "trigger_names": ["DataTriggerExample"],
      "reset_on_get": false, // Optional. Default: false. If true, resets state after it's read
      "message_builder": {
        "message_type": ".com.example.AggregatedMessage", // Optional
        "field_assignments": [
          {
            "field_name": "avg_example",
            "aggregation": {
              // Options: avg, count, min, max, sum, stddev, delta, vector, none
              "@type": "avg",
              "expression": "SubscriptionExample.value"
            }
          },
          {
            "field_name": "count_example",
            "aggregation": {
              "@type": "count" // Counts number of evaluations. No expression needed
            }
          },
          {
            "field_name": "vector_example",
            "aggregation": {
              "@type": "vector",
              "expression": "SubscriptionExample.value",
              "max_length": 10 // Optional. If set, creates a ring buffer
            }
          }
        ]
      }
    }
  ]
}

לוגיקה ועיבוד: טריגרים

{
  "triggers": [
    {
      "name": "PeriodicTriggerExample",
      "periodic": { "period_ms": 1000 }
    },
    {
      "name": "DataTriggerExample",
      "data": { "source_name": "SubscriptionExample" }
    },
    {
      "name": "ConditionalTriggerExample",
      "conditional": {
        "triggers": ["PeriodicTriggerExample"],
        "expression": "SubscriptionExample.value > 0",
        "condition_type": {
          // Options: is_true, is_false, rising_edge, falling_edge, all_changes
          "rising_edge": {
            "rising_options": { "min_duration_ms": 0, "require_exact": false }
          }
        }
      }
    }
  ]
}

פלט: הגדרות הדוח

{
  "report_configs": [
    {
      "name": "ReportExample",
      "trigger_names": ["PeriodicTriggerExample"],
      "report_incomplete": false, // Optional. Default: false
      "report_initial": false, // Optional. Default: false
      "message_builder": {
        "message_type": ".com.example.ReportMessage", // Optional. Must be defined in VSIDL catalog or descriptor_protos. Message type will be inferred if not provided
        "field_assignments": [
          {
            "field_name": "avg_example",
            "aggregation": {
              "@type": "none", // Passthrough since aggregation is done in AggregatorExample
              "expression": "AggregatorExample.avg_example"
            }
          }
        ]
      }
    }
  ]
}

תחביר של ביטויים