측정항목 구성 생성 요청 JSON 형식

이 가이드에서는 측정항목 구성 생성기 (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 인터페이스 또는 원격 분석 SDK의 구성 가능한 게시자 레지스트리 라이브러리를 사용하여 자체 등록하는 경우 데이터를 사용할 수 있습니다.

SDV에서 데이터를 사용하려면 데이터 소스 (개념)를 정의하고 data_sources 배열에 추가합니다.

일부 옵션은 특정 데이터 소스 유형에서만 사용할 수 있습니다. 자세한 내용은 데이터 소스 통합 가이드를 참고하세요.

source_identifier 형식

원격 분석 서비스는 여러 소스 식별자 형식을 허용합니다. 개요는 측정항목 구성의 데이터 소스 정의를 참고하세요.

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
}

로직 및 처리 정의

로직은 함께 작동하는 두 가지 구성요소에 의해 처리됩니다. 트리거 (개념)는 이벤트가 발생하는 시점을 정의합니다. 애그리게이터 (개념)는 이러한 트리거를 기반으로 데이터가 처리되는 방식을 정의합니다. 표현식 (개념)은 트리거 조건 및 집계 로직의 핵심이므로 이 섹션에서는 먼저 표현식을 작성하는 방법을 설명합니다.

표현식

표현식을 사용하면 인간이 읽을 수 있는 문법을 사용하여 계산 및 조건을 정의할 수 있습니다. 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
  }
}

조건부 트리거

표현식 (개념) 평가를 기반으로 실행됩니다. 평가를 시작하려면 하나 이상의 상위 트리거가 필요합니다. 이는 표현식의 데이터 소스 또는 애그리게이터에 대한 데이터 트리거이거나 데이터를 폴링하는 주기적인 트리거인 경우가 많습니다.

조건 유형

condition_type 사전에는 사용 가능한 조건 유형 중 하나만 키로 포함되어야 합니다. 자세한 내용은 조건부 트리거를 참조하세요.

에지 옵션

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

애그리게이터: 데이터 처리 방식 정의

스테이트풀(Stateful) 중간 데이터 처리에 애그리게이터를 사용합니다(개념). 애그리게이터를 정의하고 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 배열 (개념)에 객체를 추가합니다. 이러한 구성은 처리된 데이터가 패키징되는 방식과 생성되는 시점을 결정합니다. 하나의 측정항목 구성에서 여러 보고서 구성을 정의하여 구성요소를 재사용할 수 있습니다.

trigger_names 필드를 사용하여 보고서 생성을 제어합니다. 또한 report_initial를 사용하여 구성이 활성화될 때 즉시 보고서를 생성하고 report_incomplete를 사용하여 데이터 수집이 중단될 때 최종 보고서를 생성할 수 있습니다.

참고: 처리를 출력에 연결하려면 none 집계 유형(@type: "none")을 사용하여 Aggregator에서 미리 계산된 값을 읽습니다. 보고서는 일반적으로 스테이트리스(Stateless) 스냅샷이므로 복잡한 스테이트풀(Stateful) 로직을 애그리게이터 내에 유지하고 보고서를 형식 지정용으로 예약합니다.

{
  "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에는 범용 고유 식별자 (UUID)가 필요합니다. existing_uuid를 제공하면 MCG에서 이를 사용합니다. 그렇지 않으면 임의의 ID가 생성됩니다. 배포 및 도구 간의 일관성을 위해 existing_uuid를 지정합니다.

문자열은 소문자만 포함하는 유효한 하이픈으로 연결된 UUID여야 합니다.

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

신호 정의

신호 이름과 유형을 검증하려면 MCG에 차량 신호 카탈로그에 대한 액세스 권한이 필요합니다. VSIDL .proto 정의가 포함된 protobuf FileDescriptorSet입니다 (패키징되어 MCG에 업로드됨). 카탈로그를 만들고 업로드하는 방법에 관한 자세한 내용은 차량 신호 카탈로그를 참고하세요.

JSON 객체의 vs_version 필드에 카탈로그 버전을 지정합니다.

"vs_version": "v1.0",

수명 주기 트리거 정의

원격 분석 캠페인의 맥락에서 MetricsConfig의 수명 주기는 데이터가 실제로 기록되는 시점을 결정합니다. 캠페인 관리 시스템이 기기에 구성을 배포하고 활성화하는 동안 수명 주기 트리거를 사용하여 해당 배포 내에서 데이터가 수집되는 시점을 정확하게 제어할 수 있습니다.

이렇게 하면 구성을 비활성화할 필요 없이 '이동' (IgnitionOn~IgnitionOff) 또는 '충전 세션'과 같은 차량 사용 패턴에 맞춰 데이터 수집을 조정할 수 있습니다.

• 세션 제어 (시작/일시중지): start_trigger_name 및 stop_trigger_name를 사용하여 수집 시점을 제어합니다. 예를 들어 차량이 주행 중일 때만 데이터를 수집하려면 IgnitionOn를 시작 트리거로, IgnitionOff를 중지 트리거로 사용합니다. 구성은 기기에서 활성 상태로 유지되지만 중지 트리거가 실행되면 효과적으로 '일시중지' (수집 및 처리 중지)되고 시작 트리거가 다시 실행될 때만 재개됩니다.

  중요: 이 작업은 수집을 일시중지할 뿐입니다. 논리적 기간, 별도의 데이터 세트를 정의하지 않으며 다른 부작용도 없습니다. 수집이 일시중지되거나 재개될 때 애그리게이터 값은 재설정되지 않습니다.

• 일회성 감지 (완료): 구성이 한 번만 실행되어야 하고 (예: 특정 오류 코드의 첫 번째 발생 감지) 캠페인이 기술적으로 여전히 활성 상태인 경우에도 해당 기기에서 영구적으로 비활성화되어야 하는 경우 deactivate_trigger_name를 사용합니다.

수명 주기 트리거를 지정하지 않으면 캠페인에서 구성을 활성화할 때 데이터 수집이 즉시 시작되고 캠페인이 종료될 때까지 계속됩니다.

고급: 커스텀 프로토 정의

다음 두 가지 주요 사례에서는 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

data_source_message_types 또는 message_builder에 사용된 메시지 유형 중 구성된 vs_version에 없는 메시지 유형의 정의를 제공합니다.

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

표현식 구문