Nome de domínio personalizado para APIs REST no API Gateway - Amazon API Gateway
ConsideraçõesPré-requisitos Nomes de domínio personalizados curingaPróximas etapas para nomes de domínio personalizados

Nome de domínio personalizado para APIs REST 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.

  • Os nomes de domínio personalizados não são compatíveis com APIs privadas.

  • É possível desabilitar o endpoint padrão para a API. Os clientes ainda podem se conectar ao endpoint padrão, mas receberão um código de status 403 Forbidden.

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

  • Um nome de domínio personalizado deve ser exclusivo em uma região em todas as contas da AWS.

  • Você pode migrar seu nome de domínio personalizado entre endpoints regionais e otimizados para bordas.

  • É 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 ter mais informações, consulte Nomes de domínio personalizados curinga.

  • É possível escolher uma política de segurança para o nome de domínio personalizado. Para ter mais informações, consulte Escolher uma política de segurança para o domínio personalizado da API REST no API Gateway.

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

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 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 e pode ter no máximo 63 octetos por etiqueta e 255 octetos no total.

Especificar o certificado para o nome de domínio personalizado

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

Você pode usar as variáveis de contexto $context.domainName e $context.domainPrefix para determinar o nome de domínio que um cliente usou para chamar sua API. Para saber mais sobre variáveis de contexto, consulte Referência de variáveis de registro em log de acesso e modelo de mapeamento do API Gateway.

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 para solicitar uma exceção.

Próximas etapas para nomes de domínio personalizados

Estas são as próximas etapas para nomes de domínio personalizados:

Próximas etapas

Se for a primeira vez que você cria um nome de domínio personalizado, recomendamos começar com Preparar certificados no AWS Certificate Manager, para especificar o certificado e, depois, Configurar um nome de domínio regional personalizado no API Gateway, para criar um nome de domínio regional personalizado.