Nomes de domínio personalizados para APIs de WebSocket 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,
, 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.api-id
.execute-api.region
.amazonaws.com
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.
-
Se mapear um nome de domínio personalizado para uma API de WebSocket, você não poderá mapeá-lo para uma API REST ou uma API HTTP.
-
Somente nomes de domínio regionais personalizados são compatíveis.
-
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 ter mais informações, consulte Nomes de domínio personalizados curinga.
Pré-requisitos
Veja a seguir os pré-requisitos de 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
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 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
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 ter mais informações, consulte Preparar certificados no AWS Certificate Manager. Depois, crie um nome de domínio regional personalizado. Para ter mais informações, consulte Configurar um nome de domínio regional personalizado no API Gateway.