# Regras de roteamento para associar estágios da API a um nome de domínio personalizado para APIs REST
<a name="rest-api-routing-rules"></a>

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](#rest-api-routing-rules-condition-headers). Para ter mais informações sobre as condições de caminho, consulte [Correspondência com condições de caminho](#rest-api-routing-rules-condition-path). 

**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](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority).

Para ver exemplos de como o API Gateway avalia as regras de roteamento, consulte [Exemplos de como o API Gateway avalia regras de roteamento](rest-api-routing-rules-examples.md).

## Tipos de condição da regra de roteamento do API Gateway
<a name="rest-api-routing-rules-condition-types"></a>

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
<a name="rest-api-routing-rules-condition-headers"></a>

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](#rest-api-routing-rules-restrictions).

#### Uso de curingas com condições de cabeçalho
<a name="rest-api-routing-rules-condition-headers-wildcards"></a>

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  | 
| --- | --- | --- | 
| `x-version: a*` |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
| `x-version: *a` |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
| `x-version: *a*` |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
| `x-version: *a*` e `x-version: *b*` |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
| `x-version: b*` e `x-version: *a` |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
| `x-version: *` |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 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  | 
| --- | --- | --- | 
| `Accept: *json` |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  | 
| `Accept: *json*` |  [See the AWS documentation website for more details](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html)  | Nenhum | 

### Correspondência com condições de caminho
<a name="rest-api-routing-rules-condition-path"></a>

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](#rest-api-routing-rules-restrictions).

#### Remoção do caminho base com as condições do caminho base
<a name="rest-api-routing-rules-condition-path-split"></a>

Ao criar uma condição de caminho 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 `PetStoreShopper/dogs` |  Verdadeiro  | `GET https://example.com/PetStoreShopper/dogs` | O API Gateway chamará o método `GET` do recurso `/`. | 
| Se o caminho base contiver `PetStoreShopper/dogs` |  Falso  | `GET https://example.com/PetStoreShopper/dogs` | O API Gateway chamará o método `GET` do recurso `PetStoreShopper/dogs`. | 
| Se o caminho base contiver `PetStoreShopper` |  Verdadeiro  | `GET https://example.com/PetStoreShopper/dogs` | O API Gateway chamará o método `GET` do recurso `dogs`. | 
| Se o caminho base contiver `PetStoreShopper` |  Falso  | `GET https://example.com/PetStoreShopper/dogs` | O API Gateway chamará o método `GET` do recurso `PetStoreShopper/dogs`. | 
| Se o caminho base contiver `PetStoreShopper` |  Verdadeiro  | `GET https://example.com/PetStoreShopper?birds=available` | O API Gateway chamará o método `GET` do recurso `/` com o parâmetro de string de consulta `birds=available`. | 
| Se o caminho base contiver `PetStoreShopper` |  Falso  | `GET https://example.com/PetStoreShopper?birds=available` | O API Gateway chamará o `GET` método do `/PetStoreShopper` recurso com o parâmetro de string de consulta `birds=available`. | 

## Restrições
<a name="rest-api-routing-rules-restrictions"></a>
+ 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 `anyOf` só 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](https://datatracker.ietf.org/doc/html/rfc7230), que são `a-z`, `A-Z` e `0-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-*`
    + `Authorization`
    + `Connection`
    + `Content-Encoding`
    + `Content-Length`
    + `Content-Location`
    + `Forwarded`
    + `Keep-Alive`
    + `Origin`
    + `Proxy-Authenticate`
    + `Proxy-Authorization`
    + `TE`
    + `Trailers`
    + `Transfer-Encoding`
    + `Upgrade`
    + `x-amz-*`
    + `x-amzn-*`
    + `x-apigw-api-id`
    + `X-Forwarded-For`
    + `X-Forwarded-Host`
    + `X-Forwarded-Proto`
    + `x-restAPI`
    + `Via`
+ 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: `$-_.+!*'()/`.

    Esses caracteres não são compatíveis com expressões regulares (regex). 
  + O caminho base não pode começar ou terminar com o caractere de barra invertida (`\`).