# Nomes de domínio personalizados para APIs HTTP no API Gateway Os *nomes de domínio personalizados* são URLs mais simples e intuitivos que você pode fornecer aos usuários da API. Após a implantação da sua API, você e seus clientes podem invocar essa API usando a URL de base padrão com o seguinte formato: ``` https://api-id.execute-api.region.amazonaws.com/stage ``` em que *api-id* é gerado pelo API Gateway, *region* é a região da AWS e *stage* é especificado por você ao implantar a API. A parte do nome de host do URL, `api-id.execute-api.region.amazonaws.com`, refere-se a um endpoint de API. O endpoint de API padrão é gerado aleatoriamente, difícil de lembrar e não é simples de usar. Com nomes de domínio personalizados, você pode configurar o nome de host da API e escolher um caminho base (por exemplo, `myservice`) para mapear o URL alternativo para sua API. Por exemplo, um URL de base de API mais amigável pode se tornar: ``` https://api.example.com/myservice ``` ## Considerações As considerações a seguir podem afetar o uso de um nome de domínio personalizado. + Um nome de domínio regional personalizado pode ser associado a APIs REST e APIs HTTP. É possível usar as APIs do API Gateway versão 2 para criar e gerenciar nomes de domínio regionais personalizados para APIs REST. + Para a versão mínima de TLS, somente o TLS 1.2 é compatível. + É necessário criar ou atualizar o registro de recursos do provedor DNS para ser mapeado ao endpoint da API. Sem esse mapeamento, as solicitações de API que forem direcionadas para o nome de domínio personalizado não conseguirão acessar o API Gateway. + É possível comportar um número quase infinito de nomes de domínio sem exceder a cota padrão usando um certificado curinga. Para obter mais informações, consulte [Nomes de domínio personalizados curinga](#http-wildcard-custom-domain-names). ## Pré-requisitos Veja a seguir os pré-requisitos para criar um nome de domínio personalizado. ### Registrar um nome de domínio É necessário ter um nome de domínio da Internet registrado para configurar nomes de domínio personalizados para as APIs. É possível registrar o domínio da internet usando o [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) ou um registrador de domínios de terceiros da sua escolha. O nome de domínio personalizado pode ser o nome de um subdomínio ou do domínio raiz (também conhecido como “ápex da zona”) de um domínio da internet registrado. O nome de domínio deve seguir a especificação [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) e pode ter no máximo 63 octetos por etiqueta e 255 octetos no total. ### Certificados para nomes de domínio personalizados Antes de configurar um nome de domínio personalizado para uma API, você deve ter um certificado SSL/TLS pronto no ACM. Se o ACM não estiver disponível na região da AWS onde você está criando o nome de domínio personalizado, será necessário importar um certificado para o API Gateway nessa região. Para importar um certificado SSL/TLS, você deve fornecer o corpo do certificado SSL/TLS formatado em PEM, sua chave privada e a cadeia de certificado para o nome de domínio personalizado. Cada certificado armazenado no ACM é identificado por seu ARN. Com certificados emitidos pelo ACM, não é necessário se preocupar em expor detalhes de certificados confidenciais, como a chave privada. Para usar um certificado gerenciado pela AWS para um nome de domínio, basta fazer referência ao seu ARN. Se o seu aplicativo usa a fixação de certificados, às vezes chamada de fixação SSL, para fixar um certificado do ACM, talvez o aplicativo não consiga se conectar ao seu domínio após a AWS renovar o certificado. Para ter mais informações, consulte [Problemas de fixação do certificado](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) no *Guia do usuário do AWS Certificate Manager*. ## Nomes de domínio personalizados curinga Com nomes de domínio personalizados curinga, você pode suportar um número quase infinito de nomes de domínio sem exceder a [cota padrão](limits.md). Por exemplo, você pode dar a cada um de seus clientes seu próprio nome de domínio `customername.api.example.com`. Para criar um nome de domínio personalizado curinga, especifique um curinga (`*`) como o primeiro subdomínio de um domínio personalizado que representa todos os subdomínios possíveis de um domínio raiz. Por exemplo, o nome de domínio personalizado curinga `*.example.com` resulta em subdomínios, como `a.example.com`, `b.example.com` e `c.example.com`, que são todos roteados para o mesmo domínio. Os nomes de domínio personalizados curinga oferecem suporte a configurações distintas dos nomes de domínio personalizados padrão do API Gateway. Por exemplo, em uma única conta da AWS, é possível configurar `*.example.com` e `a.example.com` para se comportarem de forma diferente. Para criar um nome de domínio personalizado curinga, é necessário fornecer um certificado emitido pelo ACM que foi validado usando o DNS ou o método de validação por e-mail. **nota** Não é possível criar um nome de domínio personalizado curinga se uma conta da AWS diferente tiver criado um nome de domínio personalizado que esteja em conflito com o nome de domínio personalizado curinga. Por exemplo, se a conta A tiver criado `a.example.com`, a conta B não poderá criar o nome de domínio personalizado curinga `*.example.com`. Se a conta A e a conta B compartilham um proprietário, entre em contato com a [Central de Suporte da AWS](https://console.aws.amazon.com/support/home#/) para solicitar uma exceção. ## Próximas etapas para nomes de domínio personalizados Para configurar um nome de domínio personalizado para uma API HTTP, use a documentação da seção API REST do Guia do desenvolvedor do API Gateway. Primeiro, especifique o certificado para o nome de domínio personalizado. Para obter mais informações, consulte [Preparar certificados no AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md). Depois, crie um nome de domínio regional personalizado. Para obter mais informações, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md). # 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 ``` ------ # Desabilitar o endpoint padrão para APIs HTTP Por padrão, os clientes podem invocar sua API usando o endpoint `execute-api` gerado pelo API Gateway para sua API. Para garantir que os clientes possam acessar sua API somente usando um nome de domínio personalizado, desabilite o endpoint `execute-api` padrão. Quando o endpoint padrão é desabilitado, ele afeta todos os estágios de uma API. O procedimento a seguir mostra como desabilitar o endpoint padrão de uma API HTTP. ------ #### [ 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. Selecione uma API HTTP. 1. Escolha o ID da API para abrir a página **Detalhes da API**. 1. Em **Detalhes da API**, escolha **Editar**. 1. Em **Endpoint padrão**, selecione **Desabilitar**. 1. Escolha **Salvar**. Se você ativar as implantações automáticas no estágio, não será necessário reimplantar a API para que a alteração entre em vigor. Caso contrário, você deverá reimplantar a API. 1. (Opcional) Selecione **Implantar** e reimplante a API ou crie uma etapa para que a alteração entre em vigor. ------ #### [ AWS CLI ] O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) indicado abaixo desabilita o endpoint padrão para uma API HTTP: ``` aws apigatewayv2 update-api \ --api-id abcdef123 \ --disable-execute-api-endpoint ``` Depois de desabilitar o endpoint padrão, é necessário implantar sua API para que a alteração entre em vigor, a menos que as implantações automáticas estejam habilitadas. O seguinte comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-deployment.html) cria uma implantação: ``` aws apigatewayv2 create-deployment \ --api-id abcdef123 \ --stage-name dev ``` ------ # Tipos de endereço IP para nomes de domínio personalizados para APIs HTTP Ao criar uma API, você especifica o tipo de endereços IP que podem invocar seu domínio. É possível escolher IPv4 para resolver endereços IPv4 e invocar seu domínio ou escolher pilha dupla para permitir que endereços IPv4 e IPv6 invoquem seu domínio. Recomendamos que você defina o tipo de endereço IP como pilha dupla para aliviar o esgotamento do espaço IP ou para seu procedimento de segurança. Para ter mais informações sobre os benefícios de um tipo de endereço IP de pilha dupla, consulte [IPv6 na AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html). ## Considerações sobre tipos de endereço IP As considerações a seguir podem afetar o uso de tipos de endereço IP. + O tipo de endereço IP padrão para nomes de domínio personalizados do API Gateway é IPv4. + Seu nome de domínio personalizado não precisa ter o mesmo tipo de endereço IP para todas as APIs associadas a ele. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar sua API. ## Alterar o tipo de endereço IP de um nome de domínio personalizado É possível alterar o tipo de endereço IP atualizando a configuração do endpoint do domínio. É possível atualizar a configuração do endpoint do domínio usando o Console de gerenciamento da AWS, a AWS CLI, o CloudFormation ou um SDK da AWS. ------ #### [ Console de gerenciamento da AWS ] **Como alterar o tipo de endereço IP de um nome de domínio personalizado** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. Escolha um nome de domínio personalizado público. 1. Escolha **Configurações de endpoint**. 1. Em Tipo de endereço IP, escolha **IPv4** ou **Pilha dupla**. 1. Escolha **Salvar**. ------ #### [ AWS CLI ] O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) a seguir atualiza uma API para ter um tipo de endereço IP de pilha dupla: ``` aws apigatewayv2 update-domain-name \ --domain-name dualstack.example.com \ --domain-name-configurations CertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc,IpAddressType=dualstack ``` A saída será exibida da seguinte forma: ``` { "ApiMappingSelectionExpression": "$request.basepath", "DomainName": "dualstack.example.com", "DomainNameConfigurations": [ { "ApiGatewayDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com", "CertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/abcd1234-5678-abc", "DomainNameStatus": "AVAILABLE", "EndpointType": "REGIONAL", "HostedZoneId": "Z3LQWSYCGH4ADY", "SecurityPolicy": "TLS_1_2", "IpAddressType": "dualstack" } ], "Tags": {} } ``` ------