Catálogos de indicadores de veículos

O Metrics Configuration Generator (MCG) valida as configurações de métricas verificando nomes de indicadores, realizando a verificação de tipo em expressões e inferindo tipos de saída. O MCG precisa de acesso às definições de mensagens do buffer de protocolo (protobuf) para que os indicadores do veículo realizem essas tarefas.

No SDV, os sinais e serviços do veículo são definidos usando a linguagem de definição de interface de serviço do veículo (VSIDL, na sigla em inglês). A VSIDL usa arquivos protobuf para especificar mensagens, e esses arquivos formam a base de um catálogo de indicadores.

Para disponibilizar as definições de sinal para o MCG, é necessário empacotar esses arquivos protobuf VSIDL em um FileDescriptorSet protobuf e fazer upload dele para o serviço MCG. O MCG usa o termo Catálogo de Sinais de Veículos para esses conjuntos de definições enviados e com controle de versões (essencialmente, tornando um Catálogo de Sinais de Veículos o formulário compilado e enviado das definições de mensagens proto no seu catálogo VSIDL).

O que é um catálogo de indicadores de veículos?

Um catálogo de indicadores de veículos fornece ao MCG definições de indicadores para validação, empacotadas como um protobuf FileDescriptorSet.

No MCG, os catálogos são identificados por uma string de versão que você atribui durante o upload, o que permite gerenciar vários conjuntos distintos de definição de indicadores. Por exemplo, é possível manter diferentes versões de catálogo para versões de software (v1.0, v1.1, v2.0) ou para diferentes modelos de veículos ou configurações de hardware (suv-my2025, sedan-my2025). Cada configuração de métricas usa o campo vs_version para referenciar um catálogo específico, que define os indicadores disponíveis como fontes de dados e fornece definições de indicadores para inferência e validação de tipo.

Criar uma instância de FileDescriptorSet

Conforme descrito em Definir mensagens e serviços RPC, os indicadores do veículo são definidos como mensagens protobuf em arquivos protobuf. Se você faz parte de um projeto de SDV, use os arquivos protobuf do catálogo VSIDL do projeto para criar uma instância de FileDescriptorSet.

Para criar um catálogo para o MCG, agrupe os arquivos protobuf em um arquivo binário FileDescriptorSet usando protoc. Se todos os arquivos protobuf estiverem em uma pasta, execute o seguinte comando para gerar vehicle_signals.pb:

protoc --include_imports --descriptor_set_out=vehicle_signals.pb path/to/your/protos/*.proto

Fazer upload e gerenciar catálogos

Ao fazer upload do conjunto de definições de indicador como um catálogo, é possível referenciá-lo pelo nome da versão nas solicitações de configuração de métricas.

Adicionar ou atualizar uma versão do catálogo

Depois de gerar o arquivo de catálogo vehicle_signals.pb, é possível fazer upload dele e gerenciá-lo usando os endpoints de API MCG em /api/v2/vs/. O endpoint para adicionar ou atualizar um catálogo, POST /api/v2/vs/, exige que o FileDescriptorSet seja transmitido como uma string codificada em base64 no payload JSON.

Para codificar vehicle_signals.pb para uso da API, use o comando base64. A flag -w 0 desativa a quebra de linha para que a string codificada apareça em uma única linha:

VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

Para fazer upload de vehicle_signals.pb como uma nova versão (por exemplo, v1.0) ou para atualizar uma versão atual, envie uma solicitação POST com o conteúdo codificado em base64 para o endpoint /api/v2/vs/ com um nome de versão exclusivo.

O corpo da solicitação precisa ser um objeto JSON que contenha a string version e a string vehicle_signals codificada em base64:

{
  "version": "v1.0",
  "vehicle_signals": "Q2lSb1pYB3jCRkRt..."
}

O exemplo a seguir mostra como fazer upload de vehicle_signals.pb como versão v1.0 usando curl. O exemplo usa printf para construir o payload JSON e o canaliza para curl, o que evita a necessidade de criar um arquivo JSON contendo uma string base64 de linha única muito longa:

# 1. Encode the FileDescriptorSet to a Base64 string
VEHICLE_SIGNALS_BASE64=$(base64 -w 0 vehicle_signals.pb)

# 2. Define catalog version and build JSON payload
VERSION="v1.0"
JSON_PAYLOAD=$(jq -n --arg v "$VERSION" --arg d "$VEHICLE_SIGNALS_BASE64" \
  '{version: $v, vehicle_signals: $d}')

# 3. POST the data to the API endpoint
echo "$JSON_PAYLOAD" | curl -H "Content-Type: application/json" --data-binary @- "$SERVICE_URL/api/v2/vs/"

Listar e excluir versões

É possível listar todas as versões disponíveis do catálogo ou excluir uma versão específica:

• Listar versões: para ver uma lista de identificadores de todas as versões de catálogo enviadas, envie uma solicitação GET para /api/v2/vs/. Consulte GET /api/v2/vs/.

• Excluir uma versão: para remover um catálogo, envie uma solicitação DELETE para /api/v2/vs/{version}, em que {version} é o identificador fornecido quando o catálogo foi enviado (por exemplo, v1.0). Consulte DELETE /api/v2/vs/{version}.

Para detalhes completos sobre todos os endpoints, consulte a Referência da API.

Usar um catálogo em configurações de métricas

Depois de fazer o upload, use o campo vs_version para referenciar uma versão do catálogo nas configurações de métricas:

{ "vs_version": "v1.0", ... }

Quando esse objeto JSON é enviado para os endpoints /api/v2/generate_metrics_config ou /api/v2/validate_metrics_config, o MCG usa as definições de sinal do catálogo v1.0 para realizar a validação e a inferência de tipo.