REST Resource: projects.locations.grpcRoutes

Recurso: GrpcRoute

GrpcRoute é o recurso que define como o tráfego gRPC encaminhado por um recurso de malha ou gateway é encaminhado.

Representação JSON 
{
  "name": string,
  "selfLink": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "description": string,
  "hostnames": [
    string
  ],
  "meshes": [
    string
  ],
  "gateways": [
    string
  ],
  "rules": [
    {
      object (RouteRule)
    }
  ]
}
Campos
name

string

Identificador. Nome do recurso GrpcRoute. Corresponde ao padrão projects/*/locations/global/grpcRoutes/<grpc_route_name>
createTime

string (Timestamp format)

Apenas saída. A data/hora em que o recurso foi criado.

Usa RFC 3339, em que o resultado gerado é sempre normalizado em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Também são aceites desvios diferentes de "Z". Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Apenas saída. A data/hora em que o recurso foi atualizado.

Usa RFC 3339, em que o resultado gerado é sempre normalizado em Z e usa 0, 3, 6 ou 9 dígitos fracionários. Também são aceites desvios diferentes de "Z". Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
labels

map (key: string, value: string)

Opcional. Conjunto de etiquetas associadas ao recurso GrpcRoute.

Um objeto que contém uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
description

string

Opcional. Uma descrição de texto livre do recurso. Comprimento máximo de 1024 carateres.
hostnames[]

string

Obrigatório. Nomes de anfitriões de serviços com uma porta opcional para a qual esta rota descreve o tráfego.

Formato: [:]

O nome do anfitrião é o nome do domínio totalmente qualificado de um anfitrião de rede. Isto corresponde à definição RFC 1123 de um nome de anfitrião com 2 exceções notáveis: - Os IPs não são permitidos. – Um nome de anfitrião pode ser precedido de uma etiqueta de caráter universal (*.). A etiqueta de caráter universal tem de aparecer sozinha como a primeira etiqueta.

O nome do anfitrião pode ser "preciso", que é um nome de domínio sem o ponto final de um anfitrião de rede (por exemplo, foo.example.com) ou "caráter universal", que é um nome de domínio precedido de uma única etiqueta de caráter universal (por exemplo, *.example.com).

Tenha em atenção que, de acordo com a RFC1035 e a RFC1123, uma etiqueta tem de consistir em carateres alfanuméricos em minúsculas ou "-" e tem de começar e terminar com um caráter alfanumérico. Não é permitida outra pontuação.

As rotas associadas a uma malha ou um gateway têm de ter nomes de anfitrião exclusivos. Se tentar anexar várias rotas com nomes de anfitrião em conflito, a configuração é rejeitada.

Por exemplo, embora seja aceitável que os trajetos para os nomes de anfitrião *.foo.bar.com e *.bar.com estejam associados ao mesmo trajeto, não é possível associar dois trajetos a *.bar.com ou a bar.com.

Se for especificada uma porta, os clientes gRPC têm de usar o URI do canal com a porta para corresponder a esta regra (ou seja, "xds:///service:123"). Caso contrário, têm de fornecer o URI sem uma porta (ou seja, "xds:///service").
meshes[]

string

Opcional. Meshes define uma lista de malhas às quais esta GrpcRoute está anexada, como uma das regras de encaminhamento para encaminhar os pedidos processados pela malha.

Cada referência de malha deve corresponder ao padrão: projects/*/locations/global/meshes/<mesh_name>
gateways[]

string

Opcional. Gateways define uma lista de gateways aos quais esta GrpcRoute está anexada, como uma das regras de encaminhamento para encaminhar os pedidos processados pelo gateway.

Cada referência de gateway deve corresponder ao padrão: projects/*/locations/global/gateways/<gateway_name>
rules[]

object (RouteRule)

Obrigatório. Uma lista de regras detalhadas que definem como encaminhar o tráfego.

Num único GrpcRoute, o GrpcRoute.RouteAction associado ao primeiro GrpcRoute.RouteRule correspondente é executado. Tem de fornecer, pelo menos, uma regra.

RouteRule

Descreve como encaminhar o tráfego.

Representação JSON 
{
  "matches": [
    {
      object (RouteMatch)
    }
  ],
  "action": {
    object (RouteAction)
  }
}
Campos
matches[]

object (RouteMatch)

Opcional. As correspondências definem as condições usadas para fazer corresponder a regra com os pedidos gRPC recebidos. Cada correspondência é independente, ou seja, esta regra vai ter correspondência se QUALQUER uma das correspondências for satisfeita. Se não for especificado nenhum campo de correspondências, esta regra vai corresponder incondicionalmente ao tráfego.
action

object (RouteAction)

Obrigatório. Uma regra detalhada que define como encaminhar o tráfego. Este campo é obrigatório.

RouteMatch

Critérios para fazer corresponder o tráfego. Uma RouteMatch é considerada uma correspondência quando todos os campos fornecidos correspondem.

Representação JSON 
{
  "headers": [
    {
      object (HeaderMatch)
    }
  ],
  "method": {
    object (MethodMatch)
  }
}
Campos
headers[]

object (HeaderMatch)

Opcional. Especifica uma coleção de cabeçalhos a corresponder.
method

object (MethodMatch)

Opcional. Um método gRPC para fazer a correspondência. Se este campo estiver vazio ou for omitido, corresponde a todos os métodos.

MethodMatch

Especifica uma correspondência com um método.

Representação JSON 
{
  "type": enum (Type),
  "grpcService": string,
  "grpcMethod": string,
  "caseSensitive": boolean
}
Campos
type

enum (Type)

Opcional. Especifica como fazer a correspondência com o nome. Se não for especificado, é usado um valor predefinido de "EXACT".
grpcService

string

Obrigatório. Nome do serviço a comparar. Se não for especificado, corresponde a todos os serviços.
grpcMethod

string

Obrigatório. Nome do método a comparar. Se não for especificado, corresponde a todos os métodos.
caseSensitive

boolean

Opcional. Especifica que as correspondências são sensíveis a maiúsculas e minúsculas. O valor predefinido é verdadeiro. caseSensitive não pode ser usado com um tipo de REGULAR_EXPRESSION.

Tipo

O tipo de correspondência.

Enumerações
TYPE_UNSPECIFIED Não especificado.
EXACT Só corresponde ao nome exato indicado.
REGULAR_EXPRESSION Interpreta grpcMethod e grpcService como expressões regulares. A sintaxe RE2 é suportada.

HeaderMatch

Uma correspondência com uma coleção de cabeçalhos.

Representação JSON 
{
  "type": enum (Type),
  "key": string,
  "value": string
}
Campos
type

enum (Type)

Opcional. Especifica como fazer a correspondência com o valor do cabeçalho. Se não for especificado, é usado um valor predefinido de EXACT.
key

string

Obrigatório. A chave do cabeçalho.
value

string

Obrigatório. O valor do cabeçalho.

Tipo

O tipo de correspondência.

Enumerações
TYPE_UNSPECIFIED Não especificado.
EXACT Só corresponde ao valor exato fornecido.
REGULAR_EXPRESSION Corresponde a caminhos em conformidade com o prefixo especificado pelo valor. A sintaxe RE2 é suportada.

RouteAction

Especifica como encaminhar o tráfego correspondente.

Representação JSON 
{
  "destinations": [
    {
      object (Destination)
    }
  ],
  "faultInjectionPolicy": {
    object (FaultInjectionPolicy)
  },
  "timeout": string,
  "retryPolicy": {
    object (RetryPolicy)
  },
  "statefulSessionAffinity": {
    object (StatefulSessionAffinityPolicy)
  },
  "idleTimeout": string
}
Campos
destinations[]

object (Destination)

Opcional. Os serviços de destino para os quais o tráfego deve ser encaminhado. Se forem especificados vários destinos, o tráfego é dividido entre os serviços de back-end de acordo com o campo de ponderação destes destinos.
faultInjectionPolicy

object (FaultInjectionPolicy)

Opcional. A especificação para a injeção de falhas introduzida no tráfego para testar a capacidade de recuperação dos clientes em caso de falha do serviço de destino. Como parte da injeção de falhas, quando os clientes enviam pedidos para um destino, podem ser introduzidos atrasos numa percentagem de pedidos antes de enviar esses pedidos para o serviço de destino. Da mesma forma, os pedidos dos clientes podem ser anulados para uma percentagem de pedidos.

O timeout e a retryPolicy são ignorados pelos clientes configurados com uma faultInjectionPolicy
timeout

string (Duration format)

Opcional. Especifica o limite de tempo para o trajeto selecionado. O tempo limite é calculado a partir do momento em que o pedido é totalmente processado (ou seja, o fim da transmissão) até que a resposta seja totalmente processada. O tempo limite inclui todas as novas tentativas.

Uma duração em segundos com até nove dígitos fracionários, que termina com "s". Exemplo: "3.5s".
retryPolicy

object (RetryPolicy)

Opcional. Especifica a política de repetição associada a esta rota.
statefulSessionAffinity

object (StatefulSessionAffinityPolicy)

Opcional. Especifica a afinidade de sessão com estado baseada em cookies.
idleTimeout

string (Duration format)

Opcional. Especifica o limite de tempo de inatividade para o trajeto selecionado. O limite de tempo de inatividade é definido como o período em que não são enviados nem recebidos bytes na ligação a montante ou a jusante. Se não estiver definido, o tempo limite de inatividade predefinido é de 1 hora. Se for definido como 0 s, o limite de tempo é desativado.

Uma duração em segundos com até nove dígitos fracionários, que termina com "s". Exemplo: "3.5s".

Destino

O destino para o qual o tráfego vai ser encaminhado.

Representação JSON 
{

  // Union field destination_type can be only one of the following:
  "serviceName": string
  // End of list of possible types for union field destination_type.
  "weight": integer
}
Campos
Campo de união destination_type. Especifica o tipo de destino para o qual o tráfego vai ser encaminhado. destination_type só pode ser uma das seguintes opções:
serviceName

string

Obrigatório. O URL de um serviço de destino para o qual encaminhar tráfego. Tem de fazer referência a um BackendService ou a um ServiceDirectoryService.
weight

integer

Opcional. Especifica a proporção de pedidos encaminhados para o back-end referenciado pelo campo serviceName. Este valor é calculado da seguinte forma: - peso/Soma(pesos nesta lista de destinos). Para valores diferentes de zero, pode haver algum épsilon da proporção exata definida aqui, consoante a precisão suportada por uma implementação.

Se for especificado apenas um serviceName e tiver um peso superior a 0, 100% do tráfego é encaminhado para esse back-end.

Se forem especificados pesos para qualquer nome de serviço, têm de ser especificados para todos.

Se os pesos não forem especificados para todos os serviços, o tráfego é distribuído em proporções iguais por todos eles.

FaultInjectionPolicy

A especificação para a injeção de falhas introduzida no tráfego para testar a capacidade de recuperação dos clientes em caso de falha do serviço de destino. Como parte da injeção de falhas, quando os clientes enviam pedidos para um destino, podem ser introduzidos atrasos numa percentagem de pedidos antes de enviar esses pedidos para o serviço de destino. Da mesma forma, os pedidos dos clientes podem ser anulados para uma percentagem de pedidos.

Representação JSON 
{
  "delay": {
    object (Delay)
  },
  "abort": {
    object (Abort)
  }
}
Campos
delay

object (Delay)

A especificação para injetar um atraso nos pedidos do cliente.
abort

object (Abort)

A especificação para anular pedidos de clientes.

Atraso

Especificação de como os pedidos do cliente são atrasados como parte da injeção de falhas antes de serem enviados para um destino.

Representação JSON 
{
  "fixedDelay": string,
  "percentage": integer
}
Campos
fixedDelay

string (Duration format)

Especifique um atraso fixo antes de encaminhar o pedido.

Uma duração em segundos com até nove dígitos fracionários, que termina com "s". Exemplo: "3.5s".
percentage

integer

A percentagem de tráfego na qual o atraso vai ser injetado.

O valor tem de estar compreendido entre [0 e 100]

Interromper

Especificação de como os pedidos do cliente são anulados como parte da injeção de falhas antes de serem enviados para um destino.

Representação JSON 
{
  "httpStatus": integer,
  "percentage": integer
}
Campos
httpStatus

integer

O código de estado HTTP usado para anular o pedido.

O valor tem de estar entre 200 e 599, inclusive.
percentage

integer

A percentagem de tráfego que vai ser anulada.

O valor tem de estar compreendido entre [0 e 100]

RetryPolicy

As especificações para novas tentativas. Especifica uma ou mais condições às quais esta regra de repetição se aplica. Os valores válidos são:

Representação JSON 
{
  "retryConditions": [
    string
  ],
  "numRetries": integer
}
Campos
retryConditions[]

string

  • connect-failure: o router vai tentar novamente em caso de falhas de ligação aos serviços de backend, por exemplo, devido a limites de tempo de ligação.
  • refused-stream: o router vai tentar novamente se o serviço de back-end repuser a stream com um código de erro REFUSED_STREAM. Este tipo de reposição indica que é seguro tentar novamente.
  • cancelled: o router vai tentar novamente se o código de estado gRPC no cabeçalho da resposta estiver definido como cancelled
  • deadline-exceeded: o router vai tentar novamente se o código de estado gRPC no cabeçalho de resposta estiver definido como deadline-exceeded
  • resource-exhausted: o router vai tentar novamente se o código de estado gRPC no cabeçalho de resposta estiver definido como resource-exhausted
  • indisponível: o router vai tentar novamente se o código de estado gRPC no cabeçalho da resposta estiver definido como indisponível
numRetries

integer (uint32 format)

Especifica o número permitido de novas tentativas. Este número tem de ser > 0. Se não for especificado, a predefinição é 1.

StatefulSessionAffinityPolicy

A especificação para a afinidade de sessão com estado baseada em cookies, em que o plano de dados fornece um "cookie de sessão" com o nome "GSSA" que codifica um anfitrião de destino específico e cada pedido que contenha esse cookie é direcionado para esse anfitrião, desde que o anfitrião de destino permaneça ativo e em bom estado.

A biblioteca de malha sem proxy gRPC ou o proxy sidecar vai gerir o cookie de sessão, mas o código da aplicação cliente é responsável por copiar o cookie de cada RPC na sessão para a seguinte.

Representação JSON 
{
  "cookieTtl": string
}
Campos
cookieTtl

string (Duration format)

Obrigatório. O valor TTL do cookie para o cabeçalho Set-Cookie gerado pelo plano de dados. A duração do cookie pode ser definida para um valor entre 1 e 86 400 segundos (24 horas), inclusive.

Uma duração em segundos com até nove dígitos fracionários, que termina com "s". Exemplo: "3.5s".

Métodos

create

 Cria uma nova GrpcRoute num determinado projeto e localização.

delete

 Elimina um único GrpcRoute.

get

 Obtém detalhes de um único GrpcRoute.

list

 Apresenta GrpcRoutes num determinado projeto e localização.

patch

 Atualiza os parâmetros de uma única GrpcRoute.