Configurar um nome de domínio regional personalizado no API Gateway - Amazon API Gateway
ConsideraçõesCriar um nome de domínio regional personalizado Criar um registro DNS para o nome de domínio regional personalizado Criar um mapeamento de caminho de base para o nome de domínio regional personalizado

Configurar um nome de domínio regional personalizado no API Gateway

Use um nome de domínio regional personalizado para criar um URL de base de API fácil de usar. Com um nome de domínio regional personalizado, é possível mapear os estágios da API REST e HTTP para o mesmo nome de domínio personalizado e usar a autenticação TLS mútua.

Considerações

Veja a seguir as considerações sobre o nome de domínio regional personalizado.

  • É necessário fornecer um certificado do ACM específico da região. Esse certificado deve estar na mesma região que a API. Para obter mais informações sobre a criação ou upload de um certificado de nome de domínio personalizado, consulte Preparar certificados no AWS Certificate Manager.

  • Quando você cria um nome de domínio regional personalizado (ou migra um) com um certificado do ACM, o API Gateway cria um perfil vinculado ao serviço na sua conta. A função vinculada ao serviço é necessária para anexar seu certificado do ACM ao seu endpoint regional. A função é denominada AWSServiceRoleForAPIGateway e tem a política gerenciada APIGatewayServiceRolePolicy anexada a ela. Para obter mais informações sobre como usar a função vinculada ao serviço, consulte Usar funções vinculadas ao serviço.

  • Depois de criar o nome de domínio regional personalizado, você deve criar um registro DNS para apontar o nome de domínio personalizado para o nome de domínio regional. Isso permite que o tráfego vinculado ao nome de domínio personalizado seja roteado para o nome de host regional da API. O registro DNS pode ser do tipo CNAME ou “A”.

Criar um nome de domínio regional personalizado

O procedimento a seguir mostra como criar um nome de domínio regional personalizado. Depois de concluir esse procedimento, você deve criar um registro DNS para apontar o nome de domínio personalizado para o nome de domínio regional.

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

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

  5. Em Configuration (Configuração), escolha Regional.

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

  7. Excluir um certificado do ACM O certificado deve estar na mesma região que a API.

  8. Escolha Create (Criar).

AWS CLI

O seguinte comando create-domain-name pode ser usado para criar um nome de domínio personalizado:

aws apigatewayv2 create-domain-name \ 
    --domain-name 'regional.example.com' \
    --domain-name-configurations CertificateArn=arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678

Se houver êxito, a chamada retornará um resultado semelhante ao seguinte:

{
    "ApiMappingSelectionExpression": "$request.basepath",
    "DomainName": "regional.example.com",
    "DomainNameConfigurations": [
        {
            "ApiGatewayDomainName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
            "CertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/123456789012-1234-1234-1234-12345678",
            "DomainNameStatus": "AVAILABLE",
            "EndpointType": "REGIONAL",
            "HostedZoneId": "Z2OJLYMUO9EFXC",
            "SecurityPolicy": "TLS_1_2"
        }
    ]
}

O valor da propriedade DomainNameConfigurations retorna o nome de host da API regional. Você deve criar um registro DNS para apontar seu nome de domínio personalizado para esse nome de domínio regional. Isso permite que o tráfego vinculado ao nome de domínio personalizado seja roteado para o nome de host dessa API regional.

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

O procedimento a seguir mostra como criar um registro DNS para apontar o nome de domínio personalizado para o nome de domínio regional recém-criado.

AWS Management Console

Para usar o AWS Management Console, siga a documentação do Route 53 sobre como configurar o Route 53 para rotear o tráfego para o API Gateway.

AWS CLI

Para configurar os registros DNS para mapear o nome de domínio regional personalizado para o nome de host do ID de zona hospedada fornecido, primeiro crie um arquivo JSON que contenha a configuração de um registro DNS para o nome de domínio regional.

O setup-dns-record.json a seguir mostra como criar um registro DNS A para mapear um nome de domínio regional personalizado (regional.example.com) ao nome de host regional (d-numh1z56v6.execute-api.us-west-2.amazonaws.com) provisionado como parte da criação do nome de domínio personalizado. As propriedades DNSName e HostedZoneId de AliasTarget podem ter os valores regionalDomainName e regionalHostedZoneId respectivamente do nome de domínio personalizado. Também é possível obter os IDs de zona hospedada regional do Route 53 em Endpoints e cotas do Amazon API Gateway.

{
  "Changes": [
    {
      "Action": "CREATE",
      "ResourceRecordSet": {
        "Name": "regional.example.com",
        "Type": "A",
        "AliasTarget": {
          "DNSName": "d-numh1z56v6.execute-api.us-west-2.amazonaws.com",
          "HostedZoneId": "Z2OJLYMUO9EFXC",
          "EvaluateTargetHealth": false
        }
      }
    }
  ]
}

O seguinte change-resource-record-sets mostra como criar um registro DNS para o nome de domínio regional personalizado:

aws route53 change-resource-record-sets \
    --hosted-zone-id Z2OJLYMUO9EFXC \
    --change-batch file://path/to/your/setup-dns-record.json

Substitua hosted-zone-id pelo ID da zona hospedada do Route 53 do conjunto de registros DNS na conta. O valor do parâmetro change-batch aponta para um arquivo JSON (setup-dns-record.json) em uma pasta (path/to/your).

Criar um mapeamento de caminho de base para o nome de domínio regional personalizado

Depois de criar um registro DNS, você cria um mapeamento de caminho de base para mapear a API para o nome de domínio personalizado. Por exemplo, é possível mapear o estágio test do ID da API de abc123 para o nome de domínio personalizado regional.example.com usando a chave de mapeamento da API de myApi. Isso mapeia a API https://abcd1234.execute-api.us-west-2.amazonaws.com/test para https://regional.example.com/myApi.

AWS Management Console

  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) para o mapeamento.

  6. Escolha Salvar.

AWS CLI

O comando create-api-mapping a seguir pode ser usado para criar um mapeamento de caminho de base:

aws apigatewayv2 create-api-mapping \
    --domain-name 'regional.example.com' \
    --api-mapping-key 'myApi' \
    --api-id abcd1234 \
    --stage 'test'

Como resultado, a URL base usando o nome de domínio personalizado para a API que é implantada na etapa se torna https://regional.example.com/myAPI.

Com um nome de domínio regional personalizado, é possível criar um mapeamento de API com vários níveis, como https://regional.example.com/orders/v1/items/123. Você também pode mapear os estágios da API REST e HTTP para o mesmo nome de domínio personalizado. Para ter mais informações, consulte Mapear estágios de API para um nome de domínio personalizado.