# Tutorial: como criar e invocar um nome de domínio personalizado para APIs privadas Neste tutorial, você cria um nome de domínio personalizado privado que pode ser invocado em uma VPC em sua conta. Para conseguir isso, você é o provedor e o consumidor da API. Você precisa de uma API privada e de um endpoint da VPC existentes para concluir este tutorial. Se você usa um endpoint da VPC para acessar um nome de domínio personalizado público, não o use para este tutorial ou para criar associações de acesso a nomes de domínio. ## Etapa 1: criar um nome de domínio personalizado Para criar um nome de domínio personalizado privado, especifique o nome de domínio, o certificado do ACM e a política do serviço `execute-api` para controlar quais endpoints da VPC podem invocá-lo. ------ #### [ Console de gerenciamento da AWS ] **Como criar um nome de domínio personalizado** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. No painel de navegação principal, selecione **Nomes de domínio personalizados**. 1. Escolha **Adicionar nome do domínio**. 1. Em **Nome de domínio**, insira um nome de domínio Seu certificado do ACM deve abranger esse nome de domínio, mas o nome de domínio não precisa ser exclusivo. 1. Selecione **Privado**. 1. Em **Modo de roteamento**, escolha **Somente mapeamentos de API**. 1. Em **Certificado do ACM**, escolha um certificado. 1. Escolha **Adicionar nome do domínio**. O API Gateway provisiona um nome de domínio com uma política `deny` que nega acesso a todos os recursos. Essa é a política de recursos do serviço `execute-api`. Você precisa atualizar essa política de recursos para conceder acesso aos seus endpoints da VPC e permitir que eles invoquem seu nome de domínio personalizado privado. **Como atualizar sua política de recursos** 1. Escolha a guia **Política de recursos** e selecione **Editar política de recursos**. 1. Insira a política de recursos a seguir no editor de código. Substitua o endpoint da VPC {{vpce-abcd1234efg}} pelo seu ID de endpoint da VPC. **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "{{vpce-abcd1234}}" } } } ] } ``` 1. Escolha **Salvar alterações**. ------ #### [ AWS CLI ] Ao criar um nome de domínio personalizado privado usando a AWS CLI, você fornece uma política de recursos para o serviço `execute-api` conceder acesso aos endpoints da VPC e permitir que eles invoquem seu nome de domínio personalizado privado por meio do parâmetro `--policy file://policy.json`. Você pode modificar essa política posteriormente. Neste exemplo, você anexará a política de recursos a seguir como `policy` carregando os parâmetros de um arquivo. Copie e salve esse arquivo como `policy.json`. Essa política permite apenas tráfego de entrada para um nome de domínio personalizado privado originado do endpoint da VPC {{ `vpce-abcd1234efg`}}: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ] }, { "Effect": "Deny", "Principal": "*", "Action": "execute-api:Invoke", "Resource": [ "execute-api:/*" ], "Condition" : { "StringNotEquals": { "aws:SourceVpce": "{{vpce-abcd1234}}" } } } ] } ``` O comando [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-domain-name.html) indicado abaixo cria um nome de domínio personalizado privado: ``` aws apigateway create-domain-name \ --domain-name 'private.example.com' \ --certificate-arn 'arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef' \ --security-policy 'TLS_1_2' \ --endpoint-configuration '{"types":["PRIVATE"]}' \ --policy file://policy.json ``` A saída será exibida da seguinte forma: ``` { "domainName": "private.example.com", "domainNameId": "abcd1234", "domainNameArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234", "certificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef", "certificateUploadDate": "2024-09-10T10:31:20-07:00", "endpointConfiguration": { "types": [ "PRIVATE" ] }, "domainNameStatus": "AVAILABLE", "securityPolicy": "TLS_1_2", "routingMode" : "API_MAPPING_ONLY", "policy": "..." } ``` ------ ## Etapa 2: criar um mapeamento de caminho base para associar a API privada ao nome de domínio personalizado privado Depois de criar um nome de domínio personalizado privado, você associa uma API privada a ele. O mapeamento de caminho base torna uma API acessível por meio da combinação do nome de domínio personalizado e do caminho base correspondente. Recomendamos usar um único nome de domínio personalizado privado como o nome do host de várias APIs privadas. Todos os provedores de API precisam criar um mapeamento de caminho base, mesmo que você não pretenda invocar sua API. Também é necessário conceder acesso para que os endpoints da VPC invoquem quaisquer APIs privadas que você associa ao nome de domínio personalizado privado. ------ #### [ Console de gerenciamento da AWS ] **Como criar um mapeamento de caminho base** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. No painel de navegação principal, selecione **Nomes de domínio personalizados**. 1. Escolha um nome de domínio personalizado privado. 1. Na guia **Mapeamentos de API**, escolha **Configurar mapeamentos**. 1. Escolha **Add new mapping (Adicionar novo mapeamento)**. 1. Insira uma **API**, um **Estágio** e, opcionalmente, um **Caminho**. 1. Escolha **Salvar**. ------ #### [ AWS CLI ] O comando [create-base-path-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-base-path-mapping.html) indicado abaixo criar um mapeamento entre uma API privada e um nome de domínio personalizado privado: ``` aws apigateway create-base-path-mapping \ --domain-name-id abcd1234 \ --domain-name 'private.example.com' \ --rest-api-id a1b2c3 \ --stage prod \ --base-path v1 ``` A saída será exibida da seguinte forma: ``` { "basePath": "v1", "restApiId": "a1b2c3", "stage": "prod" } ``` ------ Para ter maior flexibilidade em relação a como você direciona o tráfego para as APIs, você pode alterar o modo de roteamento para `ROUTING_RULE_ONLY` ou `ROUTING_RULE_THEN_API_MAPPING` e criar uma regra 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](rest-api-routing-mode.md). **nota** Se você quiser que outras Contas da AWS invoquem seu nome de domínio personalizado privado, depois de concluir este tutorial, siga as etapas em [Provedor de API: compartilhar seu nome de domínio personalizado privado usando o AWS RAM](apigateway-private-custom-domains-provider-share.md). ## Etapa 3: criar uma associação de acesso ao nome de domínio entre o nome de domínio personalizado e um endpoint da VPC Em seguida, você cria uma associação de acesso ao nome de domínio entre o nome de domínio personalizado privado e o endpoint da VPC. Seu endpoint da VPC usa a associação de acesso ao nome de domínio para invocar o nome de domínio personalizado privado enquanto está isolado da internet pública. ------ #### [ Console de gerenciamento da AWS ] **Como criar uma associação de acesso ao nome de domínio** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. No painel de navegação principal, selecione **Nomes de domínio personalizados**. 1. Escolha um nome de domínio personalizado privado. 1. Na guia **Compartilhamento de recursos**, em **Associações de acesso a nomes de domínio**, escolha **Criar associação de acesso a nomes de domínio**. 1. Em **ARN do nome do domínio**, selecione seu nome de domínio. 1. Em **IDs de endpoint da VPC**, selecione o ID de endpoint da VPC ao qual você forneceu acesso na Etapa 1. 1. Escolha **Associação de acesso a nomes de domínio**. Você também pode criar sua associação de acesso ao nome de domínio usando a página **Associações de acesso a nomes de domínio** do console. ------ #### [ AWS CLI ] O comando `create-domain-name-access-association` a seguir cria uma associação de acesso ao nome de domínio entre o nome de domínio personalizado privado e o endpoint da VPC. ``` aws apigateway create-domain-name-access-association \ --domain-name-arn arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234 \ --access-association-source vpce-abcd1234efg \ --access-association-source-type VPCE \ --region us-west-2 ``` A saída será exibida da seguinte forma: ``` { "domainNameAccessAssociationARN": "arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg", "accessAssociationSource": "vpce-abcd1234efg", "accessAssociationSourceType": "VPCE", "domainNameARN" : "arn:aws:apigateway:us-west-2:111122223333:/domainnames/private.example.com+abcd1234" } ``` ------ Depois que a associação de acesso ao nome de domínio é criada, ela leva cerca de 15 minutos para ficar pronta. Enquanto isso, você pode prosseguir com as etapas a seguir. ## Etapa 4: criar uma zona hospedada do Route 53 Depois de atualizar sua política de recursos e associar o nome de domínio personalizado privado ao endpoint da VPC, você cria uma zona hospedada privada no Route 53 para resolver o nome de domínio personalizado. Zona hospedada é um contêiner que abriga informações sobre como você deseja rotear o tráfego para um domínio dentro de uma ou mais VPCs sem expor seus recursos à internet. Para obter mais informações, consulte [Como trabalhar com zonas hospedadas privadas](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-private.html). ------ #### [ Console de gerenciamento da AWS ] Para usar o Console de gerenciamento da AWS, consulte [Creating a private hosted zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zone-private-creating.html) no *Guia do desenvolvedor do Amazon Route 53*. Em **Nome**, use o nome do seu domínio personalizado privado. Em **ID da VPC**, use a VPC que contém o endpoint da VPC que você usou nas etapas anteriores. ------ #### [ AWS CLI ] O comando [create-hosted-zone](https://docs.aws.amazon.com/cli/latest/reference/route53/create-hosted-zone.html) indicado abaixo cria uma zona hospedada privada: ``` aws route53 create-hosted-zone --name private.example.com \ --caller-reference 2014-04-01-18:47 \ --hosted-zone-config Comment="command-line version",PrivateZone=true \ --vpc VPCRegion=us-west-2,VPCId=vpc-abcd1234 ``` A saída contém o ID da zona hospedada. Você usa o ID da zona hospedada nas etapas a seguir. ------ ## Etapa 5: criar um registro de DNS do Route 53 Depois de criar a zona hospedada, crie um registro para resolver o nome de domínio personalizado privado. Use o ID da zona hospedada criado na etapa anterior. Neste exemplo, você cria um tipo de registro A. Se estiver usando IPv6 para o endpoint da VPC, crie um tipo de registro AAAA. Se estiver usando pilha dupla para o endpoint da VPC, crie um registro do tipo AAAA e um do tipo A. ------ #### [ Console de gerenciamento da AWS ] Para usar o Console de gerenciamento da AWS, consulte [Routing traffic to an Amazon API Gateway API by using your domain name](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html). Use **Criação rápida** e ative **Alias**. Para o endpoint, use o nome DNS do endpoint da VPC. ------ #### [ AWS CLI ] Para configurar os registros de DNS para associar o nome de domínio personalizado privado ao nome de host do ID de zona hospedada fornecido, crie um arquivo JSON que contenha a configuração de um registro de DNS para o nome de domínio privado. O comando `setup-dns-record.json` a seguir mostra como criar um registro de DNS `A` para associar um nome de domínio personalizado privado ao respectivo nome de host privado. Você fornece o `DNSName` do ID do DNS da VPC e o ID da zona hospedada que você criou na etapa anterior. ``` { "Changes": [ { "Action": "UPSERT", "ResourceRecordSet": { "Name": "private.example.com", "Type": "A", "AliasTarget": { "DNSName": "vpce-abcd1234.execute-api.us-west-2.vpce.amazonaws.com", "HostedZoneId": "Z2OJLYMUO9EFXC", "EvaluateTargetHealth": false } } } ] } ``` O comando [change-resource-record-sets](https://docs.aws.amazon.com/cli/latest/reference/route53/change-resource-record-sets.html) indicado abaixo cria um registro de DNS para o nome de domínio personalizado privado: ``` aws route53 change-resource-record-sets \ --hosted-zone-id ZABCDEFG1234 \ --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. ------ Caso não pretenda invocar seu nome de domínio personalizado privado, depois de confirmar que ele está funcionando, você poderá excluir esses recursos. ## Etapa 6: invocar o nome de domínio personalizado privado Agora você pode invocar o nome de domínio personalizado privado em sua Conta da AWS. Em sua VPC, use o comando curl a seguir para acessar o nome de domínio personalizado privado. ``` curl https://private.example.com/v1 ``` Para ter mais informações sobre outras formas de invocar sua API privada, consulte [Invocar uma API privada usando um nome de domínio personalizado](apigateway-private-api-test-invoke-url.md#apigateway-private-custom-domains-provider-invoke). ## Etapa 7: limpar Para evitar custos desnecessários, exclua a associação entre o endpoint da VPC e o nome de domínio personalizado privado e, em seguida, exclua o nome de domínio personalizado privado. ------ #### [ Console de gerenciamento da AWS ] **Como excluir a associação de acesso ao nome de domínio** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. No painel de navegação principal, escolha **Associações de acesso a nomes de domínio**. 1. Selecione sua associação de acesso ao nome de domínio e escolha **Excluir**. 1. Confirme sua escolha e selecione **Excluir**. Depois de excluir sua associação de acesso ao nome de domínio, você pode excluir o nome de domínio personalizado privado. **Como excluir seu nome de domínio personalizado privado** 1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway). 1. No painel de navegação principal, selecione **Nomes de domínio personalizados**. 1. Escolha seu nome de domínio personalizado privado. 1. Escolha **Excluir**. 1. Confirme sua escolha e selecione **Excluir**. Se necessário, você também pode excluir o endpoint da VPC. Para obter mais informações, consulte [Excluir um endpoint de interface](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html). ------ #### [ AWS CLI ] **Para limpar** 1. O comando `delete-access-association` indicado abaixo exclui a associação de acesso ao nome de domínio: ``` aws apigateway delete-domain-name-access-association \ --domain-name-access-association-arn 'arn:aws:apigateway:us-west-2:111122223333:/domainnameaccessassociations/domainname/private.example.com+abcd1234/vpcesource/vpce-abcd1234efg' \ --region us-west-2 ``` 1. O comando `delete-domain-name` indicado abaixo exclui seu nome de domínio personalizado privado. Esse comando também remove todos os mapeamentos de caminho base. ``` aws apigateway delete-domain-name \ --domain-name test.private.com \ --domain-name-id abcd1234 ``` Se necessário, você também pode excluir o endpoint da VPC. Para obter mais informações, consulte [Excluir um endpoint de interface](https://docs.aws.amazon.com/vpc/latest/privatelink/delete-interface-endpoint.html). ------ ## Práticas recomendadas Sugerimos que você siga as práticas recomendadas indicadas abaixo ao criar um nome de domínio personalizado privado: + Crie um mapeamento de caminho base ou regras de roteamento para enviar tráfego de um nome de domínio personalizado privado a várias APIs privadas. + Quando um endpoint da VPC não precisar mais acessar um nome de domínio personalizado privado, exclua a associação. Além disso, remova o endpoint da VPC da `policy` referente ao serviço `execute-api` do domínio personalizado privado. + Configure pelo menos duas zonas de disponibilidade por endpoint da VPC. + Desabilite o endpoint padrão. Recomendamos desabilitar o endpoint padrão para permitir que os consumidores de API chamem sua API somente pelo nome de domínio personalizado. Para obter mais informações, consulte [Desabilitar o endpoint padrão para APIs REST](rest-api-disable-default-endpoint.md). + Recomendamos que você provisione uma zona hospedada privada do Route 53 e um registro do tipo A ao configurar seu nome de domínio personalizado privado. Se você não pretende invocar seu nome de domínio personalizado privado, poderá excluir esses recursos posteriormente.