# Mapear estágios de API para um nome de domínio personalizado para APIs HTTP
Você usa mapeamentos de API para conectar estágios de API a um nome de domínio personalizado. Depois de criar um nome de domínio e configurar registros DNS, você usa mapeamentos de API para enviar tráfego para as suas APIs utilizando o seu 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 mapear o estágio `production` de uma API para `https://api.example.com/orders`.
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).
## Rotear solicitações de API
Você pode configurar mapeamentos de API com vários níveis, por exemplo, `orders/v1/items` e `orders/v2/items`.
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. Para selecionar a API para invocar, o API Gateway considera apenas os caminhos configurados para mapeamentos de API, e não rotas de API. Se nenhum caminho corresponder à solicitação, o API Gateway enviará a solicitação para a API que você mapeou para o caminho vazio `(none)`.
Para nomes de domínio personalizados que usam 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.
Por exemplo, considere um nome de domínio personalizado `https://api.example.com` com os seguintes mapeamentos de API:
1. `(none)` mapeado para a API 1.
1. `orders` mapeado para a API 2.
1. `orders/v1/items` mapeado para a API 3.
1. `orders/v2/items` mapeado para a API 4.
1. `orders/v2/items/categories` mapeado para a API 5.
| 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. |
| `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.
+ 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. Para obter informações 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).
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 ]
**Para criar um mapeamento de API**
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).
1. Selecione um nome de domínio personalizado que você já criou.
1. Escolha **API mappings** (Mapeamentos de API).
1. Escolha **Configure API mappings (Configurar mapeamentos de API)**.
1. Escolha **Add new mapping (Adicionar novo mapeamento)**.
1. Insira uma **API**, um **Estágio** e, opcionalmente, um **Caminho**.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api.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.
```
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.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------