Định dạng JSON của yêu cầu tạo cấu hình chỉ số

Hướng dẫn này trình bày chi tiết định dạng yêu cầu JSON cho điểm cuối /api/v1/generate_metrics_config của công cụ Trình tạo cấu hình chỉ số (MCG). Định dạng này cho phép bạn xác định một chiến dịch đo từ xa (chỉ định việc thu thập dữ liệu, xử lý trên thiết bị và tạo báo cáo) trong một cấu trúc mà con người có thể đọc được.

Công cụ MCG xác thực đối tượng JSON này, kiểm tra các vấn đề như không khớp loại, các phần phụ thuộc theo chu kỳ hoặc các tham chiếu không xác định, sau đó biên dịch đối tượng này thành thông báo vùng đệm giao thức (protobuf) MetricsConfig. Thông báo MetricsConfig này là định dạng nhị phân mà dịch vụ Đo từ xa trên thiết bị thực thi để chạy chiến dịch.

Điều kiện tiên quyết: Bạn nên nắm rõ các lược đồ JSON, protobuf và cấu trúc dữ liệu cơ bản. Để biết thông tin tổng quan về khái niệm, hãy xem phần Các khái niệm về cấu hình chỉ số.

Cách viết nội dung mô tả cấu hình

Để thiết kế một chiến dịch thu thập chỉ số, hãy làm theo quy trình logic này:

1. Chỉ định nguồn dữ liệu: Xác định nguồn gốc của dữ liệu.
2. Xác định logic và quy trình xử lý: Thiết lập các quy tắc về thời điểm thu thập dữ liệu và cách xử lý dữ liệu.
3. Tạo đầu ra: Đóng gói dữ liệu đã xử lý thành một thông báo cuối cùng.
4. Các trường cấp cao nhất: Thêm các trường cấp cao nhất như UUID, định nghĩa tín hiệu và kiểm soát vòng đời.

Chỉ định nguồn dữ liệu

Dữ liệu đo từ xa hỗ trợ việc thu thập dữ liệu từ các Dịch vụ SDV (thông qua SDV Middleware) và các nhà xuất bản dựa trên Configurable Publisher Registry.

• Dịch vụ SDV (dựa trên mô hình xuất bản/đăng ký): Dữ liệu có sẵn từ các kênh xuất bản/đăng ký được xác định trong VSIDL.

• Dịch vụ SDV (dựa trên RPC): Dữ liệu có sẵn nếu dịch vụ hiển thị CreateSubscription hoặc GetLatestMessage RPC.

• Nhà xuất bản dựa trên Sổ đăng ký nhà xuất bản có thể định cấu hình: Dữ liệu có sẵn nếu ứng dụng tự đăng ký bằng IConfigurablePublisherRegistrygiao diện Android Binder hoặc thư viện Sổ đăng ký nhà xuất bản có thể định cấu hình từ Telemetry SDK.

Để sử dụng dữ liệu trong SDV, hãy xác định một nguồn dữ liệu (khái niệm) rồi thêm nguồn dữ liệu đó vào mảng data_sources.

Không phải tất cả các lựa chọn đều có sẵn cho mọi loại nguồn dữ liệu. Hãy xem hướng dẫn tích hợp nguồn dữ liệu để biết thông tin chi tiết.

Định dạng của source_identifier

Dịch vụ Đo từ xa chấp nhận nhiều định dạng mã nhận dạng nguồn. Hãy xem Định nghĩa nguồn dữ liệu trong cấu hình chỉ số để biết thông tin tổng quan.

MCG chỉ suy ra loại thông báo protobuf từ source_identifier nếu thông báo đó sử dụng định dạng Tên loại đơn vị. Nếu bạn sử dụng FQIN hoặc tên tuỳ chỉnh (từ Sổ đăng ký nhà xuất bản có thể định cấu hình), MCG sẽ không thể suy ra loại. Trong những trường hợp này, bạn phải cung cấp data_source_message_types. Nếu loại không có trong danh mục của bạn, bạn cũng phải cung cấp định nghĩa của loại đó trong 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
}

Xác định logic và quy trình xử lý

Logic được xử lý bởi hai thành phần hoạt động cùng nhau: Trình kích hoạt (khái niệm) xác định thời điểm xảy ra một sự kiện. Trình tổng hợp (khái niệm) xác định cách xử lý dữ liệu dựa trên các trình kích hoạt đó. Vì biểu thức (khái niệm) là chìa khoá cho các điều kiện kích hoạt và logic tổng hợp, nên phần này trước tiên mô tả cách viết các biểu thức.

Cụm từ

Biểu thức cho phép bạn xác định các phép tính và điều kiện bằng cách sử dụng cú pháp mà người dùng có thể đọc được. MCG biên dịch các chuỗi này thành một định dạng thực thi được tối ưu hoá để đánh giá trên thiết bị.

Biểu thức có thể thể hiện các phép tính số học, điều kiện logic và so sánh dữ liệu. Để biết cú pháp đầy đủ, bao gồm cả toán tử và hàm, hãy xem Cú pháp biểu thức.

Độ mới của dữ liệu: Khi một biểu thức truy cập vào một nguồn dữ liệu, hành vi truy xuất sẽ phụ thuộc vào loại kết nối:

• SUBSCRIPTION: Sử dụng thông báo nhận được gần đây nhất do dịch vụ Đo từ xa lưu vào bộ nhớ đệm. (Lưu ý: Nếu bạn đặt sub_sampling_interval_ms, thì thông báo này có thể khác với thông báo mới nhất tuyệt đối đã xuất bản.)
• ON_DEMAND: Kích hoạt lệnh gọi ngay lập tức để tìm nạp thông báo mới nhất từ dịch vụ.

Hạn chế về loại

• Mảng: Không hỗ trợ quyền truy cập trực tiếp vào chỉ mục mảng (ví dụ: my_data_source.my_array[0]).
• An toàn về kiểu: Đảm bảo bạn so sánh các kiểu tương thích (ví dụ: không so sánh một trường chuỗi với danh sách số nguyên).

Điều kiện kích hoạt: Xác định thời điểm xảy ra hành động

Điều kiện kích hoạt xác định thời điểm thực hiện các thao tác: đánh giá một trình tổng hợp, tạo báo cáo hoặc kiểm soát vòng đời thu thập. Thêm tất cả các điều kiện kích hoạt đã xác định vào mảng triggers cấp cao nhất.

Trình kích hoạt dữ liệu

Kích hoạt khi nguồn dữ liệu SUBSCRIPTION cung cấp một thông báo mới (khái niệm).

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

Điều kiện kích hoạt định kỳ

Phát ra lửa theo một khoảng thời gian đều đặn (khái niệm).

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

Điều kiện kích hoạt

Kích hoạt dựa trên việc đánh giá một biểu thức (khái niệm). Bạn cần có một hoặc nhiều điều kiện kích hoạt cấp trên để bắt đầu đánh giá. Đây thường là một trình kích hoạt dữ liệu cho các nguồn dữ liệu hoặc trình tổng hợp trong biểu thức, hoặc một trình kích hoạt định kỳ để thăm dò dữ liệu.

Loại tình trạng

Từ điển condition_type phải chứa chính xác một trong các loại điều kiện có sẵn dưới dạng khoá. Để biết thêm thông tin, hãy xem phần Điều kiện kích hoạt.

Lựa chọn về viền

Các đối tượng rising_options và falling_options có các trường sau. Nếu được cung cấp, quá trình chuyển đổi tương ứng phải đáp ứng yêu cầu về thời lượng. Các hiệu ứng chuyển đổi không có lựa chọn được chỉ định sẽ kích hoạt ngay lập tức.

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

Trình tổng hợp: Xác định cách xử lý dữ liệu

Sử dụng một trình tổng hợp để xử lý dữ liệu trung gian có trạng thái (khái niệm). Xác định một trình tổng hợp và thêm trình tổng hợp đó vào mảng aggregators.

Trình tổng hợp sẽ chuyển đổi dữ liệu và cung cấp dữ liệu đó cho các trình tổng hợp và báo cáo khác.

Trình tạo thông báo

Đối tượng message_builder xác định cấu trúc thông báo đầu ra và logic tổng hợp dùng để tính toán các trường của đối tượng. Đối tượng này được dùng trong cả Trình tổng hợp và Cấu hình báo cáo.

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

Tạo đầu ra

Để xác định đầu ra cuối cùng của chiến dịch đo từ xa, hãy thêm các đối tượng vào mảng report_configs (khái niệm). Các cấu hình này xác định cách đóng gói dữ liệu đã xử lý và thời điểm dữ liệu được tạo. Bạn có thể xác định nhiều cấu hình báo cáo trong một cấu hình chỉ số để sử dụng lại các thành phần.

Bạn kiểm soát việc tạo báo cáo bằng cách sử dụng trường trigger_names. Ngoài ra, bạn có thể dùng report_initial để tạo báo cáo ngay khi cấu hình kích hoạt và report_incomplete để tạo báo cáo cuối cùng khi quá trình thu thập dữ liệu bị gián đoạn.

Lưu ý: Để kết nối quá trình xử lý với đầu ra, hãy sử dụng loại tổng hợp none (@type: "none") để đọc các giá trị được tính toán trước từ một Trình tổng hợp. Vì báo cáo thường là ảnh chụp nhanh không trạng thái, nên điều này giúp duy trì logic phức tạp có trạng thái trong các trình tổng hợp và dành riêng báo cáo cho việc định dạng.

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

Trường cấp cao nhất

Ngoài các mảng data_sources, aggregators, triggers và report_configs, nội dung mô tả về cấu hình chỉ số cần có một thông tin tham chiếu đến danh mục tín hiệu. Bạn cũng có thể thêm các trường không bắt buộc để chỉ định một UUID cụ thể và quản lý vòng đời của bộ sưu tập.

Đặt UUID

Mỗi MetricsConfig đều yêu cầu một Giá trị nhận dạng duy nhất trên toàn cầu (UUID). Nếu bạn cung cấp một existing_uuid, MCG sẽ sử dụng giá trị đó. Nếu không, MCG sẽ tạo một giá trị ngẫu nhiên. Để đảm bảo tính nhất quán trên các hoạt động triển khai và công cụ, hãy chỉ định một existing_uuid.

Chuỗi này phải là một UUID hợp lệ có dấu gạch ngang và chỉ chứa chữ cái viết thường.

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

Định nghĩa về tín hiệu

Để xác thực tên và loại tín hiệu, MCG cần có quyền truy cập vào Danh mục tín hiệu xe. Đây là một protobuf FileDescriptorSet chứa các định nghĩa VSIDL .proto của bạn (được đóng gói và tải lên MCG). Để biết thông tin chi tiết về cách tạo và tải danh mục lên, hãy xem phần Danh mục tín hiệu xe.

Chỉ định phiên bản danh mục trong trường vs_version của đối tượng JSON:

"vs_version": "v1.0",

Xác định các điều kiện kích hoạt trong vòng đời

Trong bối cảnh của một chiến dịch đo từ xa, vòng đời của MetricsConfig sẽ xác định thời điểm dữ liệu thực sự được ghi lại. Trong khi hệ thống quản lý chiến dịch triển khai và kích hoạt cấu hình trên thiết bị, bạn có thể dùng các trình kích hoạt vòng đời để kiểm soát chính xác thời điểm dữ liệu được thu thập trong quá trình triển khai đó.

Điều này cho phép bạn điều chỉnh việc thu thập dữ liệu theo các kiểu sử dụng xe, chẳng hạn như "Chuyến đi" (IgnitionOn đến IgnitionOff) hoặc "Phiên sạc", mà không cần phải huỷ kích hoạt cấu hình.

• Kiểm soát phiên (Bắt đầu/Tạm dừng): Sử dụng start_trigger_name và stop_trigger_name để kiểm soát thời điểm thu thập dữ liệu. Ví dụ: để chỉ thu thập dữ liệu trong khi xe đang lái, hãy sử dụng IgnitionOn làm điều kiện kích hoạt bắt đầu và IgnitionOff làm điều kiện kích hoạt dừng. Cấu hình vẫn hoạt động trên thiết bị nhưng sẽ "tạm dừng" (ngừng thu thập và xử lý) một cách hiệu quả khi điều kiện dừng kích hoạt, chỉ tiếp tục khi điều kiện bắt đầu kích hoạt lại.

  Lưu ý quan trọng: Thao tác này chỉ tạm dừng việc thu thập. Thao tác này không xác định các cửa sổ logic, tách biệt các tập dữ liệu hoặc có bất kỳ tác dụng phụ nào khác. Giá trị của đối tượng tổng hợp không được đặt lại khi quá trình thu thập tạm dừng hoặc tiếp tục.

• Phát hiện một lần (Kết thúc): Sử dụng deactivate_trigger_name nếu cấu hình chỉ chạy một lần (ví dụ: để phát hiện lần xuất hiện đầu tiên của một mã lỗi cụ thể) rồi tự động tắt vĩnh viễn trên thiết bị đó, ngay cả khi chiến dịch vẫn đang hoạt động về mặt kỹ thuật.

Nếu bạn không chỉ định bất kỳ điều kiện kích hoạt vòng đời nào, thì quá trình thu thập dữ liệu sẽ bắt đầu ngay lập tức khi chiến dịch kích hoạt cấu hình và tiếp tục liên tục cho đến khi chiến dịch kết thúc.

Nâng cao: Định nghĩa proto tuỳ chỉnh

Trong 2 trường hợp chính, chỉ vs_version là không đủ để MCG hiểu tất cả các loại thông báo trong phần mô tả của một cấu hình chỉ số:

1. Lỗi suy luận theo kiểu: Như đã giải thích trong định dạng source_identifier, MCG không thể suy luận theo kiểu khi source_identifier sử dụng FQIN hoặc tên tuỳ chỉnh.
2. Thông báo tuỳ chỉnh: Nội dung mô tả cấu hình chỉ số sử dụng các thông báo protobuf không có trong danh mục VSIDL được chỉ định trong vs_version. Điều này xảy ra khi bạn đặt message_type trong message_builder cho định dạng báo cáo tuỳ chỉnh.

Trong những trường hợp này, hãy sử dụng data_source_message_types để giúp MCG suy luận các loại và descriptor_protos để cung cấp định nghĩa về thông báo.

data_source_message_types

Ánh xạ chuỗi source_identifier đến loại thông báo protobuf đủ điều kiện. Khoá trong data_source_message_types phải khớp với giá trị source_identifier trong mục data_sources:

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

descriptor_protos

Cung cấp định nghĩa cho mọi loại thông báo được dùng trong data_source_message_types hoặc message_builder không có trong vs_version đã định cấu hình.

Truyền descriptorpb.FileDescriptorSet được mã hoá base64 trong mảng descriptor_protos. Tạo mảng này từ các tệp .proto bằng trình biên dịch 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"
            }
          }
        ]
      }
    }
  ]
}

Mẫu tham chiếu

Để biết định nghĩa API, hãy xem Tài liệu tham khảo API MCG.

Các phần sau đây cung cấp thông tin tham khảo đầy đủ về nội dung mô tả của một cấu hình chỉ số. Hãy sử dụng thông tin này làm hướng dẫn để tạo nội dung mô tả của riêng bạn về một cấu hình chỉ số.

Trường cấp cao nhất

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

Đầu vào: nguồn dữ liệu và công cụ tổng hợp

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

Logic và xử lý: điều kiện kích hoạt

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

Đầu ra: cấu hình báo cáo

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

Cú pháp biểu thức