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.
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 |
|---|---|
|
|
API 1 |
|
|
API 2 |
|
|
API 3 |
|
|
API 4 |
|
|
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 |
|---|---|---|
|
|
API 2 |
A solicitação apresenta correspondência exata a esse mapeamento de API. |
|
|
API 3 |
A solicitação apresenta correspondência exata a esse mapeamento de API. |
|
|
API 4 |
A solicitação apresenta correspondência exata a esse mapeamento de API. |
|
|
API 3 |
O API Gateway escolhe o mapeamento com o caminho correspondente mais longo. O |
|
|
API 5 |
O API Gateway escolhe o mapeamento com o caminho correspondente mais longo. |
|
|
API 1 |
O API Gateway usa o mapeamento vazio como um catch-all. |
|
|
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 |
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.
Para obter exemplos de modelos do AWS Serverless Application Model que criam todos os recursos, consulte Sessões com SAM
