# Os mapeamentos de API são usados para associar estágios da API a um nome de domínio personalizado para APIs REST.
<a name="rest-api-mappings"></a>

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
<a name="rest-api-mappings-incoming-requests"></a>

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
<a name="rest-api-mappings-evalutation"></a>

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
<a name="rest-api-mappings-restrictions"></a>
+ 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
<a name="rest-api-mappings-examples"></a>

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
```

------