# Encaminhar o tráfego às APIs por meio do nome de domínio personalizado no API Gateway
Ao configurar o modo de roteamento para o nome de domínio personalizado, você define como o tráfego de entrada é direcionado às APIs. Você envia tráfego às APIs usando regras de roteamento, mapeamentos de API ou regras de roteamento e mapeamentos de API. A seção a seguir explica quando usar regras de roteamento, quando usar mapeamentos de API e como definir o modo de roteamento para o nome de domínio personalizado.
## Quando usar regras de roteamento
Ao usar regras de roteamento, você direciona as solicitações recebidas que correspondem a determinadas condições para estágios específicos das APIs REST. Por exemplo, uma regra pode encaminhar uma solicitação ao estágio `production` da API REST `users` se ela contiver o cabeçalho `version:v1` e o caminho base `/users`. Use regras de roteamento para criar topologias avançadas de roteamento dinâmico que atendam a determinados casos de uso, como testes A/B ou aumento do uso de novas versões das APIs.
Recomendamos que, ao direcionar o tráfego para uma API REST, você use regras de roteamento para o nome de domínio personalizado. Você pode recriar qualquer mapeamento de API usando regras de roteamento. Para obter mais informações, consulte [Recriar um mapeamento de API usando regras de roteamento](rest-api-routing-rules-recreate-api-mapping.md).
Para APIs REST, você também pode usar regras de roteamento e mapeamentos de API ao mesmo tempo. Quando você usa regras de roteamento e mapeamentos de API ao mesmo tempo, o API Gateway sempre avalia as regras de roteamento antes de avaliar qualquer mapeamento de API. Use regras de roteamento e mapeamentos de API juntos para migrar seus nomes de domínio personalizados atuais ou para examinar as regras de roteamento.
### Considerações sobre regras de roteamento
As seguintes considerações podem afetar o uso de APIs privadas:
+ As APIs HTTP ou de WebSocket não são permitidas como APIs de destino para regras de roteamento.
+ 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.
+ Você pode criar uma regra de roteamento de um domínio personalizado privado para uma API REST privada. Você pode criar uma regra de roteamento para um domínio público personalizado para uma API regional ou otimizada para borda.
+ Não é possível criar uma regra de roteamento de um domínio personalizado privado para uma API REST privada. Não é possível criar uma regra de roteamento de um domínio personalizado privado para uma API REST privada.
## Escolha entre regras de roteamento e mapeamentos de API
Recomendamos que, quando possível, você use regras de roteamento. Use mapeamentos de API somente para enviar tráfego a uma API HTTP ou de WebSocket.
# Definir o modo de roteamento para o nome de domínio personalizado
Você pode escolher qual modo de roteamento o API Gateway deve usar para rotear o tráfego para as APIs. Para obter mais informações, consulte [Encaminhar o tráfego às APIs por meio do nome de domínio personalizado no API Gateway](rest-api-routing-mode.md). Esta seção aborda modos de roteamento para nomes de domínio personalizados. Você deve definir um modo de roteamento para o nome de domínio personalizado para rotear o tráfego para as APIs. Os seguintes modos de roteamento são permitidos:
+ **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**: use esse modo para enviar tráfego às APIs com regras de roteamento e mapeamentos de API. Nesse modo, todas as regras de roteamento têm prioridade sobre qualquer mapeamento de API. Para obter um exemplo desse modo, consulte [Exemplo 2: regras de roteamento e mapeamentos de API](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings).
+ **ROUTING\$1RULE\$1ONLY**: use esse modo para permitir que somente as regras de roteamento enviem tráfego às APIs. Quando o nome de domínio personalizado usa esse modo, não é possível criar um mapeamento de API, mas você pode usar o comando [get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html) para visualizá-lo. Os autores de chamada de API não podem usar mapeamentos de API para acessar esse nome de domínio.
+ **API\$1MAPPING\$1ONLY**: use esse modo para permitir que somente mapeamentos de API enviem tráfego às APIs. Quando o nome de domínio personalizado usa esse modo, não é possível criar um mapeamento de API, mas você pode usar o comando `list-routing-rules` para visualizá-lo. Os autores de chamada de API não podem usar regras de roteamento para acessar esse nome de domínio.
Esse é o modo de roteamento padrão para todos os nomes de domínio existentes e quaisquer novos nomes de domínio que você criar.
Ao criar um nome de domínio personalizado usando `apigateway`, `API_MAPPING_ONLY` é chamado `BASE_PATH_MAPPING_ONLY` e `ROUTING_RULE_THEN_API_MAPPING` é chamado `ROUTING_RULE_THEN_BASE_PATH_MAPPING`. Esse comportamento ocorre somente na AWS CLI, no CloudFormation ou em qualquer SDK, não no Console de gerenciamento da AWS.
O procedimento a seguir mostra como alterar o modo de roteamento para um nome de domínio personalizado existente. Ao alterar o modo de roteamento do nome de domínio personalizado, os autores de chamada de API não podem acessar seu nome de domínio usando nenhum modo de roteamento incompatível.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado.
1. Em **Detalhes do domínio**, escolha **Editar**.
1. Em **Modo de roteamento**, escolha **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**.
1. Escolha **Salvar**.
Se você alterar o modo de roteamento para `ROUTING_RULE_ONLY` ou `API_MAPPING_ONLY`, todos os mapeamentos de API ou regras de roteamento que você criou serão removidos da página de detalhes do nome de domínio do console. Se você alterar o modo de roteamento para permitir o uso de regras de roteamento ou mapeamentos de API, esses recursos retornarão.
------
#### [ AWS CLI - apigatewayv2 ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) indicado abaixo atualiza um nome de domínio para usar o modo de roteamento `ROUTING_RULE_THEN_API_MAPPING`:
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
A saída será exibida da seguinte forma:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "api.example.com",
"DomainNameArn": "arn:aws:apigateway:us-west-2::/domainnames/api.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcdefg.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/abcdefg-123456-abcdefg",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
],
"RoutingMode": "ROUTING_RULE_THEN_API_MAPPING",
"Tags": {}
}
```
------
#### [ AWS CLI - apigateway ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) indicado abaixo atualiza um nome de domínio personalizado privado para usar o modo de roteamento `ROUTING_RULE_THEN_BASE_PATH_MAPPING`:
```
aws apigateway update-domain-name \
--domain-name 'private.example.com' \
--patch-operations "op='replace',path='/routingMode',value='ROUTING_RULE_THEN_BASE_PATH_MAPPING'"
```
A saída será exibida da seguinte forma:
```
{
"domainName": "private.example.com",
"domainNameId": "abcd1234",
"domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234",
"certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"certificateUploadDate": "2024-09-10T10:31:20-07:00",
"endpointConfiguration": {
"types": [
"PRIVATE"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"policy": "...",
"routingMode" : "ROUTING_RULE_THEN_BASE_PATH_MAPPING"
}
```
------
# 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](#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 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](#rest-api-routing-rules-restrictions).
#### 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 |
| --- | --- | --- |
| `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
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
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 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 (`\`).
# Exemplos de como o API Gateway avalia regras de roteamento
A seção a seguir mostra quatro exemplos de como o API Gateway avalia regras de roteamento e mapeamentos de API.
## Exemplo 1: somente regras de roteamento
Neste exemplo, o nome de domínio personalizado `https://petstore.example.com` tem o modo de roteamento definido como `ROUTING_RULE_ONLY` e as regras e prioridades de roteamento a seguir.
| ID da regra | Prioridade | Condições | Ação |
| --- | --- | --- | --- |
| `abc123` | 10 | Se a solicitação contiver cabeçalho: `Hello:World` | API de destino 1 |
| `zzz000` | 50 | Se a solicitação contiver cabeçalhos `Accept:image/webp` e `Pet:Dog-*` e se o caminho base contiver `PetStoreShopper` | API de destino 2 |
| `efg456` | 100 | Nenhum | API de destino 3 |
A tabela a seguir mostra como o API Gateway aplica as regras de roteamento anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://petstore.example.com -h "Hello:World"` | API de destino 1 | As solicitações correspondem à regra de roteamento `abc123`. |
| `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | API de destino 1 | O API Gateway avalia todas as regras de roteamento em ordem de prioridade. A regra de roteamento `abc123` é a primeira em prioridade e as condições correspondem, então o API Gateway invoca a API de destino 1. Embora as condições da solicitação também correspondam à regra de roteamento `zzz000`, o API Gateway não avalia nenhuma outra regra de roteamento depois que encontra uma correspondência. |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | API de destino 2 | As solicitações correspondem à regra de roteamento `zzz000`. Houve correspondência porque `Pet:Dog-Bella` era uma string compatível com `Pet:Dog-*`. |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | API de destino 3 | A solicitação não corresponde à regra de roteamento `abc123`. A solicitação não corresponde à regra de roteamento `zzz000` porque todos os cabeçalhos necessários não estão presentes. A próxima regra prioritária corresponde a todas as solicitações recebidas, então o API Gateway invoca a API de destino 3. |
## Exemplo 2: regras de roteamento e mapeamentos de API
Neste exemplo, o nome de domínio personalizado `https://petstore.diagram.example.com` tem o modo de roteamento definido como `ROUTING_RULE_THEN_API_MAPPING` e as regras de roteamento e mapeamentos de API a seguir.
| ID da regra | Prioridade | Condições | Ação |
| --- | --- | --- | --- |
| `abc123` | 1 | Se a solicitação contiver `pets` | Invoque o estágio `Prod` da API `PetStore`. |
| `000zzz` | 5 | Se a solicitação contiver cabeçalhos `Cookie` e `*ux=beta*` e se o caminho base contiver `/refunds` | Invoque o estágio `Beta` da API `Refunds`. |
A tabela a seguir mostra mapeamentos de API para `https://petstore.backup.example.com`.
| Mapeamento de API | API selecionada |
| --- | --- |
| `/refunds` | Invoque o estágio `Prod` da API `Refunds`. |
| `(none)` | Invoque o estágio `Prod` da API `Search`. |
O diagrama a seguir mostra como o API Gateway aplica as regras de roteamento e os mapeamentos de API anteriores a solicitações de exemplo. As solicitações de exemplo estão resumidas na tabela após esse diagrama.
![\[Diagrama de como o API Gateway aplica as regras de roteamento e os mapeamentos de API anteriores.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/rr-diagram.png)
A tabela a seguir mostra como o API Gateway aplica as regras de roteamento e os mapeamentos de API anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://petstore.diagram.com/pets` | O estágio `Prod` da API `PetStore`. | A solicitação corresponde à regra de roteamento `abc123`. |
| `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | O estágio `Beta` da API `Refunds`. | A solicitação corresponde à regra de roteamento `000zzz`. O cabeçalho `Cookie` contém a correspondência `*contains*` correta e a correspondência do caminho base para essa condição. |
| `https://petstore.diagram.example.com/refunds` | O estágio `Prod` da API `Refunds`. | A solicitação não tem os cabeçalhos necessários para fazer a correspondência com a regra de roteamento `zzz000`. Se o API Gateway não conseguir fazer a correspondência com uma regra de roteamento, ele retornará aos mapeamentos de API. O API Gateway pode associar o caminho base ao estágio `Prod` da API `Refunds`. |
| `https://petstore.diagram.example.com/` | O estágio `Prod` da API `Search`. | A solicitação faz a correspondência entre o mapeamento de API e o caminho vazio `(none)`. |
## Exemplo 3: regras de roteamento e mapeamentos de API com vários níveis
Neste exemplo, o nome de domínio personalizado `https://petstore.backup.example.com` tem o modo de roteamento definido como `ROUTING_RULE_THEN_API_MAPPING` e as regras de roteamento e mapeamentos de API a seguir.
A tabela a seguir mostra regras de roteamento para `https://petstore.backup.example.com`.
| ID da regra | Prioridade | Condições | Ação |
| --- | --- | --- | --- |
| `abc123` | 10 | Se a solicitação contiver cabeçalho: `Hello:World` | API de destino 1 |
| `000zzz` | 50 | Se a solicitação contiver cabeçalhos `Accept`:`image/webp` e `Pet:Dog-*` e se o caminho base contiver `PetStoreShopper` | API de destino 2 |
A tabela a seguir mostra mapeamentos de API para `https://petstore.backup.example.com`.
| Mapeamento de API | API selecionada |
| --- | --- |
| `PetStoreShopper` | API de destino 3 |
| `PetStoreShopper/cats` | API de destino 4 |
A tabela a seguir mostra como o API Gateway aplica as regras de roteamento e os mapeamentos de API anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | API de destino 3 | A solicitação não tem os cabeçalhos necessários para fazer a correspondência com a regra de roteamento `zzz000`. Se o API Gateway não conseguir fazer a correspondência com uma regra de roteamento, ele retornará aos mapeamentos de API. O API Gateway pode associar o caminho base à API de destino 3. |
| `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | API de destino 1 | A solicitação corresponde à regra de roteamento `abc123`. Se o modo de roteamento estiver definido como `ROUTING_RULE_THEN_API_MAPPING`, as regras de roteamento sempre terão prioridade sobre os mapeamentos de API. |
| `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | Nenhum | A solicitação não corresponde a nenhuma regra de roteamento ou mapeamento de API. Como não há uma regra de roteamento padrão, o API Gateway rejeita a chamada e envia um código de status `403 Forbidden` ao autor da chamada. |
## Exemplo 4: regras de roteamento para nomes de domínio curinga
Neste exemplo, o nome de domínio personalizado `https://*.example.com` é um nome de domínio curinga. O curinga aceita todos os subdomínios que são roteados de volta para o mesmo domínio. Os exemplos de regra de roteamento a seguir alteram esse comportamento para permitir que subdomínios sejam roteados para diferentes APIs de destino usando o cabeçalho `Host`.
A tabela a seguir mostra regras de roteamento para `https://*.example.com`.
| ID da regra | Prioridade | Condições | Ação |
| --- | --- | --- | --- |
| `abc123` | 10 | Se a solicitação contiver cabeçalho: `Host:a.example.com` | API de destino 1 |
| `000zzz` | 50 | Se a solicitação contiver cabeçalho: `Host:b.example.com` | API de destino 2 |
| `efg456` | 500 | Nenhum | API de destino 3 |
A tabela a seguir mostra como o API Gateway aplica as regras de roteamento anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://a.example.com` | API de destino 1 | O cabeçalho `Host` é `a.example.com`. Essa solicitação corresponde à regra de roteamento `abc123`. |
| `https://b.example.com` | API de destino 2 | O cabeçalho `Host` é `b.example.com`. Essa solicitação corresponde à regra de roteamento `000zzz`. |
| `https://testing.example.com` | API de destino 3 | Isso corresponde à regra de roteamento abrangente `efg456`. |
# Quando usar regras de roteamento
Você pode criar uma regra de roteamento usando o Console de gerenciamento da AWS, a AWS CLI ou qualquer SDK da AWS. Depois que você criar um trabalho, não poderá mais alterar ou atualizar a respectiva prioridade.
## Criar uma regra de roteamento
O procedimento a seguir mostra como criar uma regra de roteamento para um nome de domínio personalizado com um modo de roteamento definido como `ROUTING_RULE_THEN_API_MAPPING` ou `ROUTING_RULE_ONLY`.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado.
1. Na guia **Detalhes do roteamento**, escolha **Adicionar regra de roteamento.**
1. Escolha **Adicionar uma nova condição** para adicionar uma nova condição.
Você pode adicionar uma condição de cabeçalho ou de caminho base. Para fazer a correspondência de todas as solicitações recebidas com seu nome de domínio personalizado, não adicione uma condição.
1. Em **Ação**, use o menu suspenso para selecionar a API e o estágio de destino.
1. Escolha **Próximo**.
1. No campo de prioridade, insira um número para sua prioridade.
O API Gateway avalia as regras em ordem de prioridade, do valor mais baixo para o valor mais alto.
Se você estiver criando uma regra sem uma condição, recomendamos usar uma prioridade com um valor alto.
1. Selecione **Criar regra de roteamento**.
------
#### [ AWS CLI ]
O comando [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) indicado abaixo cria uma regra de roteamento com prioridade 50. Neste exemplo, o API Gateway roteia todas as solicitações recebidas que tenham os cabeçalhos `Hello:World` e `x-version:beta` e o caminho base `PetStoreShopper` para a API de destino `a1b2c3`.
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
A saída será exibida da seguinte forma:
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 50,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
## Alterar a prioridade de uma regra de roteamento
Você pode alterar a prioridade de uma regra de roteamento. Essa alteração entra em vigor imediatamente e pode afetar a forma como os consumidores da API invocam seus nomes de domínio personalizados. Recomendamos que, ao definir a prioridade de suas regras de roteamento, você deixe intervalos entre as regras.
Por exemplo, considere duas regras de roteamento, regra `abc123` com prioridade 50 e regra `zzz000` com prioridade 150. Para alterar a prioridade das regras de modo que o API Gateway avalie a regra `zzz000` primeiro, você pode alterar a prioridade da regra `zzz000` para 30.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado.
1. Na guia **Detalhes do roteamento**, escolha sua regra de roteamento e selecione **Editar**.
1. Escolha **Próximo**.
1. Em prioridade, insira a nova prioridade.
1. Escolha **Salvar alterações**.
------
#### [ AWS CLI ]
O comando [put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html) indicado abaixo altera a prioridade de uma regra de roteamento `abc123`.
```
aws apigatewayv2 put-routing-rule \
--domain-name 'api.example.com' \
--priority 30 \
--routing-rule-id abc123 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
A saída será exibida da seguinte forma:
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 38,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
# Recriar um mapeamento de API usando regras de roteamento
Você pode recriar um mapeamento de API usando regras de roteamento. Para recriar um mapeamento de API, ative a remoção do caminho base. Isso preserva o comportamento dos mapeamentos de API. Para obter mais informações, consulte [Remoção do caminho base com as condições do caminho base](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split).
O tutorial a seguir mostra como recriar o mapeamento de API `https:// api.example.com/orders/v2/items/categories/5` como uma regra de roteamento e como atualizar os logs de acesso para registrar em log o ID da regra de roteamento que o API Gateway usa para enviar tráfego à sua API.
------
#### [ Console de gerenciamento da AWS ]
**Como definir o modo de roteamento como ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha seu nome de domínio personalizado.
1. Em **Detalhes do domínio**, escolha **Editar**.
1. Em **Modo de roteamento**, escolha **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**.
1. Escolha **Salvar**
Depois de definir o modo de roteamento, crie a regra de roteamento.
**Como criar a regra de roteamento**
1. Na guia **Detalhes do roteamento**, escolha **Adicionar regra de roteamento.**
1. Escolha **Adicionar condição** e selecione **Caminho**.
1. Em **Caminho**, insira **orders/v2/items/categories/5**.
1. Em **Remover caminho base**, escolha **Ativo**.
1. Em **API de destino**, escolha sua API de destino.
1. Em **Estágio de destino**, escolha seu estágio de destino.
1. Escolha **Próximo**.
1. Em prioridade, insira a prioridade.
Mesmo que você mantiver o mapeamento de API existente, o API Gateway sempre usará a nova regra de roteamento, pois as regras de roteamento sempre têm prioridade sobre os mapeamentos de API.
1. Escolha **Salvar alterações**.
Depois de criar a regra de roteamento, atualize o formato do log de acesso do estágio ou crie um log para confirmar se o API Gateway usa sua regra de roteamento para enviar tráfego à sua API.
**Como atualizar logs de acesso**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione a API.
1. No painel de navegação principal, selecione **Estágios**.
1. Em **Logs e rastreamento**, escolha **Editar**.
Se você não tiver um grupo de logs, consulte [Configurar o registro em log do CloudWatch para APIs REST no API Gateway](set-up-logging.md).
1. Adicione **\$1context.customDomain.routingRuleIdMatched** ao formato do log.
Esse grupo de logs registra o ID da regra de roteamento que o API Gateway usou para enviar tráfego à sua API. Para obter mais informações, consulte [Não sei como o API Gateway enviou tráfego às minhas APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
1. Escolha **Salvar**.
Depois de atualizar os logs de acesso, invoque seu nome de domínio personalizado. Veja a seguir um exemplo de comando curl para invocar o nome de domínio personalizado `https://api.example.com` com o caminho base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5"
```
Depois de invocar com sucesso seu nome de domínio personalizado, confirme se o CloudWatch Logs mostra `routingRuleIdMatched`. Para saber como usar o console do CloudWatch Logs para visualizar um grupo de logs, consulte [Exibir eventos de log do API Gateway no console do CloudWatch](view-cloudwatch-log-events-in-cloudwatch-console.md).
------
#### [ AWS CLI ]
1. Use o comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) indicado abaixo para atualizar o nome de domínio `api.example.com` e usar modo de roteamento `ROUTING_RULE_THEN_API_MAPPING`.
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode ROUTING_RULE_THEN_API_MAPPING
```
1. Use o comando [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) indicado abaixo para criar uma regra de roteamento e recriar o mapeamento de API `https://api.example.com/orders/v2/items/categories/5`.
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchBasePaths": {
"AnyOf": [
"orders/v2/items/categories/5"
]
}
}
]' \
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": true
}
}
]'
```
1. Use o comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) indicado abaixo para atualizar o formato dos logs de acesso e incluir a variável `$context.customDomain.routingRuleIdMatched`. Essa variável registra o ID da regra de roteamento que o API Gateway usou para enviar tráfego à sua API. Você usa esse log para confirmar se o API Gateway usa sua regra de roteamento para enviar tráfego à sua API. Para obter mais informações, consulte [Não sei como o API Gateway enviou tráfego às minhas APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
```
aws apigateway update-stage \
--rest-api-id a1bc2c3 \
--stage-name prod \
--patch-operations "op=replace,path=/accessLogSettings/format,value='\$context.path \$context.customDomain.routingRuleIdMatched \$context.requestId \$context.extendedRequestId'"
```
Se você não tiver um grupo de logs, consulte [Configurar o registro em log do CloudWatch para APIs REST no API Gateway](set-up-logging.md).
1. Use o exemplo de comando curl indicado abaixo para invocar o nome de domínio personalizado com o caminho base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5
```
1. Use o comando [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html) indicado abaixo para obter os eventos de logs do grupo de logs `access-log-group-orders` que contêm o ID da regra de roteamento `abc123`.
```
aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123
```
Isso confirma que o API Gateway usou a regra de roteamento para enviar tráfego à sua API.
------
# Solucionar problemas em regras de roteamento
As diretrizes de solução de problemas a seguir podem ajudar a resolver problemas em suas regras de roteamento.
## Não sei como o API Gateway enviou tráfego às minhas APIs
Você pode usar logs de acesso para o estágio da API REST a fim de registrar em log e solucionar problemas em suas regras de roteamento. Você pode visualizar o ID da regra de roteamento que o API Gateway usou para enviar tráfego à sua API usando a variável `$context.customDomain.routingRuleIdMatched`. Para visualizar o mapeamento de API que o API Gateway usou para enviar tráfego à sua API, use a variável `$context.customDomain.basePathMatched`.
Para registrar suas regras de roteamento em log, você precisa configurar [um ARN de função do CloudWatch Logs apropriado](set-up-logging.md#set-up-access-logging-permissions) para sua conta e criar um grupo de logs.
O exemplo de grupo de logs de acesso a seguir pode recuperar as informações relevantes para solucionar problemas em regras de roteamento e mapeamentos de API. O API Gateway preenche somente a variável de contexto do mecanismo de roteamento que ele usa; do contrário, a variável de contexto é `-`.
------
#### [ CLF ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.requestId $context.extendedRequestId
```
------
#### [ JSON ]
```
{"requestPath": "$context.path", "routingRuleId" : "$context.customDomain.routingRuleIdMatched", "API mapping" : "$context.customDomain.basePathMatched", "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId"}
```
------
#### [ XML ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.extendedRequestId
```
------
#### [ CSV ]
```
$context.path,$context.customDomain.routingRuleIdMatched,$context.customDomain.basePathMatched,$context.requestId,$context.extendedRequestId
```
------
Também recomendamos que você confirme o modo de roteamento do nome de domínio personalizado. Para obter mais informações, consulte [Definir o modo de roteamento para o nome de domínio personalizado](set-routing-mode.md).
## Não consigo habilitar as regras de roteamento no meu nome de domínio personalizado
Você pode receber o seguinte erro do API Gateway:
```
Your account doesn’t have permission to use RoutingRules.
This might be caused by an IAM policy in your account with a deny statement on BasePathMapping or ApiMapping.
To grant permission for this account to use RoutingRules, use the UpdateAccount API.
This will impact any existing IAM policies that deny access to BasePathMapping or ApiMapping.
See API Gateway documentation for further details.
```
Você receberá esse erro se tiver ou tenha tido uma política do IAM que nega acesso ao [BasePathMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies) ou ao [ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies). Ao habilitar as regras de roteamento para um nome de domínio personalizado, embora sua política continue negando acesso a `BasePathMapping` ou a `ApiMapping`, a mesma política pode ser usada para acessar a `RoutingRule`. Isso pode permitir que um usuário altere o comportamento de roteamento do seu nome de domínio personalizado.
Por exemplo, se você teve uma política como a seguinte:
```
{
"Sid": "DenyCreatingApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
}
```
Ao habilitar as regras de roteamento para `example.com`, essa política continuará negando o acesso à criação de um `ApiMapping`, mas não negará o acesso à criação de uma `RoutingRule`.
Recomendamos que você audite as políticas do IAM em sua conta. O seguinte exemplo de política negará acesso à criação de `ApiMapping`, `BasePathMapping`e `RoutingRule`:
```
{
"Sid": "DenyCreatingBasePathMappingsApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/basepathmappings",
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
},
{
"Sid": "DenyCreatingRoutingRules",
"Effect": "Deny",
"Action": "apigateway:CreateRoutingRule",
"Resource": [
"arn:aws:apigateway:us-west-2:111122223333:/domainnames/example.com/routingrules/*"
]
}
```
Depois de confirmar que todas as políticas foram atualizadas, você pode atualizar as configurações da API no nível da conta para habilitar as regras de roteamento para uma região.
Use o comando [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) indicado abaixo para atualizar as configurações em nível de conta da API para uma região:
```
aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2
```
Depois de atualizar as configurações em nível de conta da API, você pode alterar o modo de roteamento do nome de domínio personalizado. Você também pode continuar usando as políticas do IAM para negar acesso a `RoutingRules`, `ApiMapping` ou `BasePathMapping`.
# Os mapeamentos de API são usados para associar estágios da API a um nome de domínio personalizado para APIs REST.
Você usa mapeamentos de API para conectar estágios de API a um nome de domínio personalizado. Isso encaminha o tráfego às suas APIs por meio do nome de domínio personalizado.
Um mapeamento de API especifica uma API, um estágio e, opcionalmente, um caminho a usar para o mapeamento. Por exemplo, você pode associar `https://api.example.com/orders` ao estágio `production` de uma API.
Você pode mapear os estágios da API HTTP e REST para o mesmo nome de domínio personalizado.
Antes de criar um mapeamento de API, você deve ter uma API, um estágio e um nome de domínio personalizado. Para saber mais sobre como criar um nome de domínio personalizado, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
## Solicitações recebidas em seu nome de domínio personalizado
Quando você associa um nome de domínio personalizado a um estágio da API, o API Gateway remove o caminho base de entrada. Isso remove o caminho base mapeado da invocação para a API. Por exemplo, se o caminho base `https://api.example.com/orders/shop/5` fosse associado ao estágio `test` e você usasse a solicitação `https://api.example.com/orders/shop/5/hats`, o API Gateway invocaria o recurso `/hats` do estágio `test` da API, não o recurso `orders/shop/5/hats`.
## Mapear solicitações de API
Veja a seguir como o API Gateway explica os mapeamentos de API.
Você pode criar um mapeamento de API usando mapeamentos de nível único, como um mapeamento de API de `orders` para o estágio `beta` de uma API e um mapeamento de API de `shipping` para o estágio `alpha` de uma API. No caso de nomes de domínio regionais personalizados com a política de segurança do TLS 1.2, o API Gateway aceita mapeamentos de API de vários níveis. Você pode criar um mapeamento de API de `orders/v1/items` para o estágio `alpha` de uma API e de `orders/v2/items` para o estágio `beta` de uma API. Para mapeamentos de API com vários níveis, o API Gateway encaminha as solicitações ao mapeamento de API que tem o prefixo correspondente mais longo.
Você pode criar um mapeamento de API para o caminho vazio `(none)`. Se nenhum caminho corresponder à solicitação, o API Gateway enviará a solicitação à API que você associou ao caminho vazio `(none)`.
Neste exemplo, o nome de domínio personalizado `https://api.example.com` tem os seguintes mapeamentos de API:
| Mapeamento de API | API selecionada |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
A tabela a seguir mostra como o API Gateway aplica os mapeamentos de API anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://api.example.com/orders` | API 2 | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v1/items` | API 3 | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v2/items` | API 4 | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v1/items/123` | API 3 | O API Gateway escolhe o mapeamento com o caminho correspondente mais longo. O `123` no final da solicitação não afeta a seleção. Consulte [Solicitações recebidas em seu nome de domínio personalizado](#rest-api-mappings-incoming-requests). |
| `https://api.example.com/orders/v2/items/categories/5` | API 5 | O API Gateway escolhe o mapeamento com o caminho correspondente mais longo. |
| `https://api.example.com/customers` | API 1 | O API Gateway usa o mapeamento vazio como um catch-all. |
| `https://api.example.com/ordersandmore` | API 2 | O API Gateway escolhe o mapeamento com o prefixo correspondente mais longo. Para um nome de domínio personalizado configurado com mapeamentos de nível único, como somente `https://api.example.com/orders` e `https://api.example.com/`, o API Gateway escolheria `API 1`, pois não há um caminho correspondente com `ordersandmore`. |
## Restrições
+ Em um mapeamento de API, o nome de domínio personalizado e as APIs mapeadas devem estar na mesma conta da AWS.
+ Os mapeamentos de API devem conter apenas letras, números e os caracteres a seguir: `$-_.+!*'()/`.
+ O comprimento máximo para o caminho em um mapeamento de API é de 300 caracteres.
+ É possível ter 200 mapeamentos de API com vários níveis para cada nome de domínio. Esse limite não inclui mapeamento de API com um único nível, como `/prod`.
+ Você só pode mapear APIs HTTP para um nome de domínio personalizado regional com a política de segurança TLS 1.2.
+ Você não pode mapear APIs WebSocket para o mesmo nome de domínio personalizado que uma API HTTP ou API REST.
+ Depois de criar os mapeamentos de API, você deve criar ou atualizar o registro de recursos do provedor de DNS para ser associado ao endpoint da API.
+ Se você criar mapeamentos de API com vários níveis, o API Gateway mudará todos os nomes de cabeçalho para minúsculas.
## Crie um mapeamento de API
Para criar um mapeamento de API, você deve primeiro criar um nome de domínio personalizado, uma API e um estágio. O nome de domínio personalizado deve ter um modo de roteamento definido como `ROUTING_RULE_THEN_API_MAPPING` ou `API_MAPPING_ONLY`. Para ter informações sobre como configurar o modo de roteamento, consulte [Definir o modo de roteamento para o nome de domínio personalizado](set-routing-mode.md).
Para obter exemplos de modelos do AWS Serverless Application Model que criam todos os recursos, consulte [Sessões com SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) no GitHub.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado.
1. Na guia **Detalhes do roteamento**, escolha **Configurar mapeamentos de API**.
1. Especifique a **API**, o **Estágio** e o **Caminho** do mapeamento.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) a seguir cria um mapeamento de API. Neste exemplo, o API Gateway envia solicitações para `api.example.com/v1/orders` para a API e o estágio especificados.
**nota**
Para criar mapeamentos de API com vários níveis, você deve usar `apigatewayv2`.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
O exemplo de CloudFormation a seguir cria um mapeamento de API.
**nota**
Para criar mapeamentos de API com vários níveis, você deve usar `AWS::ApiGatewayV2`.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------