Configurar um nome de domínio regional personalizado no API Gateway - Amazon API Gateway
ConsideraçõesCriar um nome de domínio regional personalizado Criar uma regra de roteamento para o nome de domínio regional personalizadoCriar um registro DNS 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 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 de DNS para apontar o nome de domínio personalizado para o 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 de DNS pode ser o CNAME ou um registro de alias A. Se você usa o Route 53 como provedor de DNS, crie um registro de alias A. Se você usa um provedor de DNS de terceiros, use um registro CNAME. Se você usar um registro CNAME e criar um endpoint da VPC de interface do API Gateway com DNS privado habilitado para uma API privada, não poderá resolver o nome de domínio personalizado na VPC que hospeda a API privada.

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, crie uma regra de roteamento para rotear estágios da API para o nome de domínio personalizado.

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 Modo de roteamento, escolha Somente regras de roteamento.

    Nesse modo de roteamento, você só pode enviar tráfego do seu nome de domínio personalizado às suas APIs usando regras de roteamento. Para obter mais informações, consulte Encaminhar o tráfego às APIs por meio do nome de domínio personalizado no API Gateway.

  6. Em Versão mínima do TLS, selecione uma versão.

  7. Em Configuração de endpoint, em Tipo de endpoint de API, selecione Regional.

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

  9. Escolha Criar.

AWS CLI

O comando create-domain-name indicado abaixo cria 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 \
      --routing-mode ROUTING_RULE_ONLY

A saída será exibida da seguinte forma:

{
    "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"
        }
        "RoutingMode": "ROUTING_RULE_ONLY"
    ]
}

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 uma regra de roteamento para o nome de domínio regional personalizado

Depois de criar um nome de domínio personalizado, configure como o tráfego é encaminhado do nome de domínio personalizado às APIs. Como o modo de roteamento é definido como ROUTING_RULE_ONLY, você usa regras de roteamento para encaminhar às suas APIs as solicitações recebidas em seu nome de domínio personalizado.

Neste exemplo, você cria uma regra abrangente que encaminha a um estágio da API todas as solicitações recebidas em seu nome de domínio personalizado. Você também pode configurar regras de roteamento com base em diferentes condições de cabeçalho e caminho. Para obter mais informações, consulte Regras de roteamento para associar estágios da API a um nome de domínio personalizado para APIs REST.

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. Na guia Detalhes do roteamento, escolha Adicionar regra de roteamento.

  4. Escolha Adicionar uma nova condição para adicionar uma nova condição.

  5. Mantenha essa regra sem nenhuma condição. Isso direciona todas as solicitações para seu nome de domínio personalizado à API de destino e ao estágio de destino.

  6. Em Ação, use o menu suspenso para selecionar a API e o estágio de destino.

  7. Escolha Próximo.

  8. No campo de prioridade, insira 100.

    O API Gateway avalia as regras em ordem de prioridade, do valor mais baixo para o valor mais alto. Como essa é uma regra abrangente, você usa uma prioridade alta para que o API Gateway primeiro faça a correspondência com qualquer regra adicional que você criar primeiro.

  9. Selecione Criar regra de roteamento.

AWS CLI

O comando create-routing-rule apresentado abaixo cria uma regra de roteamento abrangente:

aws apigatewayv2 create-routing-rule \
  --domain-name 'regional.example.com' \
  --priority 100 \
  --conditions  \
  --actions '[{
    "InvokeApi": {
      "ApiId": "a1b2c3",
      "Stage": "prod"
    }
  }]'

Você pode alterar o modo de roteamento e criar outras regras a qualquer momento. Para obter mais informações, consulte Encaminhar o tráfego às APIs por meio do nome de domínio personalizado no API Gateway.

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

Depois de criar o nome de domínio personalizado e mapeamentos de caminho base, crie um registro de 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 comando change-resource-record-sets indicado abaixo cria um registro de DNS para o nome de domínio personalizado regional:

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