درخواست تولید پیکربندی معیارها با فرمت JSON

این راهنما جزئیات فرمت درخواست JSON برای نقطه پایانی /api/v1/generate_metrics_config از ابزار Metrics Configuration Generator (MCG) را شرح می‌دهد. این فرمت به شما امکان می‌دهد یک کمپین تله‌متری - که شامل جمع‌آوری داده‌ها، پردازش روی دستگاه و تولید گزارش است - را در یک ساختار قابل خواندن توسط انسان تعریف کنید.

ابزار MCG این شیء JSON را اعتبارسنجی می‌کند، مواردی مانند عدم تطابق نوع، وابستگی‌های دایره‌ای یا ارجاعات تعریف نشده را بررسی می‌کند و سپس آن را در یک پیام بافر پروتکل MetricsConfig (protobuf) کامپایل می‌کند. این پیام MetricsConfig فرمت دودویی است که سرویس تله‌متری روی دستگاه برای اجرای کمپین اجرا می‌کند.

پیش‌نیازها: شما باید با طرحواره‌های JSON، protobuf و ساختارهای داده اولیه آشنا باشید. برای مرور کلی مفهومی، به مفاهیم پیکربندی Metrics مراجعه کنید.

نحوه نوشتن توضیحات پیکربندی

برای طراحی یک کمپین جمع‌آوری معیارها، این روند منطقی را دنبال کنید:

1. منابع داده را مشخص کنید : مشخص کنید که داده‌های شما از کجا می‌آیند.
2. تعریف منطق و پردازش : قوانینی را برای زمان جمع‌آوری داده‌ها و نحوه پردازش آنها تنظیم کنید.
3. ایجاد خروجی : داده‌های پردازش‌شده را در یک پیام نهایی بسته‌بندی کنید.
4. فیلدهای سطح بالا : فیلدهای سطح بالا مانند UUID ، تعاریف سیگنال و کنترل چرخه عمر را اضافه کنید.

منابع داده را مشخص کنید

تله‌متری از جمع‌آوری داده‌ها از سرویس‌های SDV (از طریق میان‌افزار SDV) و ناشران مبتنی بر رجیستری ناشر قابل پیکربندی پشتیبانی می‌کند.

• سرویس‌های SDV (مبتنی بر کانال‌های عمومی/فرعی): داده‌ها از کانال‌های عمومی/فرعی تعریف‌شده در VSIDL در دسترس هستند.

• سرویس‌های SDV (مبتنی بر RPC): داده‌ها در صورتی در دسترس هستند که سرویس، RPCهای CreateSubscription یا GetLatestMessage در معرض نمایش قرار دهد.

• ناشران مبتنی بر رجیستری ناشر قابل تنظیم: داده‌ها در صورتی در دسترس هستند که برنامه خود را با استفاده از رابط IConfigurablePublisherRegistry Android Binder یا کتابخانه رجیستری ناشر قابل تنظیم از Telemetry SDK ثبت کند.

برای استفاده از داده‌ها در SDV، یک منبع داده ( concept ) تعریف کنید و آن را به آرایه data_sources اضافه کنید.

همه گزینه‌ها برای همه انواع منابع داده در دسترس نیستند. برای اطلاعات دقیق‌تر به راهنمای ادغام منبع داده مراجعه کنید.

قالب شناسه منبع

سرویس تله‌متری چندین قالب شناسه منبع را می‌پذیرد. برای مرور کلی، به تعریف منبع داده در تنظیمات متریک مراجعه کنید.

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
}

تعریف منطق و پردازش

منطق توسط دو مؤلفه که با هم کار می‌کنند، مدیریت می‌شود: محرک‌ها ( concept ) تعریف می‌کنند که چه زمانی اتفاقی می‌افتد. تجمیع‌کننده‌ها ( concept ) نحوه پردازش داده‌ها بر اساس آن محرک‌ها را تعریف می‌کنند. از آنجا که عبارات ( concept ) کلید ایجاد شرایط و منطق تجمیع هستند، این بخش ابتدا نحوه نوشتن آنها را شرح می‌دهد.

عبارات

عبارات به شما امکان می‌دهند محاسبات و شرایط را با استفاده از یک سینتکس قابل خواندن توسط انسان تعریف کنید. MCG این رشته‌ها را به یک فرمت اجرایی بهینه شده برای ارزیابی روی دستگاه کامپایل می‌کند.

عبارات می‌توانند محاسبات حسابی، شرایط منطقی و مقایسه داده‌ها را بیان کنند. برای مشاهده‌ی سینتکس کامل، شامل عملگرها و توابع، به بخش سینتکس عبارات مراجعه کنید.

تازگی داده‌ها: وقتی یک عبارت به منبع داده دسترسی پیدا می‌کند، رفتار بازیابی به نوع اتصال بستگی دارد:

• SUBSCRIPTION : از آخرین پیام دریافتی ذخیره شده توسط سرویس تله‌متری استفاده می‌کند. (توجه: اگر sub_sampling_interval_ms تنظیم شده باشد، ممکن است با آخرین پیام منتشر شده متفاوت باشد.)
• ON_DEMAND : یک فراخوانی فوری برای دریافت پیام جدید از سرویس را فعال می‌کند.

محدودیت‌های نوع

• آرایه‌ها: دسترسی مستقیم به اندیس آرایه (برای مثال، my_data_source.my_array[0] ) پشتیبانی نمی‌شود.
• ایمنی نوع: مطمئن شوید که انواع سازگار را مقایسه می‌کنید (برای مثال، یک فیلد رشته‌ای را با لیستی از اعداد صحیح مقایسه نکنید).

محرک‌ها: تعریف کنید که چه زمانی اقدامات رخ می‌دهند

تریگرها زمان اجرای اقدامات را تعریف می‌کنند: ارزیابی یک تجمیع‌کننده، تولید گزارش یا کنترل چرخه حیات مجموعه. تمام تریگرهای تعریف‌شده را به آرایه triggers سطح بالا اضافه کنید.

ماشه داده

زمانی اتفاق می‌افتد که یک منبع داده‌ی SUBSCRIPTION یک پیام ( concept ) جدید ارائه دهد.

{
  "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 فیلدهای زیر را دارند. در صورت وجود، transition مربوطه باید الزام مدت زمان را برآورده کند. transitionهای بدون گزینه‌های مشخص شده بلافاصله اجرا می‌شوند.

{
  "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 ساختار پیام خروجی و منطق تجمیع مورد استفاده برای محاسبه فیلدهای آن را تعریف می‌کند. این شیء هم در Aggregators و هم در Report Configurations استفاده می‌شود.

{
  "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 ( concept ) اضافه کنید. این پیکربندی‌ها نحوه بسته‌بندی داده‌های پردازش‌شده و زمان تولید آن‌ها را تعیین می‌کنند. می‌توانید چندین پیکربندی گزارش را در یک پیکربندی معیارها تعریف کنید تا از اجزا دوباره استفاده شود.

شما با استفاده از فیلد 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 خاص و مدیریت چرخه حیات مجموعه اضافه کنید.

تنظیم UUID

هر MetricsConfig به یک شناسه منحصر به فرد جهانی (UUID) نیاز دارد. اگر شما یک existing_uuid ارائه دهید، MCG از آن استفاده می‌کند. در غیر این صورت، یک شناسه تصادفی ایجاد می‌کند. برای هماهنگی بین پیاده‌سازی‌ها و ابزارها، یک 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 استفاده کنید.

اگر هیچ محرک چرخه عمری را مشخص نکنید، جمع‌آوری داده‌ها بلافاصله پس از فعال شدن پیکربندی توسط کمپین آغاز می‌شود و تا پایان کمپین به طور مداوم ادامه می‌یابد.

پیشرفته: تعاریف پروتو سفارشی

در دو مورد اصلی، 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، به مرجع MCG API مراجعه کنید.

بخش‌های زیر مرجع کاملی از توضیحات پیکربندی معیارها ارائه می‌دهند. از آن به عنوان راهنما برای ایجاد توضیحات پیکربندی معیار خودتان استفاده کنید.

فیلدهای سطح بالا

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

نحو عبارات