Regras de roteamento para associar estágios da API a um nome de domínio personalizado para APIs REST
Uma regra de roteamento é um conjunto de condições que, quando correspondidas, invocam uma ação. Por exemplo, uma regra pode rotear qualquer solicitação recebida em um nome de domínio personalizado que contenha o cabeçalho Hello:World e o caminho base users para o estágio production de uma API REST.
As regras são avaliadas em ordem de prioridade e, se você definir o modo de roteamento com o ROUTING_RULE_THEN_API_MAPPING, o API Gateway sempre avaliará todas as regras de roteamento antes de avaliar qualquer mapeamento de API. A lista a seguir descreve como uma regra de roteamento usa condições, ações e prioridades.
- Condições
-
Quando as condições de uma regra forem atendidas, a ação será executada. O API Gateway permite até duas condições de cabeçalho e uma condição de caminho. O API Gateway avalia as condições do cabeçalho e as condições do caminho base ao mesmo tempo.
Você pode criar uma regra sem nenhuma condição. Quando o API Gateway avalia essa regra, a ação sempre é executada. Você pode criar uma regra sem nenhuma condição como uma regra abrangente.
Para ter mais informações sobre condições de cabeçalho, consulte Correspondência com condições de cabeçalho. Para ter mais informações sobre as condições de caminho, consulte Correspondência com condições de caminho.
- Ações
-
As ações resultam da correspondência entre condições e uma regra de roteamento. No momento, a única ação possível é invocar um estágio de uma API REST.
Cada regra pode ter uma ação.
- Prioridade
-
A prioridade determina em qual ordem as regras são avaliadas, do valor mais baixo para o valor mais alto. As regras não podem ter a mesma prioridade.
Você pode definir a prioridade de 1 a 1.000.000. Se a prioridade de uma regra for 1, o API Gateway a avaliará primeiro. Recomendamos que, ao criar uma regra, você adicione intervalos nas prioridades. Isso ajuda você a mudar a prioridade das regras e adicionar novas regras. Para obter mais informações, consulte Alterar a prioridade de uma regra de roteamento.
Para ver exemplos de como o API Gateway avalia as regras de roteamento, consulte Exemplos de como o API Gateway avalia regras de roteamento.
Tipos de condição da regra de roteamento do API Gateway
A seção a seguir descreve os tipos de condição de regra de roteamento. O API Gateway só encontrará correspondência com uma regra se todas as condições forem verdadeiras.
Correspondência com condições de cabeçalho
Ao criar uma condição de cabeçalho, você pode fazer a correspondência entre o nome do cabeçalho e o valor glob do cabeçalho, como Hello:World. O API Gateway usa uma correspondência literal para validar a correspondência com condições de cabeçalho. Sua condição pode utilizar até dois cabeçalhos usando AND entre eles. Por exemplo, pode haver correspondência com sua condição se uma solicitação recebida contiver Hello:World e x-version:beta.
A correspondência do nome do cabeçalho não diferencia maiúsculas de minúsculas, mas o valor glob do cabeçalho diferencia maiúsculas de minúsculas. Hello:World corresponderá a hello:World, mas não a Hello:world.
Para obter uma lista de valores de cabeçalho restritos, consulte Restrições.
Uso de curingas com condições de cabeçalho
Você só pode usar curingas no valor glob do cabeçalho, e eles devem ser *prefix-match, suffix-match* ou *contains*. A tabela a seguir mostra exemplos de como usar curingas para fazer a correspondência com as condições do cabeçalho.
| Condições de cabeçalho | Solicitações que correspondem à regra de roteamento | Solicitações que não correspondem à regra de roteamento |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Nenhum |
Se você criar condições para vários valores de cabeçalho, como Accept:application/json,text/xml, é recomendável usar *contains* para as condições de cabeçalho e evitar criar condições usando o caractere vírgula (,).
Como o API Gateway faz a correspondência com as condições de cabeçalho de maneira literal, as correspondências semânticas podem ser roteadas de forma diferente. A tabela a seguir mostra a diferença nos resultados das regras de roteamento.
| Condições de cabeçalho | Solicitações que correspondem à regra de roteamento | Solicitações que não correspondem à regra de roteamento |
|---|---|---|
|
|
|
|
|
|
|
Nenhum |
Correspondência com condições de caminho
Quando você cria uma condição de caminho base, se a solicitação de entrada contiver o caminho especificado, haverá correspondência com a regra. A correspondência diferencia maiúsculas de minúsculas, portanto, o caminho New/Users não corresponderá a new/users.
Você pode criar uma condição de caminho base somente para um caminho base.
Para obter uma lista de condições restritas de caminho base, consulte Restrições.
Remoção do caminho base com as condições do caminho base
Ao criar uma condição de caminho de base, você pode optar por remover o caminho base. Ao remover o caminho base, o API Gateway remove o caminho base correspondente de entrada ao invocar a API de destino. Esse comportamento é igual ao de quando você usa um mapeamento de API. Quando você não remove o caminho base, o API Gateway encaminha o caminho base completo para a API de destino. Recomendamos que você remova o caminho base somente ao recriar um mapeamento de API.
A tabela a seguir mostra exemplos de como o API Gateway avalia a condição de remoção do caminho base.
| Condição | Remover o caminho base | Solicitação de entrada | Resultado |
|---|---|---|---|
|
Se o caminho base contiver |
Verdadeiro |
|
O API Gateway chamará o método |
|
Se o caminho base contiver |
Falso |
|
O API Gateway chamará o método |
|
Se o caminho base contiver |
Verdadeiro |
|
O API Gateway chamará o método |
|
Se o caminho base contiver |
Falso |
|
O API Gateway chamará o método |
|
Se o caminho base contiver |
Verdadeiro |
|
O API Gateway chamará o método |
|
Se o caminho base contiver |
Falso |
|
O API Gateway chamará o |
Restrições
-
A API de destino e o nome de domínio personalizado devem estar na mesma conta da AWS.
Cada regra pode ter uma API de destino.
-
Você só pode criar uma regra de roteamento entre um nome de domínio personalizado privado e uma API privada e entre um nome de domínio personalizado público e uma API pública. Não é permitido misturar recursos públicos e privados.
-
Se o nome de domínio personalizado tiver mapeamentos de API para APIs REST e HTTP, não será possível usar regras de roteamento.
O número máximo de prioridade é 1.000.000.
-
Restrições de cabeçalho:
Cada condição
anyOfsó pode conter um valor de cabeçalho.-
Os únicos caracteres permitidos para nomes de cabeçalho e valores glob de cabeçalho são especificados pela RFC 7230
, que são a-z,A-Ze0-9, e estes caracteres especiais:*?-!#$%&'.^_`|~. -
Você só pode usar um curinga no valor glob do cabeçalho, mas ele deve ser
*prefix-match,suffix-match*ou*contains*. Não é possível usar*no meio de um valor glob de cabeçalho. Nomes de cabeçalho curinga não são permitidos.
O nome do cabeçalho deve ter menos de 40 caracteres.
O valor glob do cabeçalho deve ter menos de 128 caracteres.
O valor glob do cabeçalho para uma correspondência infixa deve ter menos de 40 caracteres.
Os seguintes cabeçalhos não são permitidos como condições:
access-control-*apigw-*AuthorizationConnectionContent-EncodingContent-LengthContent-LocationForwardedKeep-AliveOriginProxy-AuthenticateProxy-AuthorizationTETrailersTransfer-EncodingUpgradex-amz-*x-amzn-*X-Forwarded-ForX-Forwarded-HostX-Forwarded-ProtoVia
-
Restrições do caminho base:
O caminho base deve ter menos de 128 caracteres.
-
O caminho base deve conter apenas letras, números e os seguintes caracteres:
$-_.+!*'()/. O caminho base não pode começar ou terminar com o caractere de barra invertida (
/).
