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

このガイドでは、Metrics Configuration Generator（MCG）ツールの /api/v2/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 を公開している場合、データを利用できます。

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

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

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

source_identifier の形式

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

MCG は、ユニットタイプ名形式を使用している場合にのみ、source_identifier から protobuf メッセージ タイプを推測します。FQIN またはカスタム名（構成可能なパブリッシャー レジストリから）を使用すると、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 定義（パッケージ化されて MCG にアップロードされたもの）を含む protobuf FileDescriptorSet です。カタログの作成とアップロードの詳細については、車両信号カタログをご覧ください。

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

"vs_version": "v1.0",

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

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

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

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

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

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

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

高度な機能: カスタム proto 定義

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

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 で使用されるメッセージ タイプの定義を指定します。

base64 でエンコードされた descriptorpb.FileDescriptorSet を descriptor_protos 配列に渡します。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": "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
}

入力: データソースとアグリゲータ

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

式の構文