Configurar nomes de domínio personalizados para APIs REST - Amazon API Gateway
Registrar um nome de domínioNomes de domínio personalizados otimizados para bordasNomes de domínio personalizados regionaisNomes de domínio personalizados curingaCertificados para nomes de domínio personalizados

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Configurar nomes de domínio personalizados para APIs REST

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 (região da AWS) é especificada por você ao criar a API e stage é especificado por você ao implantar a API.

A parte do nome de host do URL (ou seja, api-id.execute-api.region.amazonaws.com) refere-se a um endpoint de API. O endpoint de API padrão pode ser difícil de chamar novamente e pode não ser amigável.

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
nota

Um domínio personalizado regional pode ser associado a APIs REST e APIs HTTP. É possível usar APIs do API Gateway Versão 2 para criar e gerenciar nomes de domínio personalizados regionais para APIs REST.

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

Você pode escolher uma versão TLS mínima compatível com a API REST. Para APIs REST, é possível escolher TLS 1.2 ou TLS 1.0.

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. Se necessário, é possível registrar um 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 de uma API pode ser o nome de um subdomínio ou do domínio raiz (também conhecido como "apex de zona") de um domínio da Internet registrado.

Depois da criação de um nome de domínio personalizado no API Gateway, você deve criar ou atualizar o registro de recursos do provedor DNS a fim de mapear para o 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.

nota

Um nome de domínio personalizado otimizado para borda é criado em uma região específica e pertence a determinada conta da AWS. A movimentação desse nome de domínio personalizado entre regiões ou contas da AWS envolve a exclusão da distribuição existente do CloudFront e a criação de outra. O processo pode levar aproximadamente 30 minutos antes que o novo nome de domínio personalizado torna-se disponível. Para obter mais informações, consulte Atualizar distribuições do CloudFront.

Nomes de domínio personalizados otimizados para bordas

Quando você implanta uma API otimizada para bordas, o API Gateway configura uma distribuição do Amazon CloudFront e um registro DNS para mapear o nome de domínio da API para o nome de domínio da distribuição do CloudFront. Solicitações para a API são roteadas para o API Gateway por meio da distribuição mapeada do CloudFront.

Quando você cria um nome de domínio personalizado para uma API otimizada para bordas, o API Gateway configura uma distribuição do CloudFront. No entanto, você deve configurar um registro DNS para mapear o nome de domínio personalizado para o nome de domínio da distribuição do CloudFront. Esse mapeamento refere-se a solicitações de API vinculadas ao nome de domínio personalizado a ser roteado para o API Gateway por meio da distribuição mapeada do CloudFront. Você também deve fornecer um certificado para o nome de domínio personalizado.

nota

A distribuição do CloudFront criada pelo API Gateway pertence a uma conta específica da região afiliada ao API Gateway. Ao rastrear operações para criar e atualizar essa distribuição do CloudFront no CloudWatch Logs, você deve usar esse ID de conta do API Gateway. Para obter mais informações, consulte Registrar a criação do nome de domínio personalizado no CloudTrail em log.

Para configurar um nome de domínio personalizado otimizado para bordas ou atualizar seu certificado, você deve ter uma permissão para atualizar as distribuições do CloudFront.

Para fornecer o acesso, adicione as permissões aos seus usuários, grupos ou perfis:

  • Usuários e grupos no AWS IAM Identity Center:

    Crie um conjunto de permissões. Siga as instruções em Create a permission set (Criação de um conjunto de permissões) no Guia do usuário do AWS IAM Identity Center.

  • Usuários gerenciados no IAM usando um provedor de identidade:

    Crie um perfil para a federação de identidades. Siga as instruções em Criar um perfil para um provedor de identidade de terceiros (federação) no Guia do usuário do IAM.

  • Usuários do IAM:

    • Crie um perfil que seu usuário possa assumir. Siga as instruções em Creating a role for an IAM user (Criação de um perfil para um usuário do IAM) no Guia do usuário do IAM.

    • (Não recomendado) Vincule uma política diretamente a um usuário ou adicione um usuário a um grupo de usuários. Siga as instruções em Adição de permissões a um usuário (console) no Guia do usuário do IAM.

As seguintes permissões são necessárias para atualizar as distribuições do CloudFront. 

{
    "Version": "2012-10-17",
    "Statement": [
         {
            "Sid": "AllowCloudFrontUpdateDistribution",
            "Effect": "Allow",
            "Action": [
                "cloudfront:updateDistribution"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

O API Gateway oferece suporte a nomes de domínio personalizados otimizados para bordas, otimizando a Indicação de nome de servidor (SNI) na distribuição do CloudFront. Para obter mais informações sobre como usar nomes de domínio personalizados em uma distribuição do CloudFront, incluindo o formato de certificado necessário e o tamanho máximo de um comprimento de chave de certificado, consulte Usar nomes de domínio alternativos e HTTPS no Guia do desenvolvedor do Amazon CloudFront.

Para configurar um nome de domínio personalizado como o nome de host da API, você, como proprietário da API, deve fornecer um certificado SSL/TLS para o nome de domínio personalizado.

Para fornecer um certificado para um nome de domínio personalizado otimizado para borda, é possível solicitar que o AWS Certificate Manager (ACM) gere um novo certificado no ACM ou importar para o ACM um outro certificado emitido por uma autoridade de certificação de terceiros na região us-east-1 (Leste dos EUA, Norte da Virgínia).

Nomes de domínio personalizados regionais

Quando um nome de domínio personalizado é criado para uma API regional, o API Gateway cria um nome de domínio regional para a API. Você deve configurar um registro DNS para mapear o nome de domínio personalizado para o nome de domínio regional. Você também deve fornecer um certificado para o nome de domínio personalizado.

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.

Certificados para nomes de domínio personalizados

Importante

Você especifica o certificado para o seu nome de domínio personalizado. 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.

Para fornecer um certificado para um nome de domínio personalizado em uma região compatível com o ACM, é necessário solicitar um certificado do ACM. Para fornecer um certificado para um nome de domínio personalizado regional em uma região onde não haja suporte para o ACM, é 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. Para usar um certificado gerenciado pela AWS para um nome de domínio, basta fazer referência ao seu ARN.

O ACM simplifica a configuração e o uso de um nome de domínio personalizado para uma API. Crie um certificado para o nome de domínio determinado (ou importe um certificado), configure o nome de domínio no API Gateway com o ARN do certificado fornecido pelo ACM e mapeie um caminho base no nome de domínio personalizado para um estágio implantado da API. Com certificados emitidos pelo ACM, não é necessário se preocupar em expor detalhes de certificados confidenciais, como a chave privada.

Tópicos