Configuración de nombres de dominio personalizados para API de REST - Amazon API Gateway

Configuración de nombres de dominio personalizados para API de REST

Losnombres de dominio personalizados son direcciones URL más sencillas e intuitivas que puede proporcionar a los usuarios de la API.

Después de implementar la API, usted (y sus clientes) puede invocar la API utilizando la URL base predeterminada con el siguiente formato:

https://api-id.execute-api.region.amazonaws.com/stage

donde API Gateway genera api-id, y usted especifica la region (región de AWS) cuando crea la API y la stage cuando implementa la API.

La parte del nombre de host de la URL (es decir, api-id.execute-api.region.amazonaws.com) hace referencia a un punto de enlace de la API. El punto de enlace de la API predeterminado puede ser difícil de recordar y no es muy descriptivo.

Con los nombres de dominio personalizados, puede configurar el nombre de host de la API y elegir una ruta base (por ejemplo, myservice) para asignarle una URL alternativa. Por ejemplo, una URL base de la API más simple puede ser:

https://api.example.com/myservice

Si no establece ningún mapeo de ruta base bajo un nombre de dominio personalizado, la URL base de la API resultante será la misma que la del dominio personalizado (por ejemplo, https://api.example.com). En este caso, el nombre de dominio personalizado no puede admitir más de una API.

nota

Los dominios personalizados de región se pueden asociar con API de REST y API HTTP. Puede utilizar una API de API Gateway versión 2 para crear y administrar nombres de dominio de región personalizados para las API de REST.

Los nombres de dominio personalizados no son compatibles con las API privadas.

Puede elegir la versión mínima de TLS compatible con su API de REST. Para las API de REST, puede elegir TLS 1.2 o TLS 1.0.

Registrar un nombre de dominio

Debe disponer de un nombre de dominio de Internet registrado para poder crear nombres de dominio personalizados para sus API. Si es necesario, puede registrar un dominio de Internet con Amazon Route 53 o un registrador de dominios de un tercero de su elección. Un nombre de dominio personalizado de la API puede ser el nombre de un subdominio o el dominio raíz (lo que recibe el nombre de "ápex de zona") de un dominio de Internet registrado.

Después de crear un nombre de dominio personalizado en API Gateway, debe crear o actualizar el registro de recursos del proveedor de DNS para asignarlo al punto de enlace de la API. Si no se realiza este mapeo, las solicitudes de API vinculadas al nombre de dominio personalizado no pueden llegar a API Gateway.

nota

Un nombre de dominio personalizado optimizado para el borde se crea en una región específica y es propiedad de una determinada cuenta de AWS. Mover este nombre de dominio personalizado entre regiones o cuentas de AWS implica eliminar la distribución de CloudFront existente y crear una nueva. El proceso puede tardar aproximadamente 30 minutos antes de que el nuevo nombre de dominio personalizado esté disponible. Para obtener más información, consulte el tema sobre actualización de distribuciones de CloudFront.

Nombres de dominio personalizados optimizados para bordes

Cuando se implementa una API optimizada para bordes, API Gateway configura una distribución de Amazon CloudFront y un registro DNS para asignar el nombre de dominio de la API al nombre de dominio de distribución de CloudFront. Las solicitudes para la API se redirigen a API Gateway a través de la distribución de CloudFront asignada.

Cuando se crea un nombre de dominio personalizado para una API optimizada para bordes, API Gateway configura una distribución de CloudFront. Pero el usuario debe configurar un registro de DNS para asignar el nombre de dominio personalizado al nombre de dominio de distribución de CloudFront. Este mapeo es para solicitudes de API que estén enlazadas para que el nombre de dominio personalizado se dirija a API Gateway a través de la distribución de CloudFront asignada. También debe proporcionar un certificado para el nombre de dominio personalizado.

nota

La distribución de CloudFront que ha creado API Gateway es propiedad de un cuenta específica de la región afiliada a API Gateway. Cuando realice un seguimiento de las operaciones para crear y actualizar esta distribución de CloudFront en CloudWatch Logs, deberá utilizar este ID de cuenta de API Gateway. Para obtener más información, consulte Registro de la creación del nombre de dominio personalizado en CloudTrail.

Para configurar un nombre de dominio personalizado optimizado para bordes o para actualizar su certificado, debe tener permiso para actualizar las distribuciones de CloudFront. Puede hacerlo asociando la siguiente instrucción de política de IAM a un usuario, grupo o rol de IAM en su cuenta:

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

API Gateway admite nombres de dominio personalizados optimizados para bordes mediante la indicación de nombre de servidor (SNI) en la distribución de CloudFront. Para obtener más información acerca de cómo usar nombres de dominio personalizados en una distribución de CloudFront, incluido el formato de certificado necesario y el tamaño máximo de una longitud de clave de certificado, consulte Usar nombres de dominio alternativos y HTTPS en la guía para desarrolladores de Amazon CloudFront.

Para configurar un nombre de dominio personalizado como el nombre de host de la API, como propietario de la API, debe proporcionar un certificado SSL/TLS para el nombre de dominio personalizado.

Si desea proporcionar un certificado a un nombre de dominio personalizado optimizado para el borde, puede solicitar a AWS Certificate Manager (ACM) que genere un certificado nuevo en ACM o importe en ACM uno emitido por una entidad de certificación externa en la región us-east-1 (EE. UU. Este [Norte de Virginia]).

Nombres de dominio personalizados regionales

Cuando se crea un nombre de dominio personalizado para una API de región, API Gateway crea un nombre de dominio de región para la API. Debe establecer un registro DNS para asignar el nombre de dominio personalizado al nombre de dominio regional. También debe proporcionar un certificado para el nombre de dominio personalizado.

Nombres de dominio personalizados comodín

Con los nombres de dominio personalizados comodín, puede admitir un número casi infinito de nombres de dominio sin exceder el límite predeterminado. Por ejemplo, puede dar a cada uno de los clientes su propio nombre de dominio, customername.api.example.com.

Para crear un nombre de dominio personalizado comodín, especifique un comodín (*) como primer subdominio de un dominio personalizado que represente todos los subdominios posibles de un dominio raíz.

Por ejemplo, el nombre de dominio personalizado comodín *.example.com produce subdominios como a.example.com, b.example.com y c.example.com, que enrutan al mismo dominio.

Los nombres de dominio personalizados comodín admiten configuraciones distintas de los nombres de dominio personalizados estándar de API Gateway. Por ejemplo, en una sola cuenta de AWS, puede configurar *.example.com y a.example.com para que se comporten de manera diferente.

Puede utilizar las variables de contexto $context.domainName y $context.domainPrefix para determinar el nombre de dominio que un cliente utilizó para llamar a la API. Para obtener más información acerca de las variables de contexto, consulte Plantilla de mapeo de API Gateway y referencia de la variable de registro de acceso.

Para crear un nombre de dominio personalizado comodín, debe proporcionar un certificado emitido por ACM que se haya validado utilizando el método DNS o de validación de correo electrónico.

nota

No se puede crear un nombre de dominio personalizado comodín si una cuenta de AWS diferente ha creado un nombre de dominio personalizado que entra en conflicto con el nombre de dominio personalizado comodín. Por ejemplo, si la cuenta A ha creado a.example.com, la cuenta B no puede crear el nombre de dominio personalizado comodín *.example.com.

Si la cuenta A y la cuenta B comparten un propietario, puede contactar con el Centro de soporte de AWS para solicitar una excepción.

Certificados para nombres de dominio personalizados

Para proporcionar un certificado para un nombre de dominio personalizado en una región donde se admita ACM, debe solicitar a ACM un certificado. Para proporcionar un certificado para un nombre de dominio personalizado de región en una región donde no se admita ACM, debe importar un certificado en API Gateway en esa región.

Para importar un certificado SSL/TLS, debe proporcionar el cuerpo del certificado SSL/TLS con formato PEM, su clave privada y la cadena de certificados para el nombre de dominio personalizado. Los certificados almacenados en ACM se identifican mediante su ARN. Para utilizar un certificado administrado por AWS para un nombre de dominio, solo tiene que hacer referencia a su ARN.

ACM facilita la configuración y el uso de un nombre de dominio personalizado para una API. El usuario crea un certificado para el nombre de dominio dado (o importa un certificado), configura el nombre de dominio en API Gateway con el ARN del certificado proporcionado por ACM y asigna una ruta base bajo el nombre de dominio personalizado a una etapa implementada de la API. Con los certificados emitidos por ACM no tiene que preocuparse de si se exponen datos del certificado confidenciales, como la clave privada.