Descrição dos campos do ASMGrpcJsonTranscoder - Alibaba Cloud Service Mesh: Central de Documentação do Alibaba Cloud

O ASMGrpcJsonTranscoder é uma Custom Resource Definition (CRD) no Alibaba Cloud Service Mesh (ASM) que transcodifica entre HTTP/JSON e gRPC/Protobuf. Implante esta CRD para expor serviços gRPC como endpoints HTTP RESTful e permitir que clientes HTTP os chamem sem um cliente gRPC dedicado.

Configuração completa

O YAML a seguir mostra todos os campos configuráveis em um recurso ASMGrpcJsonTranscoder:

workloadSelector:
  <label-key>: <label-value>        # Required. Labels to select target pods.
isGateway: false                     # Optional. Apply to gateway instead of sidecars.
portNumber: <service-port>           # Required. Service port for transcoding.
services:                            # Required. gRPC services in {package}.{service} format.
  - '<package-name>.<service-name>'
protoDescriptorBin: <base64-string>  # Required. Base64-encoded proto descriptor set.
transcodeFirst: false                # Optional. Transcode before other filter processing.
convertGrpcStatus: false             # Optional. Convert gRPC errors to JSON responses.
ignoredQueryParameters:              # Optional. Specific query params to skip.
  - <param-name>
ignoreUnknownQueryParameters: <bool>  # Optional. Skip all unmapped query params.

Campos

Campo	Tipo	Obrigatório	Descrição
workloadSelector	map<string, string>	Sim	Rótulos que selecionam os pods onde esta configuração entra em vigor. O escopo dos rótulos limita-se ao namespace do recurso. Para mais informações, consulte Workload Selector.
isGateway	bool	Não	Aplica a configuração a um gateway. Padrão: `false`.
portNumber	int	Sim	Porta do serviço a transcodificar. Se `isGateway` for `true`, especifique a porta do serviço (como `8080`) que executa a transcodificação no gateway.
services	string[]	Sim	Serviços gRPC declarados no arquivo proto, no formato `{package name}.{service name}`. Consulte a seção Formato de serviços abaixo.
protoDescriptorBin	string	Sim	Conteúdo codificado em Base64 do arquivo de conjunto de descritores proto. Consulte a seção Gerar um descritor proto abaixo.
transcodeFirst	bool	Não	Transcodifica requisições HTTP antes de outros processamentos. Padrão: `false`. Consulte a seção Ordem de transcodificação abaixo.
convertGrpcStatus	bool	Não	Converte o status de erro gRPC em um corpo de resposta JSON. Padrão: `false`. Consulte a seção Conversão de status gRPC abaixo.
ignoredQueryParameters	[]string	Não	Parâmetros de query a ignorar durante o mapeamento do método de transcodificação. Use quando souber exatamente quais parâmetros excluir. Consulte a seção Tratamento de parâmetros de query abaixo.
ignoreUnknownQueryParameters	bool	Não	Ignora todos os parâmetros de query não mapeáveis a campos protobuf. Recomendado quando não for possível prever os parâmetros presentes na requisição. Consulte a seção Tratamento de parâmetros de query abaixo.

Detalhes dos campos

Formato de serviços

Especifique cada serviço gRPC no formato {package name}.{service name}, correspondendo às definições no seu arquivo proto:

services:
  - 'helloworld.Greeter'

Gerar um descritor proto

O campo protoDescriptorBin exige um conjunto de descritores proto codificado em Base64. Gere-o seguindo os passos abaixo:

Clone o repositório googleapis, que contém as anotações proto necessárias:

   git clone https://github.com/googleapis/googleapis
   GOOGLEAPIS_DIR=<path-to-local-googleapis-folder>

Execute o protoc para gerar o conjunto de descritores:

   protoc -I${GOOGLEAPIS_DIR} -I. \
     --include_imports \
     --include_source_info \
     --descriptor_set_out=proto.pb \
     your_service.proto

Codifique o arquivo de saída em Base64 e use o resultado como valor de protoDescriptorBin:
```
   base64 -w 0 proto.pb
```

Ordem de transcodificação

Quando transcodeFirst está definido como true, as requisições HTTP de entrada são transcodificadas para gRPC antes de qualquer outro processamento de filtro. Isso afeta recursos de controle de tráfego baseados em requisição, como autorização externa.

Por exemplo, quando uma requisição passa por um serviço personalizado de autorização externa:

transcodeFirst: true -- O serviço de autorização recebe uma requisição gRPC.
transcodeFirst: false (padrão) -- O serviço de autorização recebe uma requisição HTTP.

Conversão de status gRPC

Se convertGrpcStatus estiver definido como true e o serviço upstream retornar um erro gRPC sem corpo HTTP, o transcodificador converterá o status gRPC em uma resposta JSON:

O transcodificador verifica o cabeçalho grpc-status-details-bin, que contém uma mensagem protobuf google.rpc.Status codificada em Base64.
Caso o cabeçalho exista, a mensagem é decodificada e retornada como corpo JSON.
Na ausência do cabeçalho, uma mensagem google.rpc.Status é gerada a partir dos cabeçalhos grpc-status e grpc-message.

Exemplo:

Um serviço upstream retorna os seguintes cabeçalhos gRPC:

grpc-status: 5
grpc-status-details-bin: CAUaMwoqdHlwZS5nb29nbGVhcGlzLmNvbS9nb29nbGUucnBjLlJlcXVlc3RJbmZvEgUKA3ItMQ

O transcodificador converte isso na seguinte resposta HTTP/JSON:

HTTP/1.1 404 Not Found
content-type: application/json

{
  "code": 5,
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.RequestInfo",
      "requestId": "r-1"
    }
  ]
}

Tratamento de parâmetros de query

Por padrão, o transcodificador rejeita requisições com parâmetros de query desconhecidos ou inválidos. Dois campos controlam esse comportamento:

Campo	Quando usar
`ignoredQueryParameters`	Use quando souber exatamente quais parâmetros extras permitir. Liste-os explicitamente.
`ignoreUnknownQueryParameters`	Adequado para cenários em que não é possível prever os parâmetros extras da requisição. Defina como `true` para permitir todos os parâmetros não mapeados.

Importante

Se ignoredQueryParameters e ignoreUnknownQueryParameters estiverem configurados simultaneamente, ignoredQueryParameters será ignorado. Use apenas um dos dois campos.

Alibaba Cloud Service Mesh:Referência de campos do ASMGrpcJsonTranscoder