Configurar um nome de domínio personalizado otimizado para borda no API Gateway - Amazon API Gateway
ConsideraçõesCriar um nome de domínio personalizado otimizado para bordaCriar um registro DNS para o nome de domínio personalizado otimizado para bordaRegistrar a criação do nome de domínio personalizado no CloudTrail em logConfigurar o mapeamento de caminho base de uma API com um nome de domínio personalizado como seu nome de hostAlternar um certificado importado para o ACMChamar a API com nomes de domínio personalizado

Configurar um nome de domínio personalizado otimizado para borda no API Gateway

Quando você cria um nome de domínio personalizado para uma API otimizada para borda, o API Gateway configura uma distribuição do 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. 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.

Considerações

Veja a seguir algumas considerações sobre o nome de domínio personalizado otimizado para borda.

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

    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": [
                "*"
            ]
        }
    ]
}

  • É necessário solicitar ou importar um certificado para o nome de domínio personalizado otimizado para borda na região Leste dos EUA (N. da Virgínia): us-east-1.

  • 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 CloudTrail, você deve usar esse ID de conta do API Gateway. Para ter mais informações, consulte Registrar a criação do nome de domínio personalizado no CloudTrail em log.

  • 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. Consulte 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 uma chave de certificado, em Usar nomes de domínio alternativos e HTTPS no Guia do desenvolvedor do Amazon CloudFront.

  • Um nome de domínio personalizado otimizado para borda leva cerca de 40 minutos para ficar pronto.

  • Após criar o nome de domínio personalizado otimizado para borda, é necessário criar um registro DNS para mapear o nome de domínio personalizado para o nome da distribuição do CloudFront.

Criar um nome de domínio personalizado otimizado para borda

O procedimento a seguir descreve como criar um nome de domínio personalizado otimizado para borda para uma API.

AWS Management Console

  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) no painel de navegação principal.

  3. Escolha Adicionar nome do domínio.

  4. Em Nome de domínio, insira um nome de domínio

  5. Em Tipo de endpoint de API, escolha Otimizado para a borda.

  6. Escolha uma versão mínima de TLS.

  7. Excluir um certificado do ACM

  8. Escolha Adicionar nome do domínio.

REST API

  1. Chame domainname:create, especificando o nome de domínio personalizado e o ARN de um certificado armazenado no AWS Certificate Manager.

    A chamada de API bem-sucedida retorna uma resposta 201 Created que contém o ARN do certificado e o nome da distribuição do CloudFront associada em sua carga útil.

  2. Observe o nome de domínio da distribuição do CloudFront mostrado na saída. Você precisará disso na próxima etapa para definir o destino do alias do registro A do domínio personalizado no seu DNS.

Para exemplos de código dessa chamada de API REST, consulte domainname:create.

Um nome de domínio personalizado otimizado para borda leva cerca de 40 minutos para ficar pronto, mas o console exibe imediatamente o nome de domínio da distribuição do CloudFront associado, no formato distribution-id.cloudfront.net, junto com o ARN do certificado. Enquanto isso, você pode continuar na próxima etapa e configurar o alias do registro DNS para mapear o nome de domínio personalizado para o nome de domínio da distribuição do CloudFront associado.

Criar um registro DNS para o nome de domínio personalizado otimizado para borda

Depois de iniciar a criação do nome de domínio personalizado otimizado para borda, configure o alias do registro DNS.

Recomendamos que você use o Route 53 para criar um alias de registro A para o nome de domínio personalizado e especifique o nome de domínio da distribuição do CloudFront como o destino do alias. Isso significa que o Route 53 pode rotear seu nome de domínio personalizado, mesmo que seja um apex de zona. Para obter mais informações, consulte Escolher entre conjuntos de registros de recursos de alias e não alias no Guia do desenvolvedor do Amazon Route 53.

Para obter instruções sobre o Amazon Route 53, consulte Como rotear o tráfego para uma API do Amazon API Gateway usando o seu nome de domínio no Guia do desenvolvedor do Amazon Route 53.

Registrar a criação do nome de domínio personalizado no CloudTrail em log

Quando o CloudTrail está habilitado para registrar em log as chamadas do API Gateway feitas pela sua conta, o API Gateway registra as atualizações da distribuição do CloudFront associadas quando um nome de domínio personalizado é criado ou atualizado para uma API. Esses logs estão disponíveis em us-east-1. Como essas distribuições do CloudFront são de propriedade do API Gateway, cada uma dessas distribuições do CloudFront reportadas é identificada por um dos seguintes IDs de conta do API Gateway específicos da região, e não pelo ID da conta do proprietário da API.

Region

ID da conta
us-east-1 392220576650
us-east-2 718770453195
us-west-1 968246515281
us-west-2 109351309407
ca-central-1 796887884028
eu-west-1 631144002099
eu-west-2 544388816663
eu-west-3 061510835048
eu-central-1 474240146802
eu-central-2 166639821150
eu-north-1 394634713161
eu-south-1 753362059629
eu-south-2 359345898052
ap-northeast-1 969236854626
ap-northeast-2 020402002396
ap-northeast-3 360671645888
ap-southeast-1 195145609632
ap-southeast-2 798376113853
ap-southeast-3 652364314486
ap-southeast-4 849137399833
ap-south-1 507069717855
ap-south-2 644042651268
ap-east-1 174803364771
sa-east-1 287228555773
me-south-1 855739686837
me-central-1 614065512851

Configurar o mapeamento de caminho base de uma API com um nome de domínio personalizado como seu nome de host

Você pode usar o mapeamento de caminho de base para usar um único nome de domínio personalizado como o nome do host de várias APIs. Isso torna uma API acessível por meio da combinação do nome de domínio personalizado e do caminho base associado.

Por exemplo, se, no API Gateway, você criou uma API chamada PetStore e outra API chamada Dogs e configurou um nome de domínio personalizado de api.example.com, pode definir o URL da API PetStore como https://api.example.com.

Isso associa a API PetStore ao caminho base de uma string vazia. Se você definir o URL da API PetStore como https://api.example.com/PetStore, isso associará a API PetStore ao caminho base de PetStore. É possível atribuir um caminho base de MyDogList para a API Dogs. A URL de https://api.example.com/MyDogList é então a URL raiz da API Dogs.

Para configurar mapeamentos de API em vários níveis, você só pode usar um nome de domínio regional personalizado. Os nomes de domínio personalizados otimizados para borda não são compatíveis. Para ter mais informações, consulte Associar estágios de API a um nome de domínio personalizado para APIs REST.

O procedimento a seguir configura mapeamentos de API para mapear caminhos de seu nome de domínio personalizado para seus estágios de API.

AWS Management Console

  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) no painel de navegação principal.

  3. Escolha um nome de domínio personalizado otimizado para borda.

  4. Na guia Mapeamentos de API, escolha Configurar mapeamentos de API.

  5. Especifique a API, o Estágio e o Caminho do mapeamento.

  6. Escolha Salvar.

REST API

Chame basepathmapping:create em um nome de domínio personalizado, especificando basePath, restApiId e uma propriedade stage de implantação na carga útil da solicitação.

A chamada de API bem-sucedida retorna uma resposta 201 Created.

Para exemplos de código da chamada de API REST, consulte basepathmapping:create.

Alternar um certificado importado para o ACM

O ACM lida automaticamente com a renovação dos certificados que ele emite. Não é necessário alternar certificados emitidos pelo ACM para seus nomes de domínio personalizados. O CloudFront se encarrega disso em seu nome.

No entanto, se você importar um certificado para o ACM e usá-lo para um nome de domínio personalizado, deverá alternar o certificado antes que ele expire. Isso envolve importar um novo certificado de terceiro para o nome de domínio e revezar o certificado existente para o novo. Você precisará repetir o processo quando o certificado recém-importado expirar. Como alternativa, você pode solicitar que o ACM emita um novo certificado para o nome de domínio e alterne esse certificado existente com o novo certificado emitido pelo ACM. Depois disso, é possível deixar o ACM e o CloudFront encarregados de lidar com a alternância de certificados para você automaticamente. Para criar ou importar um novo certificado do ACM, siga as etapas em Como criar ou importar um certificado SSL/TLS no ACM.

O procedimento a seguir descreve como alternar um certificado para um nome de domínio.

nota

Leva cerca de 40 minutos para alternar um certificado importado no ACM.

AWS Management Console

  1. Solicite ou importe um certificado no ACM.

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

  3. Escolha Custom domain names (Nomes de domínio personalizados) no painel de navegação principal do console do API Gateway.

  4. Escolha um nome de domínio personalizado otimizado para borda.

  5. Em Configuração de endpoint, escolha Editar.

  6. Em Certificado do ACM, selecione um certificado na lista suspensa.

  7. Escolha Salvar alterações para começar a alternar o certificado para o nome de domínio personalizado.

REST API

Chame a ação domainname:update, especificando o ARN do novo certificado do ACM para o nome de domínio especificado.

Chamar a API com nomes de domínio personalizado

Chamar uma API com um nome de domínio personalizado é o mesmo que chamá-la com o nome de domínio padrão, desde que a URL correta seja utilizada.

Os exemplos a seguir comparam e contrastam um conjunto de URLs padrão e as URLs personalizadas correspondentes de duas APIs (udxjef e qf3duz) em uma região especificada (us-east-1) e de um determinado nome de domínio personalizado (api.example.com).

ID de API Estágio URL padrão Caminho base URL personalizado
udxjef prod https://udxjef.execute-api.us-east-1.amazonaws.com/prod /petstore https://api.example.com/petstore
udxjef tst https://udxjef.execute-api.us-east-1.amazonaws.com/tst /petdepot https://api.example.com/petdepot
qf3duz dev https://qf3duz.execute-api.us-east-1.amazonaws.com/dev /bookstore https://api.example.com/bookstore
qf3duz tst https://qf3duz.execute-api.us-east-1.amazonaws.com/tst /bookstand https://api.example.com/bookstand

O API Gateway oferece suporte a nomes de domínio personalizados para uma API usando a Indicação de nome de servidor (SNI). Você pode invocar a API com um nome de domínio personalizado usando um navegador ou uma biblioteca de cliente que ofereça suporte a SNIs.

O API Gateway impõe o SNI na distribuição do CloudFront. Para obter informações sobre como o CloudFront usa nomes de domínio personalizados, consulte SSL personalizado no Amazon CloudFront.