Associar estágios de API a um nome de domínio personalizado para APIs REST - Amazon API Gateway
Rotear solicitações de APIRestriçõesCrie um mapeamento de API

Associar estágios de 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. 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.

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.

nota

Para configurar mapeamentos de API com vários níveis, é necessário usar um nome de domínio regional personalizado com a política de segurança do TLS 1.2.

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.

  2. orders mapeado para a API 2.

  3. orders/v1/items mapeado para a API 3.

  4. orders/v2/items mapeado para a API 4.

  5. 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.

  • 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.

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.

Para obter exemplos de modelos do AWS Serverless Application Model que criam todos os recursos, consulte Sessões com SAM no GitHub.

AWS Management Console
Para criar um mapeamento de API

  1. Inicie uma sessão no console do API Gateway em https://console.aws.amazon.com/apigateway.

  2. Escolha Custom domain names (Nomes de domínios personalizados).

  3. Selecione um nome de domínio personalizado que você já criou.

  4. Escolha API mappings (Mapeamentos de API).

  5. Escolha Configure API mappings (Configurar mapeamentos de API).

  6. Escolha Add new mapping (Adicionar novo mapeamento).

  7. Insira uma API, um Estágio e, opcionalmente, um Caminho.

  8. Escolha Save (Salvar).

AWS CLI

O comando da AWS CLI 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
AWS CloudFormation

O exemplo de AWS 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