How to configure backend routing plug-ins - API Gateway: Central de Documentação do Alibaba Cloud

Como funciona

O API Gateway avalia as regras de roteamento em ordem. A primeira regra cuja condição corresponder à requisição determina o backend. Se nenhuma regra corresponder, a requisição seguirá para o backend padrão definido na API.

Cada regra de roteamento especifica:

Uma condition que a requisição deve atender
Um backend de destino para as requisições correspondentes
(Opcional) Um weight para distribuir o tráfego entre vários backends correspondentes
(Opcional) Constant parameters para anexar à requisição antes do encaminhamento

Casos de uso

Cenário	Como funciona	Abordagem de configuração
Roteamento multilocatário	Encaminha chamadores VIP para clusters de servidores dedicados	Use `$CaAppId` para rotear para um backend VPC
Roteamento baseado em ambiente	Direciona requisições de estágio de teste para um servidor de testes	Use `$CaStage` para substituir a URL do backend
Implantação blue-green	Divide o tráfego entre versões estáveis e novas	Atribua pesos a várias rotas com condições `1 = 1`
Hashing consistente	Fixa requisições do mesmo IP ou com o mesmo parâmetro em um único backend	Defina `routeByHash` com um fator de hash

Formato de configuração

Os plug-ins aceitam JSON ou YAML. Ambos os formatos compartilham o mesmo esquema e permitem conversão mútua.

O modelo YAML a seguir mostra a estrutura básica:

---
routes:
  # Route VIP callers to a dedicated VPC backend
  - name: Vip
    condition: "$CaAppId = 123456"
    backend:
      type: "HTTP-VPC"
      vpcAccessName: "slbAccessForVip"

  # Return a mock response for outdated clients
  - name: MockForOldClient
    condition: "$ClientVersion < '2.0.5'"
    backend:
      type: "MOCK"
      statusCode: 400
      body: "This version is not supported!!!"

Objeto Route

Campo	Obrigatório	Descrição
`name`	Sim	Nome exclusivo dentro do plug-in. Aceita apenas letras e dígitos. Quando uma requisição corresponde a esta regra, o API Gateway adiciona um cabeçalho `X-Ca-Routing-Name` com este valor.
`condition`	Sim	Expressão condicional que determina se uma requisição corresponde a esta regra. As regras são avaliadas em ordem; a primeira correspondência prevalece. Consulte Expressões condicionais.
`backend`	Sim	Configuração de backend que substitui o backend padrão da API. Deve estar em conformidade com a especificação OpenAPI do API Gateway. Uma configuração incompleta retorna `X-Ca-Error-Code: I504RB`. Consulte Tipos de backend.
`constant-parameters`	Não	Parâmetros constantes personalizados anexados à requisição antes do encaminhamento. Cada parâmetro requer `name`, `location` (`header` ou `query`) e `value`.
`weight`	Não	Peso de tráfego para esta rota. Usado quando várias rotas correspondem. Consulte Distribuição ponderada de tráfego.

Expressões condicionais

Sintaxe

As expressões condicionais usam sintaxe semelhante a SQL:

$ParamName = 'value' and $AnotherParam = 'value'

Regras:

Prefixe cada parâmetro com $. Referencie qualquer parâmetro de requisição definido na API (modo MAPPING ou PASSTHROUGH).
Combine expressões com and e or. Use parênteses () para controlar a precedência.
Um parâmetro inexistente em uma condição é avaliado como false.

Tipos de dados suportados:

Tipo	Descrição	Exemplo
STRING	Coloque entre aspas simples ou duplas	`'Hello'`, `"Hello"`
INTEGER	Valores inteiros	`1001`, `-1`
NUMBER	Valores de ponto flutuante	`0.1`, `100.0`
BOOLEAN	Valores booleanos	`true`, `false`

Parâmetros do sistema

Referencie estes parâmetros integrados sem defini-los na API. Se uma API definir um parâmetro com o mesmo nome, o valor do parâmetro da API terá precedência.

Parâmetro	Descrição	Valores de exemplo
`$CaStage`	Estágio de implantação da API	`RELEASE`, `PRE`, `TEST`
`$CaDomain`	Nome de domínio do grupo de APIs	-
`$CaRequestHandleTime`	Hora em que a requisição foi recebida (UTC)	-
`$CaAppId`	AppId do chamador	`10098`
`$CaAppKey`	AppKey do chamador	-
`$CaClientIp`	Endereço IP do cliente	`47.47.XX.XX`
`$CaApiName`	Nome da API solicitada	-
`$CaHttpScheme`	Protocolo da requisição	`HTTP`, `HTTPS`
`$CaClientUa`	String UserAgent do cliente	-

Exemplos de expressões

Roteie requisições para APIs publicadas no estágio de teste:

$CaStage = 'TEST'

Corresponda a um usuário específico de um endereço IP específico:

$UserName = 'Admin' and $CaClientIp = '47.47.XX.XX'

Corresponda a vários AppIds via HTTPS:

$CaHttpScheme = 'HTTPS' and ($CaAppId = 1001 or $CaAppId = 1098 or $CaAppId = 2011)

Tipos de backend

A configuração de backend em uma regra de roteamento substitui o backend padrão da API vinculada. Para alterar apenas campos específicos sem trocar o tipo de backend, especifique somente os campos a serem substituídos. As configurações de backend devem ser consistentes com os arquivos Swagger importados para o API Gateway. Para mais informações, consulte Importar arquivos Swagger para criar APIs com extensões do API Gateway.

Importante

Para distribuir requisições por peso, especifique todos os parâmetros de backend. Para detalhes sobre a prioridade do cabeçalho Host, consulte Configurar o cabeçalho Host. O tempo limite mínimo configurável é de 300 ms. Valores abaixo desse limiar assumem o padrão de 300 ms.

Referência de parâmetros de backend

Tipo de backend	Parâmetro	Descrição
HTTP	`address`	URL do backend, ex.: `http://10.10.100.2:8000`
	`httpTargetHostName`	Substituição do cabeçalho Host (maior prioridade)
	`path`	Caminho da requisição, ex.: `/users/{userId}`
	`method`	Método HTTP, ex.: `GET`
	`timeout`	Tempo limite em milissegundos (mínimo de 300 ms)
HTTP-VPC	`vpcAccessName`	Nome da autorização de acesso à VPC
	`vpcTargetHostName`	Substituição do cabeçalho Host (maior prioridade)
	`vpcScheme`	Protocolo para o backend VPC, ex.: `https`
	`path`	Caminho da requisição
	`method`	Método HTTP
	`timeout`	Tempo limite em milissegundos (mínimo de 300 ms)
FC	`fcRegion`	Região do Function Compute, ex.: `cn-shanghai`
	`fcType`	Tipo de gatilho: `FCEvent` ou `HttpTrigger`
	`serviceName`	Nome do serviço FC (FCEvent)
	`functionName`	Nome da função FC (FCEvent)
	`fcUrl`	URL da função (HttpTrigger)
	`roleArn`	ARN da função RAM para o API Gateway acessar o FC
	`method`	Método HTTP (apenas HttpTrigger)
OSS	`ossRegionId`	Região do Object Storage Service (OSS), ex.: `cn-hangzhou`
	`bucketName`	Nome do bucket OSS
	`key`	Chave do objeto, ex.: `/objectName`
	`timeout`	Tempo limite em milissegundos (mínimo de 300 ms)
	`action`	Operação OSS, ex.: `putObject`
MOCK	`mockResult`	Corpo da resposta simulada
	`mockStatusCode`	Código de status HTTP para a resposta simulada
	`mockHeaders`	Array de cabeçalhos de resposta (cada um com `name` e `value`)

Exemplos de configuração

HTTP

---
backend:
  type: HTTP
  address: "http://10.10.100.2:8000"
  httpTargetHostName: "a.b.com"
  path: "/users/{userId}"
  method: GET
  timeout: 7000

HTTP-VPC

---
backend:
  type: HTTP-VPC
  vpcAccessName: vpcAccess1
  vpcTargetHostName: "a.b.com"
  vpcScheme: "https"
  path: "/users/{userId}"
  method: GET
  timeout: 10000

Function Compute (FCEvent)

---
backend:
  type: FC
  fcRegion: cn-shanghai
  fcType: FCEvent
  serviceName: fcService
  functionName: fcFunction
  roleArn: "acs:ram::111111111:role/aliyunapigatewayaccessingfcrole"

Function Compute (HttpTrigger)

---
backend:
  type: FC
  fcRegion: cn-shenzhen
  method: GET
  fcType: HttpTrigger
  fcUrl: https://1833848375796824.cn-shenzhen.fc.aliyuncs.com/2016-08-15/proxy/servicetest/fctest3/fctest3
  roleArn: acs:ram::1833848375796824:role/aliyunapigatewayaccessingfcrole

OSS

---
backend:
  type: OSS
  ossRegionId: cn-hangzhou
  bucketName: bucketName
  key: /objectName
  timeout: 10000
  action: putObject

MOCK

---
backend:
  type: MOCK
  mockResult: "mock resul sample"
  mockStatusCode: 200
  mockHeaders:
    - name: server
      value: mock
    - name: proxy
      value: GW

Distribuição ponderada de tráfego

Atribua pesos às rotas para distribuir o tráfego proporcionalmente. Rotas com pesos maiores recebem mais requisições.

---
routes:
  - name: Backend01
    condition: "1 = 1"   # Always matches
    weight: 100
    backend:
      type: "HTTP"
      address: "https://test01.com"
      path: "/web/cloudapi"
  - name: Backend02
    condition: "1 = 1"
    weight: 80
    backend:
      type: "HTTP"
      address: "https://test02.com"
      path: "/web/cloudapi"

Regras de distribuição de tráfego:

Condição	Comportamento
Uma rota corresponde	Todas as requisições vão para o backend dessa rota
Várias rotas correspondem	As requisições são distribuídas proporcionalmente pelo peso
Nenhuma rota corresponde	As requisições vão para o backend padrão da API

Importante

A distribuição baseada em peso exige a especificação de todos os parâmetros de backend em cada rota.

Hashing consistente

O hashing consistente distribui requisições com base em um fator de hash. Requisições com o mesmo fator de hash sempre chegam ao mesmo backend.

Fatores de hash suportados:

Fator de hash	Descrição
Endereço IP de source	Requisições do mesmo IP de cliente vão para o mesmo backend
Parâmetro de requisição	Requisições com o mesmo valor de parâmetro vão para o mesmo backend

Exemplo: hashing por IP de source

---
parameters:
  clientIp: "System:CaClientIp"
routeByHash: clientIp
routes:
  - name: route1
    condition: "1 = 1"
    backend:
      type: "MOCK"
      statusCode: 200
      mockResult: "Hello World!!!"
  - name: route2
    condition: "1 = 1"
    backend:
      type: "MOCK"
      statusCode: 400
      mockResult: "mock resul sample"
  - name: route3
    condition: "1 = 0"   # Never matches
    backend:
      type: "HTTP"
      address: "https://test.com"
    constant-parameters:
      - name: x-route-by-hash
        location: header
        value: "route-by-hash"

Neste exemplo, parameters mapeia clientIp para o parâmetro de sistema CaClientIp. O campo routeByHash seleciona clientIp como fator de hash. Requisições do mesmo IP de cliente são roteadas consistentemente para o mesmo backend entre as rotas correspondentes.

Cenários de roteamento

Roteamento por ID de aplicativo

Encaminhe chamadores VIP (AppId 10098 ou 10099) para um backend dedicado de virtual private cloud (VPC):

---
routes:
  - name: Vip
    condition: "$CaAppId = 10098 or $CaAppId = 10099"
    backend:
      type: "HTTP-VPC"
      vpcAccessName: "slbAccessForVip"

Roteamento por ambiente

Envie todas as requisições de estágio de teste para um servidor de teste público:

---
routes:
  - name: Vip
    condition: "$CaStage = 'TEST'"
    backend:
      type: "HTTP"
      address: "https://test-env.foo.com"

Implantação blue-green

Divida o tráfego em 5%/95% entre um servidor beta e um backend de produção VPC:

---
routes:
  - name: BlueGreenPercent05
    condition: "1 = 1"
    weight: 5
    backend:
      type: "HTTP"
      address: "https://beta-version.api.foo.com"
      path: "/web/cloudapi"
    constant-parameters:
      - name: x-route-blue-green
        location: header
        value: "route-blue-green"
  - name: BlueGreenPercent95
    condition: "1 = 1"
    weight: 95
    backend:
      type: HTTP-VPC
      path: "/web/cloudapi"
      vpcAccessName: testvpc

condition: "1 = 1" sempre corresponde. condition: "1 = 0" nunca corresponde. Use weight para controlar a distribuição de tráfego entre rotas correspondentes.

Limitações

Restrição	Limite	Código de erro
Tamanho dos metadados do plug-in	16.384 bytes	`InvalidPluginData.TooLarge`
Rotas por plug-in	160	`InvalidPluginData.TooManyRoutes`
Tamanho da expressão condicional	512 bytes	`InvalidPluginData.ConditionTooLong`
Intervalo mínimo de atualização	45 segundos	`InvalidPluginData.UpdateTooBusy`