指標構成生成リクエストの JSON 形式

このガイドでは、Metrics Configuration Generator（MCG）ツールの /api/v1/generate_metrics_config エンドポイントの JSON リクエスト形式について詳しく説明します。この形式を使用すると、人が読める構造でテレメトリー キャンペーン（データの収集、デバイス上の処理、レポート生成を指定）を定義できます。

MCG ツールはこの JSON オブジェクトを検証し、型の不一致、循環依存関係、未定義の参照などの問題をチェックしてから、MetricsConfig プロトコル バッファ（protobuf）メッセージにコンパイルします。この MetricsConfig メッセージは、オンデバイスのテレメトリー サービスがキャンペーンを実行するために実行するバイナリ形式です。

前提条件: JSON スキーマ、protobuf、基本的なデータ構造について理解している必要があります。概念の概要については、指標構成のコンセプトをご覧ください。

構成の説明の作成方法

指標収集キャンペーンを設計するには、次の論理フローに沿って操作します。

1. データソースを指定する: データの取得元を定義します。
2. ロジックと処理を定義する: データを収集するタイミングと処理方法に関するルールを設定します。
3. 出力を作成する: 処理されたデータを最終的なメッセージにパッケージ化します。
4. 最上位フィールド: UUID、シグナル定義、ライフサイクル制御などの最上位フィールドを追加します。

データソースを指定する

テレメトリーは、SDV サービス（SDV ミドルウェア経由）と構成可能なパブリッシャー レジストリ ベースのパブリッシャーからのデータ収集をサポートしています。

• SDV サービス（pub/sub ベース）: データは VSIDL で定義された pub/sub チャネルから利用できます。

• SDV サービス（RPC ベース）: サービスが CreateSubscription または GetLatestMessage RPC を公開している場合、データを利用できます。

• 構成可能な Publisher Registry ベースのパブリッシャー: アプリケーションが Telemetry SDK の IConfigurablePublisherRegistry Android Binder インターフェースまたは構成可能な Publisher Registry ライブラリを使用して自身を登録している場合、データを利用できます。

SDV でデータを使用するには、データソース（コンセプト）を定義して data_sources 配列に追加します。

すべてのデータソース タイプですべてのオプションを使用できるわけではありません。詳細については、データソース統合ガイドをご覧ください。

source_identifier の形式

テレメトリー サービスは、複数のソース識別子形式を受け入れます。概要については、指標構成のデータソース定義をご覧ください。

MCG は、単位型名の形式を使用する場合にのみ、source_identifier から protobuf メッセージ型を推測します。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
}

ロジックと処理を定義する

ロジックは、連携して動作する 2 つのコンポーネントによって処理されます。トリガー（コンセプト）は、何かが発生するタイミングを定義します。アグリゲータ（コンセプト）は、これらのトリガーに基づいてデータを処理する方法を定義します。式（コンセプト）はトリガー条件と集計ロジックの鍵となるため、このセクションではまず式の書き方について説明します。

式

式を使用すると、人間が読める構文を使用して計算と条件を定義できます。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
  }
}

条件付きトリガー

式（コンセプト）の評価に基づいて発火します。評価を開始するには、1 つ以上の親トリガーが必要です。これは、式内のデータソースまたはアグリゲータのデータトリガー、またはデータをポーリングする定期的なトリガーであることがよくあります。

条件のタイプ

condition_type 辞書には、使用可能な条件タイプのうち 1 つだけをキーとして含める必要があります。詳細については、条件付きトリガーをご覧ください。

エッジ オプション

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 配列（コンセプト）にオブジェクトを追加します。これらの構成により、処理されたデータのパッケージ化方法と生成タイミングが決まります。1 つの指標構成で複数のレポート構成を定義して、コンポーネントを再利用できます。

レポートの生成は trigger_names フィールドを使用して制御します。また、report_initial を使用すると、構成が有効になったときにレポートを直ちに生成できます。report_incomplete を使用すると、データ収集が中断されたときに最終レポートを生成できます。

注: 処理を出力に接続するには、none 集計タイプ（@type: "none"）を使用して、Aggregator から事前計算された値を読み取ります。通常、レポートはステートレス スナップショットであるため、複雑なステートフル ロジックはアグリゲータ内に保持され、レポートはフォーマット用に予約されます。

{
  "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 には Universally Unique Identifier（UUID）が必要です。existing_uuid を指定すると、MCG はそれを使用します。指定しない場合は、ランダムに作成されます。デプロイとツール間で整合性を保つために、existing_uuid を指定します。

文字列は、英小文字のみを含む有効なハイフン付き UUID である必要があります。

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

シグナルの定義

シグナル名とタイプを検証するには、MCG が車両シグナル カタログにアクセスする必要があります。これは、VSIDL .proto 定義を含む protobuf FileDescriptorSet です（パッケージ化されて MCG にアップロードされます）。カタログの作成とアップロードの詳細については、車両シグナル カタログをご覧ください。

JSON オブジェクトの vs_version フィールドにカタログのバージョンを指定します。

"vs_version": "v1.0",

ライフサイクル トリガーを定義する

テレメトリー キャンペーンのコンテキストでは、MetricsConfig のライフサイクルによって、実際にデータが記録されるタイミングが決まります。キャンペーン管理システムがデバイスに構成をデプロイして有効にしている間、ライフサイクル トリガーを使用して、そのデプロイ内でデータを収集するタイミングを正確に制御できます。

これにより、構成を無効にすることなく、「Trip」（IgnitionOn から IgnitionOff）や「Charge Session」などの車両の使用パターンに合わせてデータの収集を調整できます。

• セッション制御（開始/一時停止）: start_trigger_name と stop_trigger_name を使用して、収集のタイミングを制御します。たとえば、車両の運転中のみデータを収集するには、開始トリガーとして IgnitionOn を、停止トリガーとして IgnitionOff を使用します。構成はデバイスでアクティブなままですが、停止トリガーが起動すると効果的に「一時停止」（収集と処理を停止）し、開始トリガーが再び起動したときにのみ再開します。

  重要: これは単に収集を一時停止するだけです。論理ウィンドウや個別のデータセットを定義したり、その他の副作用を引き起こしたりすることはありません。収集が一時停止または再開されても、アグリゲータの値はリセットされません。

• 1 回限りの検出（完了）: 構成を 1 回のみ実行し（特定の障害コードの初回発生を検出するなど）、キャンペーンが技術的にはまだ有効であっても、そのデバイスで永続的に無効にする場合は、deactivate_trigger_name を使用します。

ライフサイクルのトリガーを指定しない場合、キャンペーンで構成が有効になるとすぐにデータの収集が開始され、キャンペーンが終了するまで継続的に行われます。

上級: カスタム proto 定義

次の 2 つの主なケースでは、MCG が指標構成の説明にあるすべてのメッセージ タイプを理解するには、vs_version だけでは不十分です。

1. 型推論の失敗: source_identifier 形式で説明したように、source_identifier が FQIN またはカスタム名を使用している場合、MCG は型を推論できません。
2. カスタム メッセージ: 指標構成の説明で、vs_version で指定された VSIDL カタログにない protobuf メッセージが使用されています。これは、カスタム レポート形式の message_builder で message_type を設定するときに発生します。

このような場合は、data_source_message_types を使用して MCG が型を推測できるようにし、descriptor_protos を使用してメッセージ定義を提供します。

data_source_message_types

source_identifier 文字列を完全修飾 protobuf メッセージ タイプにマッピングします。data_source_message_types のキーは、data_sources エントリの source_identifier 値と一致する必要があります。

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

descriptor_protos

構成された vs_version にない data_source_message_types または message_builder で使用されるメッセージ タイプの定義を指定します。

descriptor_protos 配列で Base64 エンコードされた descriptorpb.FileDescriptorSet を渡します。これは、Protobuf コンパイラ protoc を使用して .proto ファイルから生成します。

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

式の構文