تنسيق JSON لطلب إنشاء إعدادات المقاييس

يوضّح هذا الدليل بالتفصيل تنسيق طلب JSON لنقطة النهاية /api/v1/generate_metrics_config الخاصة بأداة Metrics Configuration Generator (MCG). يتيح لك هذا التنسيق تحديد حملة قياس عن بُعد، وتحديد جمع البيانات ومعالجتها على الجهاز وإنشاء التقارير، وذلك في بنية يمكن قراءتها.

تتحقّق أداة MCG من صحة كائن JSON هذا، وتبحث عن مشاكل مثل عدم تطابق الأنواع أو التبعيات الدائرية أو المراجع غير المحدّدة، ثم تجمّعه في رسالة MetricsConfig Protocol Buffers (protobuf). هذه MetricsConfig الرسالة هي التنسيق الثنائي الذي تنفّذه خدمة القياس عن بُعد على الجهاز لتشغيل الحملة.

المتطلبات الأساسية: يجب أن تكون على دراية بمخططات JSON وprotobuf وبنى البيانات الأساسية. للحصول على نظرة عامة مفاهيمية، يُرجى الاطّلاع على مفاهيم إعداد المقاييس.

كيفية كتابة وصف إعدادات

لتصميم حملة لجمع المقاييس، اتّبِع التسلسل المنطقي التالي:

1. تحديد مصادر البيانات: حدِّد مصدر بياناتك.
2. تحديد المنطق والمعالجة: يمكنك إعداد قواعد تحدّد متى يتم جمع البيانات وكيفية معالجتها.
3. إنشاء الناتج: يتم تجميع البيانات المعالَجة في رسالة نهائية.
4. الحقول ذات المستوى الأعلى: أضِف حقولاً ذات مستوى أعلى، مثل المعرّف الفريد العالمي (UUID) وتعريفات الإشارات وعنصر التحكّم في مراحل النشاط.

تحديد مصادر البيانات

تتيح القياس عن بُعد جمع البيانات من "خدمات القيمة المضافة" (عبر "برنامج الوسيط لخدمات القيمة المضافة") والناشرين المستندين إلى "سجلّ الناشرين القابل للإعداد".

• خدمات SDV (استنادًا إلى النشر/الاشتراك): تتوفّر البيانات من قنوات النشر/الاشتراك المحدّدة في VSIDL.

• خدمات SDV (استنادًا إلى RPC): تتوفّر البيانات إذا كانت الخدمة تعرض CreateSubscription أو GetLatestMessage RPC.

• الناشرون المستندون إلى "سجلّ الناشرين القابل للضبط": تتوفّر البيانات إذا سجّل التطبيق نفسه باستخدام IConfigurablePublisherRegistry واجهة Android Binder أو مكتبة "سجلّ الناشرين القابل للضبط" من حزمة تطوير البرامج (SDK) الخاصة بخدمة القياس عن بُعد.

لاستخدام البيانات في SDV، حدِّد مصدر بيانات (مفهوم) وأضِفه إلى مصفوفة data_sources.

لا تتوفّر جميع الخيارات لجميع أنواع مصادر البيانات. يمكنك الاطّلاع على دليل دمج مصادر البيانات للحصول على معلومات مفصّلة.

تنسيق source_identifier

تقبل خدمة القياس عن بُعد عدة تنسيقات لمعرّفات المصادر. للحصول على نظرة عامة، اطّلِع على تعريف مصدر البيانات في إعدادات المقاييس.

يستنتج MCG نوع رسالة protobuf من source_identifier فقط إذا كان يستخدم تنسيق اسم نوع الوحدة. إذا كنت تستخدم 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") لقراءة القيم المحسوبة مسبقًا من أداة تجميع. وبما أنّ التقارير عادةً ما تكون لقطات بدون حالة، فإنّ هذا الإجراء يحافظ على المنطق المعقّد ذي الحالة ضمن أدوات التجميع ويحجز التقارير للتنسيق.

{
  "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) محدّد وإدارة دورة حياة المجموعة.

ضبط المعرّف الفريد العالمي

يتطلّب كل MetricsConfig معرّفًا فريدًا عالميًا (UUID). إذا قدّمت existing_uuid، ستستخدمها "مجموعة إعلانات العملاء". وإلا، سيتم إنشاء رمز عشوائي. للحفاظ على الاتساق في عمليات النشر والأدوات، حدِّد existing_uuid.

يجب أن تكون السلسلة معرّفًا فريدًا عالميًا صالحًا يتضمّن واصلات ويحتوي على أحرف صغيرة فقط.

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

تعريفات الإشارات

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

حدِّد إصدار الكتالوج في الحقل vs_version ضمن عنصر JSON:

"vs_version": "v1.0",

تحديد مشغّلات مراحل النشاط

في سياق حملة قياس عن بُعد، تحدّد دورة حياة MetricsConfig وقت تسجيل البيانات فعليًا. وبينما ينشر نظام إدارة الحملة الإعداد ويفعّله على الجهاز، يمكنك استخدام مشغّلات دورة الحياة للتحكّم بدقة في وقت جمع البيانات ضمن عملية النشر هذه.

يتيح لك ذلك ربط عملية جمع البيانات بأنماط استخدام المركبة، مثل "رحلة" (من IgnitionOn إلى IgnitionOff) أو "جلسة شحن"، بدون الحاجة إلى إيقاف الإعدادات.

• التحكّم في الجلسة (بدء/إيقاف مؤقت): استخدِم start_trigger_name وstop_trigger_name للتحكّم في وقت جمع البيانات. على سبيل المثال، لجمع البيانات فقط أثناء قيادة المركبة، استخدِم IgnitionOn كعامل تشغيل بدء وIgnitionOff كعامل تشغيل إيقاف. يظل الإعداد نشطًا على الجهاز، ولكن يتم "إيقافه مؤقتًا" (أي التوقف عن جمع البيانات ومعالجتها) عند تشغيل مشغّل الإيقاف، ولا تتم استعادته إلا عند تشغيل مشغّل البدء مرة أخرى.

  ملاحظة مهمة: يؤدي هذا الإجراء إلى إيقاف عملية الجمع مؤقتًا فقط. ولا يحدّد نوافذ منطقية أو مجموعات بيانات منفصلة أو أي آثار جانبية أخرى. لا تتم إعادة ضبط قيم أداة التجميع عند إيقاف عملية التجميع مؤقتًا أو استئنافها.

• الرصد لمرة واحدة (إنهاء): استخدِم deactivate_trigger_name إذا كان من المفترض أن يتم تنفيذ الإعداد مرة واحدة فقط (على سبيل المثال، لرصد أول ظهور لرمز خطأ معيّن) ثم يتم إيقافه نهائيًا على هذا الجهاز، حتى إذا كانت الحملة لا تزال نشطة من الناحية الفنية.

إذا لم تحدّد أي مشغّلات لدورة الحياة، سيبدأ جمع البيانات فورًا عندما يتم تفعيل الإعداد من خلال الحملة، وسيستمر بشكل متواصل إلى أن تنتهي الحملة.

متقدّم: تعريفات بروتوكول مخصّصة

في حالتين رئيسيتين، لا تكون vs_version وحدها كافية لكي تفهم أداة "مقارنة المقاييس" جميع أنواع الرسائل في وصف إعدادات المقاييس:

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"
            }
          }
        ]
      }
    }
  ]
}

نموذج المرجع

للاطّلاع على تعريف واجهة برمجة التطبيقات، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات "برنامج الشركاء التجاريين في Google".

تقدّم الأقسام التالية مرجعًا كاملاً لوصف إعدادات المقاييس، ويمكنك استخدامها كدليل لإنشاء وصف خاص بك لإعدادات المقاييس.

الحقول ذات المستوى الأعلى

{
  "existing_uuid": "00000000-0000-0000-0000-000000000000", // 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"
            }
          }
        ]
      }
    }
  ]
}

بنية التعبيرات