O gerador de configuração de métricas (MCG, na sigla em inglês) valida as configurações de métricas verificando nomes de indicadores, realizando a verificação de tipos em expressões e inferindo tipos de saída. O MCG precisa acessar as definições de mensagens de 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). O 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 indicadores ao MCG, empacote esses arquivos protobuf VSIDL
em um protobuf FileDescriptorSet e faça upload dele no serviço
do 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ão. Essencialmente, um catálogo de sinais de veículos é a forma compilada e enviada 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 sinais de veículo (VSC, na sigla em inglês) fornece ao MCG definições de sinais para validação,
empacotadas como um protobuf FileDescriptorSet.
No MCG, os catálogos são identificados por uma string de versão atribuída durante o upload, o que permite gerenciar vários conjuntos de definição de indicadores distintos. Por
exemplo, você pode manter diferentes versões de catálogo para lançamentos 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 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 seus 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 <var label="path to folder with .proto files">path/to/your/protos</var>/*.proto
Fazer upload e gerenciar catálogos
Ao fazer upload do conjunto de definições de indicadores como um catálogo, você pode fazer referência a ele pelo nome da versão em 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, faça upload e
gerencie-o usando os endpoints da API MCG em /api/v1/vs/. O endpoint para adicionar ou atualizar um catálogo, POST /api/v1/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
atualizar uma versão atual, envie uma solicitação POST com o conteúdo
codificado em base64 para o endpoint /api/v1/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 direciona
para curl, o que evita a necessidade de criar um arquivo JSON com 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="<var label="catalog version">v1.0</var>"
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/v1/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 conferir uma lista de identificadores de todas as versões do catálogo enviadas, envie uma solicitação
GETpara/api/v1/vs/. Consulte GET /api/v1/vs/.Excluir uma versão: para remover um catálogo, envie uma solicitação
DELETEpara/api/v1/vs/{version}, em que{version}é o identificador fornecido quando o catálogo foi enviado (por exemplo,v1.0). Consulte DELETE /api/v1/vs/{version}.
Para mais detalhes sobre todos os endpoints, consulte a referência da API.
Usar um catálogo nas configurações de métricas
Ao fazer upload, referencie uma versão do catálogo nas configurações de métricas usando o campo vs_version:
{ "vs_version": "v1.0", ... }
Quando esse objeto JSON é enviado aos endpoints /api/v1/generate_metrics_config ou /api/v1/validate_metrics_config, o MCG usa as definições de indicadores do catálogo v1.0 para realizar a validação e a inferência de tipo.