Criar um nome de domínio personalizado otimizado para bordas

Configurar um nome de domínio personalizado otimizado para bordas para uma API do API Gateway

O procedimento a seguir descreve como criar um nome de domínio personalizado para uma API usando o console do API Gateway.

Como criar um nome de domínio personalizado usando o console do API Gateway

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 Create (Criar).

4. Em Domain name (Nome de domínio), insira um nome de domínio

5. Em Configuration (Configuração), escolha Edge-optimized (Otimizado para bordas).

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

7. Excluir um certificado do ACM

   nota

   Para usar um certificado do ACM com um nome de domínio personalizado otimizado para bordas do API Gateway, você deve solicitar ou importar o certificado na região us-east-1 (Leste dos EUA (Norte da Virgínia)).

8. Escolha Create domain name (Criar nome de domínio).

9. Após a criação do nome de domínio personalizado, o console exibe o nome de domínio da distribuição do CloudFront associado, no formato distribution-id.cloudfront.net, junto com o ARN do certificado. 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 valor CNAME do domínio personalizado ou o destino do alias do registro A no seu DNS.

   nota

   O nome de domínio personalizado recém-criado leva cerca de 40 minutos para ficar pronto. Enquanto isso, você pode configurar o alias de registro DNS para mapear o nome de domínio personalizado para o nome de domínio da distribuição do CloudFront associado e configurar o mapeamento do caminho base para o nome de domínio personalizado enquanto este último está sendo inicializado.

10. Em seguida, você configura registros DNS com seu provedor DNS para mapear o nome de domínio personalizado para a distribuição associada do CloudFront. 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.

    Para a maioria dos provedores de DNS, um nome de domínio personalizado é adicionado à zona hospedada como um conjunto de registros de recursos CNAME. O nome do registro CNAME especifica o nome de domínio personalizado que você inseriu anteriormente em Domain Name (Nome do domínio) (por exemplo, api.example.com). O valor do registro CNAME especifica o nome do domínio para a distribuição do CloudFront. No entanto, o uso de um registro CNAME não funcionará se o seu domínio personalizado for um ápice de zona (ou seja, example.com em vez de api.example.com). Um ápice de zona também é conhecido como o domínio raiz da sua organização. Para um ápice de zona, você precisa usar um alias de registro A, desde que ele tenha suporte pelo seu provedor de DNS.

    Com o Route 53, você pode criar um alias de registro A para o seu nome de domínio personalizado e especificar 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.

    O uso de alias de registros A também elimina a exposição do nome de domínio da distribuição do CloudFront subjacente, pois o mapeamento de nome de domínio ocorre exclusivamente no Route 53. Por esses motivos, recomendamos que você use o alias de registro A do Route 53 sempre que possível.

Além de usar o console do API Gateway, você pode usar a API REST do API Gateway, a CLI da AWS ou um dos SDKs da AWS para configurar o nome de domínio personalizado das suas APIs. Como ilustração, o procedimento a seguir descreve as etapas para fazer isso usando as chamadas da API REST.

Como configurar um nome de domínio personalizado usando a API REST do API Gateway

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 valor CNAME do domínio personalizado ou o destino do alias do registro A no seu DNS.

3. Siga o procedimento anterior para configurar um alias de registro A de modo a mapear o nome de domínio personalizado para seu nome de distribuição do CloudFront.

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

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

Região	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 um único nome de domínio personalizado como o nome do host de várias APIs. Para fazer isso, configure os mapeamentos de caminho base no nome de domínio personalizado. Com os mapeamentos de caminho base, uma API no domínio personalizado é acessível por meio da combinação de nome de domínio personalizado e do caminho base associado.

Por exemplo, se você criou uma API chamada PetStore e outra API chamada PetShop e configurou um nome de domínio personalizado de api.example.com no API Gateway, defina o URL da API PetStore como https://api.example.com ou https://api.example.com/myPetStore. A API PetStore está associada ao caminho base de uma string vazia ou a myPetStore no nome de domínio personalizado de api.example.com. Da mesma forma, você pode atribuir um caminho base de yourPetShop para a API PetShop. A URL de https://api.example.com/yourPetShop é então a URL raiz da API PetShop.

Antes de definir o caminho base para uma API, conclua as etapas em Configurar um nome de domínio personalizado otimizado para bordas para uma API do API Gateway.

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

Como criar nomes de mapeamentos de API usando o console do API Gateway

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

2. Escolha um nome de domínio personalizado.

3. Escolha Configure API mappings (Configurar mapeamentos de API).

4. Escolha Add new mapping (Adicionar novo mapeamento).

5. Especifique a API, o Stage (Estágio) e o Path (Caminho) (opcional) para o mapeamento.

6. Escolha Save (Salvar).

Além disso, você pode chamar a API REST do API Gateway, a CLI da AWS ou um dos SDKs da AWS para configurar o mapeamento de caminho base de uma API com um nome de domínio personalizado como seu nome de host. Como ilustração, o procedimento a seguir descreve as etapas para fazer isso usando as chamadas da API REST.

Como configurar o mapeamento do caminho base de uma API usando a API REST do API Gateway

• 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 de solicitação ou importação de um novo certificado do ACM para o nome de domínio especificado.

Para alternar um certificado para um nome de domínio, você pode usar o console do API Gateway, a API REST do API Gateway, a CLI da AWS ou um dos SDKs da AWS.

Como alternar um certificado prestes a expirar importado para o ACM usando o console do API Gateway

1. Solicite ou importe um certificado no ACM.

2. Volte para o console do API Gateway.

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.

5. Selecione Edit.

6. Escolha o certificado desejado na lista suspensa ACM Certificate (Certificado do ACM).

7. Escolha Save para começar a revezar o certificado para o nome de domínio personalizado.

   nota

   Demora cerca de 40 minutos para terminar o processo. Após o revezamento, você pode escolher o ícone de seta bidirecional ao lado de ACM Certificate para reverter para o certificado original.

Para ilustrar como alternar programaticamente um certificado importado para um nome de domínio personalizado, descrevemos as etapas usando a API REST do API Gateway.

Alternar um certificado importado usando a API REST do API Gateway

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

URLs raiz de APIs com nomes de domínio padrão e personalizados
ID de API	Estágio	URL padrão	Caminho base	URL personalizado
udxjef	pro	https://udxjef.execute-api.us-east-1.amazonaws.com/pro	/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.