Referência da API

Esta página fornece documentação de referência para os endpoints da API Metrics Configuration Generator (MCG).

Visão geral dos endpoints

As seções a seguir detalham os endpoints da API disponíveis no MCG.

Configuração de métricas

• POST /api/v1/generate_metrics_config: cria uma instância MetricsConfig com base nos detalhes da solicitação de configuração de métricas.
• POST /api/v1/get_file_descriptor_set: retorna descritores de arquivo para um determinado MetricsConfig para decodificar relatórios.
• POST /api/v1/validate_metrics_config: valida o MetricsConfig transmitido, retornando uma lista de erros de validação.

Catálogos de indicadores de veículos

• POST /api/v1/vs/: cria ou atualiza o catálogo de sinais de veículos.
• GET /api/v1/vs/: lista todos os metadados do catálogo de sinais de veículos.
• DELETE /api/v1/vs/{version}: exclui o catálogo de sinais de veículos especificado.

Status do serviço

• GET /health: verifica a integridade do serviço.

Tipos de conteúdo de protobuf

Vários endpoints da API aceitam ou retornam dados no formato de buffer de protocolo (protobuf). Dois tipos de conteúdo são usados:

• application/x-protobuf: indica dados de protobuf no formato de transmissão binária. Esse formato é eficiente para comunicação entre máquinas, mas não é legível por humanos.
• text/x-protobuf: indica dados de protobuf no formato de texto, que é legível por humanos e útil para depuração ou inspeção manual.

Quando um endpoint oferece suporte a vários formatos de protobuf para uma solicitação ou resposta, use o cabeçalho Content-Type para especificar o formato dos dados da solicitação e o cabeçalho Accept para especificar o formato selecionado dos dados de resposta. Exemplo:

• -H 'Content-Type: application/x-protobuf'
• -H 'Accept: text/x-protobuf'

Chamar a API

Os exemplos nesta página usam curl para chamar a API REST e pressupõem que você definiu a variável de ambiente SERVICE_URL para se referir ao host em que o MCG está implantado. Ao executar localmente, geralmente é http://localhost:8005.

Para segmentar uma instância remota do Cloud Run, defina SERVICE_URL usando gcloud. Em seguida, anexe um cabeçalho de autorização com um token de identidade do OpenID Connect (OIDC) ao comando curl:

SERVICE_URL=$(gcloud run services describe mcg-service --region=<var label="Google Cloud region">GCP_REGION</var> --format='value(status.url)')

# Authorization header to append to curl command:
-H "Authorization: Bearer $(gcloud auth print-identity-token)"

Configuração de métricas

Esta seção descreve os endpoints para gerar e validar configurações de métricas.

POST /api/v1/generate_metrics_config

Cria uma instância MetricsConfig com base nos detalhes da solicitação de configuração de métricas. Esse processo inclui a validação e, se a geração falhar devido a violações de esquema, referências inválidas, dependências cíclicas ou outros problemas, a API retornará uma lista de detalhes do erro.

curl -H "Content-Type: application/json" \
  -H "Accept: text/x-protobuf" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v1/generate_metrics_config"
      

POST /api/v1/get_file_descriptor_set

Retorna descritores de arquivo para um determinado MetricsConfig para decodificar relatórios.

curl -H "Content-Type: application/x-protobuf" \
  -H "Accept: application/x-protobuf" \
  --data-binary @PATH_TO_METRICS_CONFIG_PB \
  "$SERVICE_URL/api/v1/get_file_descriptor_set"
      

POST /api/v1/validate_metrics_config

Valida o MetricsConfig fornecido, retornando uma lista de erros de validação.

curl -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @PATH_TO_METRICS_CONFIG_JSON \
  "$SERVICE_URL/api/v1/validate_metrics_config"
      

Catálogos de indicadores de veículos

Esta seção descreve os endpoints para gerenciar catálogos de sinais de veículos.

POST /api/v1/vs/

Cria ou atualiza o catálogo de sinais de veículos.

{
  "version": "string",
  "vehicle_signals": "string"
}

{"version": "string"}

curl -H "Content-Type: application/json" \
  --data-binary @- "$SERVICE_URL/api/v1/vs/" << EOF
{
  "version": "v1.0",
  "vehicle_signals": "VEHICLE_SIGNALS_BASE64"
}
EOF
      

GET /api/v1/vs/

Lista todos os metadados do catálogo de sinais de veículos.

{"versions": [{"version": "string"}]}

curl "$SERVICE_URL/api/v1/vs/"
      

DELETE /api/v1/vs/{version}

Exclui o catálogo de sinais de veículos especificado.

{"version": "string"}

curl --request DELETE "$SERVICE_URL/api/v1/vs/v1.0"
      

Status do serviço

Esta seção descreve os endpoints para verificar a integridade do serviço.

GET /health

Verifica a integridade do serviço.

curl "$SERVICE_URL/health"
      

Respostas de erro

Quando uma chamada de API resulta em um erro (HTTP status 4xx ou 5xx), o corpo da resposta contém um objeto de erro com a seguinte estrutura:

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "message": "Request validation failed",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "fieldName",
            "description": "error description"
          }
        ]
      }
    ]
  }
}