Referência da API

Nesta página, você encontra a 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 de API disponíveis no MCG.

Configuração de métricas

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

Catálogos de indicadores de veículos

• POST /api/v2/vs/: criar um novo catálogo de indicadores de veículos ou atualizar um atual.
• GET /api/v2/vs/: lista todos os metadados do catálogo de indicadores de veículos.
• DELETE /api/v2/vs/{version}: exclui o catálogo de indicadores de veículos especificado.

Status do serviço

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

Tipos de conteúdo do Protobuf

Vários endpoints de 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 protobuf no formato de transmissão binário. 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 aceita 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 da 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 presumem 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:

SERVICE_URL=$(gcloud run services describe mcg-service \
  --region=GCP_REGION \
  --format='value(status.url)')

Ao chamar endpoints remotos do Cloud Run, anexe o seguinte cabeçalho de autorização aos comandos curl:

-H "Authorization: Bearer $(gcloud auth print-identity-token)"

Configuração de métricas

Nesta seção, descrevemos os endpoints para gerar e validar configurações de métricas.

POST /api/v2/generate_metrics_config

Crie uma instância MetricsConfig com base nos detalhes da solicitação de configuração de métricas. Esse processo inclui a validação. Se a geração falhar devido a violações de esquema, referências inválidas, dependências cíclicas ou outros problemas, a API vai 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/v2/generate_metrics_config"
      

POST /api/v2/get_file_descriptor_set

Retorna descritores do 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/v2/get_file_descriptor_set"
      

POST /api/v2/validate_metrics_config

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

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

Catálogos de indicadores de veículos

Nesta seção, descrevemos os endpoints para gerenciar catálogos de indicadores de veículos.

POST /api/v2/vs/

Crie um novo catálogo de indicadores de veículos ou atualize um atual.

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

{"version": "string"}

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

GET /api/v2/vs/

Liste todos os metadados do catálogo de indicadores de veículos.

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

curl "$SERVICE_URL/api/v2/vs/"
      

DELETE /api/v2/vs/{version}

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

{"version": "string"}

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

Status do serviço

Nesta seção, descrevemos os endpoints para verificar o Service Health.

GET /health

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