Format JSON żądania generowania konfiguracji danych

Ten przewodnik zawiera szczegółowe informacje o formacie żądania JSON dla punktu końcowego /api/v1/generate_metrics_config narzędzia do generowania konfiguracji danych (MCG). Ten format umożliwia zdefiniowanie kampanii telemetrycznej – określenie zbierania danych, przetwarzania na urządzeniu i generowania raportów – w strukturze czytelnej dla człowieka.

Narzędzie MCG weryfikuje ten obiekt JSON, sprawdzając, czy nie występują w nim problemy, takie jak niezgodność typów, zależności cykliczne lub niezdefiniowane odwołania, a następnie kompiluje go do postaci komunikatu MetricsConfig bufora protokołu (protobuf). Ta MetricsConfigwiadomość jest formatem binarnym, który usługa telemetrii na urządzeniu wykonuje, aby uruchomić kampanię.

Wymagania wstępne: musisz znać schematy JSON, protobuf i podstawowe struktury danych. Informacje koncepcyjne znajdziesz w artykule Koncepcje konfiguracji danych.

Jak napisać opis konfiguracji

Aby zaprojektować kampanię zbierającą dane, postępuj zgodnie z tym schematem:

1. Określ źródła danych: zdefiniuj, skąd pochodzą dane.
2. Określ logikę i przetwarzanie: skonfiguruj reguły określające, kiedy zbierać dane i jak je przetwarzać.
3. Utwórz dane wyjściowe: spakuj przetworzone dane w wiadomość końcową.
4. Pola najwyższego poziomu: dodaj pola najwyższego poziomu, takie jak UUID, definicje sygnałów i kontrola cyklu życia.

Określanie źródeł danych

Telemetria obsługuje zbieranie danych z usług SDV (za pomocą oprogramowania pośredniczącego SDV) i wydawców opartych na rejestrze konfigurowalnych wydawców.

• Usługi SDV (oparte na Pub/Sub): dane są dostępne z kanałów Pub/Sub zdefiniowanych w VSIDL.

• Usługi SDV (oparte na RPC): dane są dostępne, jeśli usługa udostępnia CreateSubscription lub GetLatestMessage RPC.

• Wydawcy korzystający z rejestru wydawców z możliwością konfiguracji: dane są dostępne, jeśli aplikacja rejestruje się za pomocą IConfigurablePublisherRegistryinterfejsu Android Binder lub biblioteki rejestru wydawców z możliwością konfiguracji z pakietu SDK do telemetrii.

Aby używać danych w SDV, zdefiniuj źródło danych (koncepcja) i dodaj je do tablicy data_sources.

Nie wszystkie opcje są dostępne w przypadku wszystkich typów źródeł danych. Szczegółowe informacje znajdziesz w przewodniku po integracji źródeł danych.

Format parametru source_identifier

Usługa telemetrii akceptuje formaty identyfikatorów wielu źródeł. Więcej informacji znajdziesz w sekcji Definicja źródła danych w konfiguracjach wskaźników.

MCG wywnioskuje typ wiadomości protobuf z source_identifier tylko wtedy, gdy używa formatu Unit Type Name. Jeśli używasz FQIN lub nazwy niestandardowej (z Configurable Publisher Registry), MCG nie może wywnioskować typu. W takich przypadkach musisz podać data_source_message_types. Jeśli typu nie ma w katalogu, musisz też podać jego definicję w 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
}

Określanie logiki i przetwarzania

Logika jest obsługiwana przez 2 współdziałające ze sobą komponenty: reguły (koncepcja) określają, kiedy coś się dzieje, a agregatory (koncepcja) określają, jak dane są przetwarzane na podstawie tych reguł. Wyrażenia (koncepcja) są kluczowe dla warunków reguł i logiki agregacji, dlatego w tej sekcji najpierw opisujemy, jak je pisać.

Wyrażenia

Wyrażenia umożliwiają definiowanie obliczeń i warunków za pomocą czytelnej dla użytkownika składni. MCG kompiluje te ciągi znaków do formatu wykonywalnego zoptymalizowanego pod kątem oceny na urządzeniu.

Wyrażenia mogą zawierać obliczenia arytmetyczne, warunki logiczne i porównania danych. Pełną składnię, w tym operatory i funkcje, znajdziesz w artykule Składnia wyrażeń.

Częstotliwość aktualizacji danych: gdy wyrażenie uzyskuje dostęp do źródła danych, sposób pobierania zależy od typu połączenia:

• SUBSCRIPTION: używa ostatniej otrzymanej wiadomości zapisanej w pamięci podręcznej przez usługę Telemetria. (Uwaga: jeśli ustawiono sub_sampling_interval_ms, może się to różnić od najnowszej opublikowanej wiadomości).
• ON_DEMAND: Wywołuje natychmiastowe połączenie w celu pobrania nowej wiadomości z usługi.

Ograniczenia typu

• Tablice: bezpośredni dostęp do indeksu tablicy (np.my_data_source.my_array[0]) nie jest obsługiwany.
• Bezpieczeństwo typów: upewnij się, że porównujesz zgodne typy (np. nie porównuj pola tekstowego z listą liczb całkowitych).

Aktywatory: określ, kiedy mają wystąpić działania

Triggery określają, kiedy mają być wykonywane działania: ocena agregatora, generowanie raportu lub kontrolowanie cyklu życia zbierania danych. Dodaj wszystkie zdefiniowane triggery do tablicy najwyższego poziomu triggers.

Wyzwalacz danych

Wywoływane, gdy źródło danych SUBSCRIPTION dostarcza nową wiadomość (koncepcja).

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

Reguła okresowa

Wystrzeliwuje pociski w regularnych odstępach czasu (koncepcja).

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

Aktywator warunkowy

Uruchamia się na podstawie oceny wyrażenia (pojęcia). Aby rozpocząć ocenę, wymaga co najmniej jednego wyzwalacza nadrzędnego. Jest to często wyzwalacz danych dla źródeł danych lub agregatorów w wyrażeniu albo wyzwalacz okresowy do sondowania danych.

Typy warunków

condition_type słownik musi zawierać dokładnie jeden z dostępnych typów warunków jako klucz. Więcej informacji znajdziesz w sekcji Wywoływanie warunkowe.

Opcje krawędzi

Obiekty rising_options i falling_options mają te pola: Jeśli podano czas trwania, odpowiednie przejście musi spełniać wymagania dotyczące czasu trwania. Przejścia bez określonych opcji są uruchamiane natychmiast.

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

Agregatory: określają sposób przetwarzania danych.

Użyj agregatora do przetwarzania danych pośrednich z zachowaniem stanu (koncepcja). Zdefiniuj agregatora i dodaj go do tablicy aggregators.

Agregator przekształca dane i udostępnia je innym agregatorom oraz raportom.

Kreator wiadomości

Obiekt message_builder określa strukturę wiadomości wyjściowej i logikę agregacji używaną do obliczania jej pól. Jest on używany zarówno w agregatorach, jak i w konfiguracjach raportów.

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

Tworzenie danych wyjściowych

Aby zdefiniować ostateczny wynik kampanii telemetrycznej, dodaj obiekty do tablicy report_configs (concept). Te konfiguracje określają sposób pakowania przetworzonych danych i czas ich generowania. W jednej konfiguracji wskaźników możesz zdefiniować wiele konfiguracji raportów, aby ponownie wykorzystywać komponenty.

Generowaniem raportów możesz sterować za pomocą pola trigger_names. Możesz też użyć parametru report_initial, aby wygenerować raport natychmiast po aktywowaniu konfiguracji, oraz parametru report_incomplete, aby wygenerować raport końcowy po przerwaniu zbierania danych.

Uwaga: aby połączyć przetwarzanie z danymi wyjściowymi, użyj typu agregacji none (@type: "none"), aby odczytać wstępnie obliczone wartości z agregatora. Raporty są zwykle bezstanowymi migawkami, więc dzięki temu złożona logika stanowa pozostaje w agregatorach, a raporty służą do formatowania.

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

Pola najwyższego poziomu

Oprócz tablic data_sources, aggregators, triggers i report_configs opis konfiguracji danych wymaga odniesienia do katalogu sygnałów. Możesz też uwzględnić pola opcjonalne, aby przypisać konkretny identyfikator UUID i zarządzać cyklem życia kolekcji.

Ustawianie identyfikatora UUID

Każdy element MetricsConfig wymaga unikalnego identyfikatora uniwersalnego (UUID). Jeśli podasz existing_uuid, MCG użyje tego adresu. W przeciwnym razie tworzy losowy. Aby zapewnić spójność w przypadku wdrożeń i narzędzi, określ existing_uuid.

Ciąg znaków musi być prawidłowym identyfikatorem UUID z łącznikami, który zawiera tylko małe litery.

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

Definicje sygnałów

Aby zweryfikować nazwy i typy sygnałów, MCG wymaga dostępu do katalogu sygnałów pojazdu. Jest to plik protobuf FileDescriptorSet zawierający definicje VSIDL .proto (spakowane i przesłane do MCG). Szczegółowe informacje o tworzeniu i przesyłaniu katalogu znajdziesz w artykule Katalogi sygnałów pojazdów.

Określ wersję katalogu w polu vs_version obiektu JSON:

"vs_version": "v1.0",

Definiowanie aktywatorów cyklu życia

W kontekście kampanii telemetrycznej cykl życia MetricsConfigokreśla, kiedy dane są faktycznie rejestrowane. System zarządzania kampanią wdraża i aktywuje konfigurację na urządzeniu, ale za pomocą wyzwalaczy cyklu życia możesz precyzyjnie kontrolować, kiedy dane są zbierane w ramach tego wdrożenia.

Dzięki temu możesz dostosować zbieranie danych do wzorców użytkowania pojazdu, takich jak „Podróż” (IgnitionOn do IgnitionOff) lub „Sesja ładowania”, bez konieczności dezaktywowania konfiguracji.

• Sterowanie sesją (rozpoczęcie/wstrzymanie): użyj gestów start_trigger_name i stop_trigger_name, aby określić, kiedy ma się odbywać zbieranie danych. Aby na przykład zbierać dane tylko podczas jazdy pojazdem, użyj IgnitionOn jako wyzwalacza rozpoczęcia i IgnitionOff jako wyzwalacza zakończenia. Konfiguracja pozostaje aktywna na urządzeniu, ale po uruchomieniu wyzwalacza zatrzymania zostaje „wstrzymana” (przestaje zbierać i przetwarzać dane), a wznawia działanie dopiero po ponownym uruchomieniu wyzwalacza rozpoczęcia.

  Ważne: to tylko wstrzymuje zbieranie danych. Nie definiuje ona okien logicznych, oddzielnych zbiorów danych ani nie ma żadnych innych efektów ubocznych. Wartości agregatora nie są resetowane, gdy zbieranie danych jest wstrzymywane lub wznawiane.

• Wykrywanie jednorazowe (zakończenie): użyj deactivate_trigger_name, jeśli konfiguracja ma być uruchamiana tylko raz (np. w celu wykrycia pierwszego wystąpienia określonego kodu błędu), a następnie ma się trwale dezaktywować na danym urządzeniu, nawet jeśli kampania jest technicznie nadal aktywna.

Jeśli nie określisz żadnych wyzwalaczy cyklu życia, zbieranie danych rozpocznie się natychmiast po aktywowaniu konfiguracji przez kampanię i będzie kontynuowane nieprzerwanie do zakończenia kampanii.

Zaawansowane: niestandardowe definicje protokołu

W 2 głównych przypadkach sam znak vs_version nie wystarczy, aby MCG zrozumiał wszystkie typy wiadomości w opisie konfiguracji danych:

1. Błąd wnioskowania o typie: jak wyjaśniono w sekcji source_identifierformat, MCG nie może wywnioskować typu, gdy source_identifier używa FQIN lub nazwy niestandardowej.
2. Wiadomości niestandardowe: opis konfiguracji danych zawiera wiadomości protobuf, których nie ma w katalogu VSIDL określonym w vs_version. Dzieje się tak, gdy ustawisz message_type w message_builder w przypadku niestandardowego formatu raportu.

W takich przypadkach użyj data_source_message_types, aby pomóc MCG w określaniu typów, i descriptor_protos, aby podać definicje wiadomości.

data_source_message_types

Zmapuj source_identifier ciąg znaków na jego pełny typ wiadomości protobuf. Klucz w data_source_message_types musi być zgodny z wartością source_identifier z pozycji data_sources:

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

descriptor_protos

Podaj definicje wszystkich typów wiadomości używanych w data_source_message_types lub message_builder, które nie znajdują się w skonfigurowanym vs_version.

Przekaż zakodowany w standardzie base64 plik descriptorpb.FileDescriptorSet w tablicy descriptor_protos. Wygeneruj go z plików .proto za pomocą kompilatora 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"
            }
          }
        ]
      }
    }
  ]
}

Szablon referencyjny

Definicję interfejsu API znajdziesz w dokumentacji API MCG.

W sekcjach poniżej znajdziesz pełne informacje o konfiguracji danych. Skorzystaj z nich, aby utworzyć własny opis konfiguracji danych.

Pola najwyższego poziomu

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

Dane wejściowe: źródła danych i agregatory

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

Logika i przetwarzanie: aktywatory

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

Dane wyjściowe: konfiguracje raportów

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

Składnia wyrażeń