Format JSON żądania generowania konfiguracji danych

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

Narzędzie MCG sprawdza ten obiekt JSON pod kątem problemów, takich jak niezgodność typów, zależności zapętlone lub niezdefiniowane odwołania, a następnie kompiluje go w wiadomość bufora protokołu (protobuf) MetricsConfig. Ten komunikat MetricsConfig 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. Omówienie pojęć znajdziesz w artykule na temat konfiguracji wskaźników.

Jak napisać opis konfiguracji

Aby zaprojektować kampanię zbierania danych, wykonaj te czynności:

1. Określ źródła danych: określ, skąd pochodzą dane.
2. Zdefiniuj 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 ostateczną wiadomość.
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 konfigurowalnym rejestrze 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 Configurable Publisher Registry: dane są dostępne, jeśli aplikacja zarejestruje się za pomocą IConfigurablePublisherRegistryinterfejsu Android Binder lub biblioteki Configurable Publisher Registry z pakietu Telemetry SDK.

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

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

Format identyfikatora danych źródłowych

Usługa telemetryczna akceptuje wiele formatów identyfikatorów źródeł. Omówienie znajdziesz w sekcji Definicja źródła danych w konfiguracjach wskaźników.

MCG wnioskuje typ wiadomości protobuf z source_identifier tylko wtedy, gdy używa formatu nazwy typu jednostki. Jeśli używasz FQIN lub nazwy niestandardowej (z konfigurowalnego rejestru wydawców), MCG nie może określić 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
}

Definiowanie logiki i przetwarzania

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

Wyrażenia

Wyrażenia umożliwiają definiowanie obliczeń i warunków przy użyciu składni zrozumiałej dla człowieka. 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 odebranej wiadomości zapisanej w pamięci podręcznej przez usługę telemetrii. (Uwaga: jeśli ustawiono sub_sampling_interval_ms, może się różnić od ostatniej 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.
• Zabezpieczenia wpisywania: upewnij się, że porównujesz zgodne typy (np. nie porównuj pola ciągu znaków z listą liczb całkowitych).

Aktywatory: określ, kiedy mają być wykonywane działania

Aktywatory określają, kiedy działania są wykonywane: ocena agregatora, generowanie raportu lub kontrolowanie cyklu życia kolekcji. Dodaj wszystkie zdefiniowane reguły do tablicy triggers najwyższego poziomu.

Aktywator danych

Uruchamia się, 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

Uruchamia się 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 (koncepcja). Do rozpoczęcia oceny wymaga co najmniej 1 reguły nadrzędnej. Często jest to aktywator danych dla źródeł danych lub agregatorów w wyrażeniu albo aktywator okresowy do pobierania danych.

Typy warunku

Słownik condition_type musi zawierać dokładnie 1 z dostępnych typów warunków jako klucz. Więcej informacji znajdziesz w artykule Reguły warunkowe.

Opcje krawędzi

Obiekty rising_options i falling_options zawierają te pola. Jeśli jest podany, 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: definiowanie sposobu przetwarzania danych

Użyj agregatora do stanowego, pośredniego przetwarzania danych (koncepcja). Zdefiniuj agregator i dodaj go do tablicy aggregators.

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

Kreator wiadomości

Obiekt message_builder definiuje strukturę wiadomości wyjściowej i logikę agregacji używaną do obliczania jej pól. Jest używany zarówno w agregatorach, jak i 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
        }
      }
    ]
  }
}

Utwórz dane wyjściowe

Aby zdefiniować ostateczne dane wyjściowe kampanii telemetrycznej, dodaj obiekty do tablicy report_configs (koncepcja). Te konfiguracje określają, jak przetworzone dane są pakowane i kiedy są generowane. W jednej konfiguracji danych możesz zdefiniować wiele konfiguracji raportów, aby ponownie używać komponentów.

Generowanie raportów możesz kontrolować za pomocą pola trigger_names. Możesz też użyć report_initial, aby wygenerować raport natychmiast po aktywacji konfiguracji, oraz 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"), który umożliwia odczytywanie wstępnie obliczonych wartości z agregatora. Raporty są zwykle migawkami bezstanowymi, więc złożona logika stanowa jest zachowywana w agregatorach, a raporty są przeznaczone 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 odwołania do katalogu sygnałów. Możesz też dodać opcjonalne pola, aby przypisać konkretny identyfikator UUID i zarządzać cyklem życia kolekcji.

Ustaw UUID

Każdy MetricsConfig wymaga unikalnego identyfikatora uniwersalnego (UUID). Jeśli podasz existing_uuid, MCG go użyje. W przeciwnym razie tworzy losowy identyfikator. Aby zachować spójność między wdrożeniami i narzędziami, określ existing_uuid.

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

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

Definicje sygnałów

Aby sprawdzić nazwy i typy sygnałów, MCG wymaga dostępu do katalogu sygnałów pojazdu. Jest to bufor protokołu 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 pojazdu.

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 MetricsConfig określa, kiedy dane są faktycznie rejestrowane. Podczas gdy system zarządzania kampanią wdraża i aktywuje konfigurację na urządzeniu, możesz używać aktywatorów cyklu życia, aby 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.

• Kontrola sesji (rozpoczęcie/wstrzymanie): użyj przycisków start_trigger_name i stop_trigger_name, aby kontrolować, kiedy dane są zbierane. Jeśli na przykład chcesz zbierać dane tylko podczas jazdy, jako regułę uruchamiającą ustaw IgnitionOn, a jako regułę zatrzymującą – IgnitionOff. Konfiguracja pozostaje aktywna na urządzeniu, ale zostaje „wstrzymana” (przestaje zbierać i przetwarzać dane), gdy aktywator zatrzymania zostanie uruchomiony. Wznawia działanie dopiero po ponownym uruchomieniu aktywatora rozpoczęcia.

  Ważne: spowoduje to jedynie wstrzymanie zbierania danych. Nie definiuje okien logicznych ani oddzielnych zbiorów danych i 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 wartości deactivate_trigger_name, jeśli konfiguracja ma zostać uruchomiona tylko raz (np. w celu wykrycia pierwszego wystąpienia określonego kodu błędu), a następnie trwale dezaktywowana na tym urządzeniu, nawet jeśli kampania jest technicznie nadal aktywna.

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

Zaawansowane: niestandardowe definicje proto

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

1. Niepowodzenie wnioskowania o typie: jak wyjaśniono w sekcji Format source_identifier, MCG nie może wnioskować o typie, gdy source_identifier używa FQIN lub nazwy niestandardowej.
2. Komunikaty niestandardowe: opis konfiguracji danych korzysta z komunikatów protobuf, których nie ma w katalogu VSIDL określonym w vs_version. Dzieje się tak, gdy ustawiasz message_type w message_builder dla niestandardowego formatu raportu.

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

data_source_message_types

Zmapuj ciąg znaków source_identifier na w pełni kwalifikowany typ wiadomości protobuf. Klucz w data_source_message_types musi odpowiadać wartości source_identifier z wpisu 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órych nie ma w skonfigurowanym vs_version.

Przekaż zakodowany w formacie base64 obiekt 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 interfejsu MCG API.

W poniższych sekcjach znajdziesz pełne informacje o opisie konfiguracji wskaźników. Możesz go użyć jako przewodnika podczas tworzenia własnego opisu konfiguracji wskaźników.

Pola najwyższego poziomu

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

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ń