# Nome de domínio personalizado para APIs REST públicas no API Gateway
Os *nomes de domínio personalizados* são URLs mais simples e intuitivos que você pode fornecer aos usuários da API.
Após a implantação da sua API, você e seus clientes podem invocar essa API usando o URL de base padrão com o seguinte formato:
```
https://api-id.execute-api.region.amazonaws.com/stage
```
em que *api-id* é gerado pelo API Gateway, *region* é a região da AWS e *stage* é especificado por você ao implantar a API.
A parte do nome de host do URL, `api-id.execute-api.region.amazonaws.com`, refere-se a um endpoint de API. O endpoint de API padrão é gerado aleatoriamente, difícil de lembrar e não é simples de usar.
Com nomes de domínio personalizados, você pode configurar o nome de host da API e escolher um caminho base (por exemplo, `myservice`) para mapear o URL alternativo para sua API. Por exemplo, um URL de base de API mais amigável pode se tornar:
```
https://api.example.com/myservice
```
**nota**
Para ter informações sobre nomes de domínio personalizados para APIs privadas, consulte [Nomes de domínio personalizados para APIs privadas no API Gateway](apigateway-private-custom-domains.md).
## Considerações
As considerações a seguir podem afetar o uso de um nome de domínio personalizado.
+ É possível desabilitar o endpoint padrão para a API. Os clientes ainda podem se conectar ao endpoint padrão, mas receberão um código de status `403 Forbidden`.
+ Um nome de domínio regional personalizado pode ser associado a APIs REST e APIs HTTP. É possível usar as [APIs do API Gateway versão 2](https://docs.aws.amazon.com/apigatewayv2/latest/api-reference/api-reference.html) para criar e gerenciar nomes de domínio regionais personalizados para APIs REST.
+ Um nome de domínio personalizado deve ser exclusivo em uma região em todas as contas da AWS.
+ Você pode migrar o nome de domínio personalizado entre endpoints otimizados para borda e regionais, mas não é possível migrar um domínio personalizado público para um nome de domínio personalizado privado.
+ É necessário criar ou atualizar o registro de recursos do provedor DNS para ser mapeado ao endpoint da API. Sem esse mapeamento, as solicitações de API que forem direcionadas para o nome de domínio personalizado não conseguirão acessar o API Gateway.
+ É possível comportar um número quase infinito de nomes de domínio sem exceder a cota padrão usando um certificado curinga. Para obter mais informações, consulte [Nomes de domínio personalizados curinga](#wildcard-custom-domain-names).
+ É possível escolher uma política de segurança para o nome de domínio personalizado. Para obter mais informações, consulte [Escolher uma política de segurança para o domínio personalizado no API Gateway](apigateway-custom-domain-tls-version.md).
+ Para configurar mapeamentos de API com vários níveis, é necessário usar um nome de domínio regional personalizado e a política de segurança do TLS 1.2.
## Pré-requisitos referentes a nomes de domínio personalizados
Veja a seguir os pré-requisitos para criar um nome de domínio personalizado público ou privado. Para ter informações sobre nomes de domínio personalizados para APIs privadas, consulte [Nomes de domínio personalizados para APIs privadas no API Gateway](apigateway-private-custom-domains.md).
### Registrar um nome de domínio
É necessário ter um nome de domínio da Internet registrado para configurar nomes de domínio personalizados para as APIs. É possível registrar o domínio da internet usando o [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) ou um registrador de domínios de terceiros da sua escolha. O nome de domínio personalizado pode ser o nome de um subdomínio ou do domínio raiz (também conhecido como “ápex da zona”) de um domínio da internet registrado.
O nome de domínio deve seguir a especificação [RFC 1035](https://tools.ietf.org/html/rfc1035#section-2.3.4) e pode ter no máximo 63 octetos por etiqueta e 255 octetos no total.
### Especificar o certificado para o nome de domínio personalizado
Antes de configurar um nome de domínio personalizado para uma API, você deve ter um certificado SSL/TLS pronto no ACM. Se o ACM não estiver disponível na região da AWS onde você está criando o nome de domínio personalizado, será necessário importar um certificado para o API Gateway nessa região.
Para importar um certificado SSL/TLS, você deve fornecer o corpo do certificado SSL/TLS formatado em PEM, sua chave privada e a cadeia de certificado para o nome de domínio personalizado.
Cada certificado armazenado no ACM é identificado por seu ARN. Com certificados emitidos pelo ACM, não é necessário se preocupar em expor detalhes de certificados confidenciais, como a chave privada. Para usar um certificado gerenciado pela AWS para um nome de domínio, basta fazer referência ao seu ARN.
Se o seu aplicativo usa a fixação de certificados, às vezes chamada de fixação SSL, para fixar um certificado do ACM, talvez o aplicativo não consiga se conectar ao seu domínio após a AWS renovar o certificado. Para ter mais informações, consulte [Problemas de fixação do certificado](https://docs.aws.amazon.com/acm/latest/userguide/troubleshooting-pinning.html) no *Guia do usuário do AWS Certificate Manager*.
## Nomes de domínio personalizados curinga
Com nomes de domínio personalizados curinga, você pode suportar um número quase infinito de nomes de domínio sem exceder a [cota padrão](limits.md). Por exemplo, você pode dar a cada um de seus clientes seu próprio nome de domíni, `customername.example.com`.
Para criar um nome de domínio personalizado curinga, especifique um curinga (`*`) como o primeiro subdomínio de um domínio personalizado que representa todos os subdomínios possíveis de um domínio raiz.
Por exemplo, o nome de domínio curinga personalizado `*.example.com` resulta em subdomínios, como `a.example.com`, `b.example.com` e `c.example.com`. Quando você cria o nome de domínio personalizado curinga, todos os subdomínios são roteados pelo modo de roteamento do nome de domínio curinga. Para rotear subdomínios para APIs diferentes, você pode executar uma das seguintes ações:
+ Use regras de roteamento para encaminhar solicitações recebidas em `*.example.com` para diferentes APIs REST de destino usando o cabeçalho `Host`. Para obter mais informações, consulte [Exemplo 4: regras de roteamento para nomes de domínio curinga](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-for-wildcard-domains).
+ Crie um nome de domínio para qualquer subdomínio que você queira rotear para um endpoint diferente. Em uma única conta da AWS, você pode ter `*.example.com` e `a.example.com`.
Você pode usar as variáveis de contexto `$context.domainName` e `$context.domainPrefix` para determinar o nome de domínio que um cliente usou para chamar sua API. Para saber mais sobre variáveis de contexto, consulte [Variáveis para transformações de dados para o API Gateway](api-gateway-mapping-template-reference.md).
Para criar um nome de domínio personalizado curinga, é necessário fornecer um certificado emitido pelo ACM que foi validado usando o DNS ou o método de validação por e-mail.
**nota**
Não é possível criar um nome de domínio personalizado curinga se uma conta da AWS diferente tiver criado um nome de domínio personalizado que esteja em conflito com o nome de domínio personalizado curinga. Por exemplo, se a conta A tiver criado `a.example.com`, a conta B não poderá criar o nome de domínio personalizado curinga `*.example.com`.
Se a conta A e a conta B compartilham um proprietário, entre em contato com a [Central de Suporte da AWS](https://console.aws.amazon.com/support/home#/) para solicitar uma exceção.
## Próximas etapas para nomes de domínio personalizados
Veja as próximas etapas para nomes de domínio personalizados.
**Próximas etapas**
+ Para saber como configurar o certificado SSL/TLS, consulte [Preparar certificados no AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md).
+ Para saber como criar um nome de domínio regional personalizado, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
+ Para saber como criar um nome de domínio personalizado otimizado para borda, consulte [Configurar um nome de domínio personalizado otimizado para borda no API Gateway](how-to-edge-optimized-custom-domain-name.md).
+ Para saber como migrar entre nomes de domínio personalizados regionais e otimizados para borda, consulte [Migrar um nome de domínio personalizado para um tipo de endpoint de API diferente no API Gateway](apigateway-regional-api-custom-domain-migrate.md).
+ Para saber como conectar estágios de API a um nome de domínio personalizado, consulte [Encaminhar o tráfego às APIs por meio do nome de domínio personalizado no API Gateway](rest-api-routing-mode.md).
+ Para saber como escolher uma política de segurança para o nome de domínio personalizado, consulte [Escolher uma política de segurança para o domínio personalizado no API Gateway](apigateway-custom-domain-tls-version.md).
+ Para saber como desativar o endpoint padrão para o nome de domínio personalizado, consulte [Desabilitar o endpoint padrão para APIs REST](rest-api-disable-default-endpoint.md).
+ Para saber como usar as verificações de integridade do Route 53 para controlar o failover de DNS por uma API do API Gateway, consulte [Configurar verificações de integridade personalizadas para failover de DNS para um API Gateway](dns-failover.md).
Se for a primeira vez que você cria um nome de domínio personalizado, recomendamos começar com [Preparar certificados no AWS Certificate Manager](how-to-specify-certificate-for-custom-domain-name.md), para especificar o certificado e, depois, [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md), para criar um nome de domínio regional personalizado.
# Preparar certificados no AWS Certificate Manager
Antes de configurar um nome de domínio personalizado para uma API, você deve ter um certificado SSL/TLS pronto no AWS Certificate Manager. Para obter mais informações, consulte o [Guia do usuário do AWS Certificate Manager](https://docs.aws.amazon.com/acm/latest/userguide/).
## Considerações
Veja a seguir algumas considerações para o certificado SSL/TLS.
+ Se você criar um nome de domínio personalizado otimizado para borda, o API Gateway utilizará o CloudFront no suporte a certificados para nomes de domínio personalizados. Como tal, os requisitos e as restrições de um certificado SSL/TLS de nome de domínio personalizado são determinados pelo [CloudFront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-web-values-specify.html). Por exemplo, o tamanho máximo da chave pública é 2048, e o tamanho da chave privada pode ser de 1024, 2048 e 4096. O tamanho da chave pública é determinado pela autoridade de certificação que você utiliza. Peça à sua autoridade de certificação que retorne chaves de um tamanho diferente do comprimento padrão. Para obter mais informações, consulte [Acesso seguro aos seus objetos](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https.html) e [Criar URLs e cookies assinados](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/private-content-trusted-signers.html).
+ Ao criar um nome de domínio personalizado regional, o tamanho máximo da chave pública deve ser 2048.
+ Para usar um certificado do ACM com um nome de domínio regional personalizado, é necessário solicitar ou importar o certificado na mesma região da API. O certificado deve cobrir o nome de domínio personalizado.
+ Para usar um certificado do ACM com um nome de domínio personalizado otimizado para borda, é necessário solicitar ou importar o certificado na região Leste dos EUA (N. da Virgínia): `us-east-1`.
+ É necessário ter um nome de domínio registrado, como `example.com`. Você pode usar o [Amazon Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/) ou um registrador de domínios credenciado de terceiros. Para obter uma lista de registradores, consulte o [Diretório de registradores acreditados](https://www.icann.org/en/accredited-registrars) no site da ICANN.
## Como criar ou importar um certificado SSL/TLS no ACM
Os procedimentos a seguir mostram como criar ou importar um certificado SSL/TLS para um nome de domínio.
------
#### [ To request a certificate provided by ACM for a domain name ]
1. Faça login no [console do AWS Certificate Manager](https://console.aws.amazon.com/acm).
1. Selecione **Request a certificate**.
1. Em **Tipo de certificado**, escolha **Solicitar um certificado público**.
1. Escolha **Próximo**.
1. Em **Nome de domínio totalmente qualificado**, insira um nome de domínio personalizado para a API, por exemplo `api.example.com`.
1. Opcionalmente, escolha **Add another name to this certificate**.
1. Em **Método de validação**, escolha um método para validar a propriedade do domínio.
1. Em **Algoritmo de chave**, escolha um algoritmo de criptografia.
1. Escolha **Solicitar**.
1. Para uma solicitação válida, um proprietário registrado do domínio da Internet deve concordar com a solicitação antes que o ACM emita o certificado. Se você usa o Route 53 para gerenciar registros de DNS públicos, pode atualizar os registros diretamente do console do ACM.
------
#### [ To import into ACM a certificate for a domain name ]
1. Obtenha um certificado SSL/TLS codificado em PEM para seu nome de domínio personalizado de uma autoridade de certificação (CA). Consulte uma lista parcial dessas CAs em [Mozilla Included CA List](https://ccadb.my.salesforce-sites.com/mozilla/IncludedCACertificateReport).
1. Gere uma chave privada para o certificado e salve a saída em um arquivo usando o toolkit [OpenSSL](https://www.openssl.org) no site da OpenSSL:
```
openssl genrsa -out private-key-file 2048
```
1. Gere uma solicitação de assinatura de certificado (CSR) com a chave privada gerada anteriormente, usando o OpenSSL:
```
openssl req -new -sha256 -key private-key-file -out CSR-file
```
1. Envie a CSR para a autoridade de certificação e salve o certificado resultante.
1. Baixe a cadeia de certificados da autoridade de certificação.
**nota**
Se você obtiver a chave privada de outra maneira e a chave estiver criptografada, poderá usar o seguinte comando para descriptografar a chave antes de enviá-la ao API Gateway para a configuração de um nome de domínio personalizado.
```
openssl pkcs8 -topk8 -inform pem -in MyEncryptedKey.pem -outform pem -nocrypt -out MyDecryptedKey.pem
```
1. Carregue o certificado para o AWS Certificate Manager:
1. Faça login no [console do AWS Certificate Manager](https://console.aws.amazon.com/acm).
1. Selecione **Importar um certificado**.
1. Em **Corpo do certificado**, insira o corpo do certificado de servidor no formato PEM da autoridade de certificação. Veja a seguir um exemplo abreviado desse tipo de certificado.
```
-----BEGIN CERTIFICATE-----
EXAMPLECA+KgAwIBAgIQJ1XxJ8Pl++gOfQtj0IBoqDANBgkqhkiG9w0BAQUFADBB
...
az8Cg1aicxLBQ7EaWIhhgEXAMPLE
-----END CERTIFICATE-----
```
1. Em **Chave privada do certificado**, insira a chave privada do certificado no formato PEM. Veja a seguir um exemplo abreviado desse tipo de chave.
```
-----BEGIN RSA PRIVATE KEY-----
EXAMPLEBAAKCAQEA2Qb3LDHD7StY7Wj6U2/opV6Xu37qUCCkeDWhwpZMYJ9/nETO
...
1qGvJ3u04vdnzaYN5WoyN5LFckrlA71+CszD1CGSqbVDWEXAMPLE
-----END RSA PRIVATE KEY-----
```
1. Em **Cadeia de certificados**, insira os certificados intermediários no formato PEM e, opcionalmente, o certificado raiz, um após o outro, sem linhas em branco. Se você incluir o certificado raiz, sua cadeia de certificados deverá começar com certificados intermediários e terminar com o certificado raiz. Use os certificados intermediários fornecidos pela sua autoridade de certificação. Não inclua intermediários que não estejam no caminho da cadeia de confiança. O seguinte mostra um exemplo abreviado.
```
-----BEGIN CERTIFICATE-----
EXAMPLECA4ugAwIBAgIQWrYdrB5NogYUx1U9Pamy3DANBgkqhkiG9w0BAQUFADCB
...
8/ifBlIK3se2e4/hEfcEejX/arxbx1BJCHBvlEPNnsdw8EXAMPLE
-----END CERTIFICATE-----
```
Aqui está outro exemplo.
```
-----BEGIN CERTIFICATE-----
Intermediate certificate 2
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Intermediate certificate 1
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
Optional: Root certificate
-----END CERTIFICATE-----
```
1. Selecione **Próximo** e, depois, **Próximo**.
------
Depois que o certificado for criado ou importado com êxito, anote o ARN desse certificado. Você precisa dele ao configurar o nome de domínio 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](how-to-specify-certificate-for-custom-domain-name.md).
+ 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html).
+ 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.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha **Create** (Criar).
1. Em **Domain name (Nome de domínio)**, insira um nome de domínio
1. 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](rest-api-routing-mode.md).
1. Em **Versão mínima do TLS**, selecione uma versão.
1. Em **Configuração de endpoint**, em **Tipo de endpoint de API**, selecione **Regional**.
1. Excluir um certificado do ACM O certificado deve estar na mesma região que a API.
1. Escolha **Criar**.
------
#### [ AWS CLI ]
O comando [create-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-domain-name.html) 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](rest-api-routing-rules.md).
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha um nome de domínio personalizado.
1. Na guia **Detalhes do roteamento**, escolha **Adicionar regra de roteamento.**
1. Escolha **Adicionar uma nova condição** para adicionar uma nova condição.
1. 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.
1. Em **Ação**, use o menu suspenso para selecionar a API e o estágio de destino.
1. Escolha **Próximo**.
1. 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.
1. 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](rest-api-routing-mode.md).
## 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.
------
#### [ Console de gerenciamento da AWS ]
Para usar o Console de gerenciamento da AWS, siga a documentação do Route 53 sobre [como configurar o Route 53 para rotear o tráfego para o API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html).
------
#### [ 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](https://docs.aws.amazon.com/general/latest/gr/apigateway.html).
```
{
"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](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 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*).
------
# Configurar um nome de domínio personalizado otimizado para borda no API Gateway
Quando você cria um nome de domínio personalizado para uma API otimizada para borda, o API Gateway configura uma distribuição do CloudFront e um registro DNS para mapear o nome de domínio da API para o nome de domínio da distribuição do CloudFront. Solicitações para a API são roteadas para o API Gateway por meio da distribuição mapeada do CloudFront. Esse mapeamento refere-se a solicitações de API vinculadas ao nome de domínio personalizado a ser roteado para o API Gateway por meio da distribuição mapeada do CloudFront.
## Considerações
Veja algumas considerações sobre o nome de domínio personalizado otimizado para borda:
+ Para configurar um nome de domínio personalizado otimizado para bordas ou atualizar seu certificado, você deve ter uma permissão para atualizar as distribuições do CloudFront.
As seguintes permissões são necessárias para atualizar as distribuições do CloudFront:
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowCloudFrontUpdateDistribution",
"Effect": "Allow",
"Action": [
"cloudfront:updateDistribution"
],
"Resource": [
"*"
]
}
]
}
```
------
+ É necessário solicitar ou importar um certificado para o nome de domínio personalizado otimizado para borda na região Leste dos EUA (N. da Virgínia): `us-east-1`.
+ A distribuição do CloudFront criada pelo API Gateway pertence a uma conta específica da região afiliada ao API Gateway. Ao rastrear operações para criar e atualizar essa distribuição do CloudFront no CloudTrail, você deve usar esse ID de conta do API Gateway. Para obter mais informações, consulte [Registrar a criação do nome de domínio personalizado no CloudTrail em log](#how-to-custom-domain-log-cloudfront-distribution-update-in-cloudtrail).
+ O API Gateway oferece suporte a nomes de domínio personalizados otimizados para bordas, otimizando a Indicação de nome de servidor (SNI) na distribuição do CloudFront. Consulte mais informações sobre como usar nomes de domínio personalizados em uma distribuição do CloudFront, incluindo o formato de certificado necessário e o tamanho máximo de uma chave de certificado, em [Usar nomes de domínio alternativos e HTTPS](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/using-https-alternate-domain-names.html) no *Guia do desenvolvedor do Amazon CloudFront*.
+ Um nome de domínio personalizado otimizado para borda leva cerca de 40 minutos para ficar pronto.
+ Após criar o nome de domínio personalizado otimizado para borda, é necessário criar um registro DNS para mapear o nome de domínio personalizado para o nome da distribuição do CloudFront.
## Criar um nome de domínio personalizado otimizado para borda
O procedimento a seguir descreve como criar um nome de domínio personalizado otimizado para borda para uma API.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha **Adicionar nome do domínio**.
1. Em **Nome de domínio**, insira um nome de domínio
1. Em **Modo de roteamento**, escolha **API\$1MAPPING\$1ONLY**.
1. Em **Tipo de endpoint de API**, escolha **Otimizado para a borda**.
1. Escolha uma versão mínima de TLS.
1. Excluir um certificado do ACM
1. Escolha **Adicionar nome do domínio**.
------
#### [ REST API ]
1. Chame [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html), 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.
1. 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 destino do alias do registro A do domínio personalizado no seu DNS.
Para exemplos de código dessa chamada de API REST, consulte [domainname:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateDomainName.html).
------
Um nome de domínio personalizado otimizado para borda leva cerca de 40 minutos para ficar pronto, mas o console exibe imediatamente o nome de domínio da distribuição do CloudFront associado, no formato `distribution-id.cloudfront.net`, junto com o ARN do certificado. Enquanto isso, você pode criar um mapeamento de caminho base ou uma regra de roteamento e configurar o registro de DNS para associar o nome de domínio personalizado ao nome de domínio da distribuição do CloudFront correspondente.
## Configurar o mapeamento de caminho base de uma API com um nome de domínio personalizado como seu nome de host
Pelo fato de definir o modo de roteamento como `API_MAPPING_ONLY`, você pode usar o mapeamento de caminho base para usar um único nome de domínio personalizado como o nome de host de várias APIs. Isso torna uma API acessível por meio da combinação do nome de domínio personalizado e do caminho base associado.
Por exemplo, se, no API Gateway, você criou uma API chamada `PetStore` e outra API chamada `Dogs` e configurou um nome de domínio personalizado de `api.example.com`, pode definir o URL da API `PetStore` como `https://api.example.com`.
Isso associa a API `PetStore` ao caminho base de uma string vazia. Se você definir o URL da API `PetStore` como `https://api.example.com/PetStore`, isso associará a API `PetStore` ao caminho base de `PetStore`. É possível atribuir um caminho base de `MyDogList` para a API `Dogs`. A URL de `https://api.example.com/MyDogList` é então a URL raiz da API `Dogs`.
Para configurar mapeamentos de API em vários níveis, você só pode usar um nome de domínio regional personalizado. Os nomes de domínio personalizados otimizados para borda não são compatíveis. Para obter mais informações, consulte [Os mapeamentos de API são usados para associar estágios da API a um nome de domínio personalizado para APIs REST.](rest-api-mappings.md).
O procedimento a seguir configura mapeamentos de API para mapear caminhos de seu nome de domínio personalizado para seus estágios de API.
------
#### [ Console de gerenciamento da AWS ]
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom domain names (Nomes de domínio personalizados)** no painel de navegação principal do console do API Gateway.
1. Escolha um nome de domínio personalizado.
1. Escolha **Configure API mappings (Configurar mapeamentos de API)**.
1. Escolha **Add new mapping (Adicionar novo mapeamento)**.
1. Especifique a **API**, o **Stage (Estágio)** e o **Path (Caminho)** (opcional) para o mapeamento.
1. Escolha **Salvar**.
------
#### [ REST API ]
Chame [basepathmapping:create](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html) 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](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateBasePathMapping.html).
------
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).
## Criar um registro DNS para o nome de domínio personalizado otimizado para borda
Depois de iniciar a criação do nome de domínio personalizado otimizado para borda, configure o alias do registro DNS.
Recomendamos que você use o Route 53 para criar um alias de registro A para o nome de domínio personalizado e especifique 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](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html) no *Guia do desenvolvedor do Amazon Route 53*.
Para obter instruções sobre o Amazon Route 53, 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) no *Guia do desenvolvedor do Amazon Route 53*.
## 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. Esses logs estão disponíveis em `us-east-1`. 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 |
## 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 em [Como criar ou importar um certificado SSL/TLS no ACM](how-to-specify-certificate-for-custom-domain-name.md#how-to-specify-certificate-for-custom-domain-name-setup).
O procedimento a seguir descreve como alternar um certificado para um nome de domínio.
**nota**
Leva cerca de 40 minutos para alternar um certificado importado no ACM.
------
#### [ Console de gerenciamento da AWS ]
1. Solicite ou importe um certificado no ACM.
1. Faça login no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom domain names (Nomes de domínio personalizados)** no painel de navegação principal do console do API Gateway.
1. Escolha um nome de domínio personalizado otimizado para borda.
1. Em **Configuração de endpoint**, escolha **Editar**.
1. Em **Certificado do ACM**, selecione um certificado na lista suspensa.
1. Escolha **Salvar alterações** para começar a alternar o certificado para o nome de domínio personalizado.
------
#### [ REST API ]
Chame a ação [domainname:update](https://docs.aws.amazon.com/apigateway/latest/api/API_UpdateDomainName.html), especificando o ARN do novo certificado do ACM para o nome de domínio especificado.
------
#### [ AWS CLI ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) abaixo atualiza o certificado do ACM para um nome de domínio otimizado para borda.
```
aws apigateway update-domain-name \
--domain-name edge.example.com \
--patch-operations "op='replace',path='/certificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) atualiza o certificado do ACM para um nome de domínio regional.
```
aws apigateway update-domain-name \
--domain-name regional.example.com \
--patch-operations "op='replace',path='/regionalCertificateArn',value='arn:aws:acm:us-east-2:111122223333:certificate/CERTEXAMPLE123EXAMPLE'"
```
------
## Chamar a API com nomes de domínio personalizado ao usar um mapeamento de caminho base
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`).
| ID de API | Estágio | URL padrão | Caminho base | URL personalizado |
| --- | --- | --- | --- | --- |
| udxjef | prod | https://udxjef.execute-api.us-east-1.amazonaws.com/prod | /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 |
Para ter maior flexibilidade em relação a como você direciona o tráfego para suas APIs, você pode 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).
O API Gateway oferece suporte a nomes de domínio personalizados para uma API usando a [Indicação de nome de servidor (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication). 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](https://aws.amazon.com/cloudfront/custom-ssl-domains/).
# Migrar um nome de domínio personalizado para um tipo de endpoint de API diferente no API Gateway
Você pode migrar seu nome de domínio personalizado entre endpoints regionais e otimizados para bordas. Não é possível migrar um nome de domínio personalizado público para um nome de domínio personalizado privado. Primeiro adicione o novo tipo de configuração de endpoint à lista `endpointConfiguration.types` existente para o nome de domínio personalizado. Em seguida, configure um registro DNS para apontar o nome de domínio personalizado para o endpoint recém-provisionado. Por fim, você remove o endpoint obsoleto do nome de domínio personalizado.
## Considerações
Veja as considerações sobre como migrar o domínio personalizado entre um endpoint de API regional e um endpoint de API otimizado para borda:
+ Um nome de domínio personalizado otimizado para borda exige um certificado fornecido pelo ACM da região Leste dos EUA (N. da Virgínia): `us-east-1`. Esse certificado é distribuído por todas as localizações geográficas.
+ Um nome de domínio regional personalizado exige um certificado fornecido pelo ACM na mesma região que hospeda a API. Você pode migrar um nome de domínio personalizado otimizado para borda que não esteja na região `us-east-1` para um nome de domínio regional personalizado solicitando um novo certificado do ACM da região da API.
+ Pode levar até 60 segundos para concluir uma migração entre um nome de domínio personalizado otimizado para borda e um nome de domínio regional personalizado. O tempo de migração também depende de quando você atualiza os registros DNS.
+ Você só poderá adicionar uma configuração do endpoint adicional se o modo de acesso ao endpoint estiver definido como `BASIC`. Assim que você tiver duas configurações do endpoint, não poderá mais alterar o modo de acesso ao endpoint. Para obter mais informações, consulte [Modo de acesso ao endpoint](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
+ Se seu nome de domínio personalizado utiliza uma política de segurança que comece com `SecurityPolicy_`, quando você adiciona um novo tipo de configuração do endpoint, o modo de acesso ao endpoint é o mesmo nos dois tipos, e você precisa escolher uma política de segurança que comece com `SecurityPolicy_` para o novo tipo de configuração do endpoint.
## Migrar nomes de domínios personalizados
**nota**
Para concluir a migração, remova o endpoint obsoleto do nome de domínio personalizado.
O procedimento a seguir mostra como migrar um nome de domínio personalizado otimizado para borda para um nome de domínio regional personalizado.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado otimizado para borda.
1. Em **Configuração de endpoint**, escolha **Editar**.
1. Escolha **Adicionar endpoint regional**.
1. Em **Certificado do ACM**, escolha um certificado.
O certificado regional deve estar da mesma região da API regional.
1. Escolha **Salvar alterações**.
1. Configure um registro DNS para apontar o nome de domínio regional personalizado para esse nome de host regional. Consulte mais informações sobre [como configurar o Route 53 para encaminhar o tráfego ao API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html).
1. Depois de confirmar que a configuração de DNS está usando o endpoint correto, você exclui a configuração de endpoint otimizado para borda. Escolha o nome de domínio personalizado e, em **Configuração de endpoint otimizado para borda**, escolha **Excluir**.
1. Confirme sua escolha e exclua o endpoint.
------
#### [ AWS CLI ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) indicado abaixo migra o nome de domínio personalizado otimizado para borda para um nome de domínio personalizado regional:
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
O certificado regional deve ser da mesma região da API regional.
A saída será exibida da seguinte forma:
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
Para o nome de domínio personalizado regional migrado, a propriedade `regionalDomainName` resultante retorna o nome de host da API regional. Você deve configurar um registro DNS para apontar o nome de domínio personalizado regional para esse nome de host regional. Isso permite que o tráfego direcionado para o nome de domínio personalizado seja roteado para o host regional.
Depois que o registro DNS for definido, você poderá remover o nome de domínio personalizado otimizado para borda. O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) indicado abaixo remove o nome de domínio personalizado otimizado para borda.
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
O procedimento a seguir mostra como migrar um nome de domínio personalizado otimizado para borda que use uma política de segurança aprimorada para um nome de domínio regional personalizado que também usa uma política de segurança aprimorada.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado otimizado para borda.
1. Em **Configuração de endpoint**, escolha **Editar**.
1. Escolha **Adicionar endpoint regional**.
1. Em **Certificado do ACM**, escolha um certificado.
O certificado regional deve estar da mesma região da API regional.
1. Em **Política de segurança**, escolha uma política de segurança que comece com `SecurityPolicy_`.
1. Em **Modo de acesso ao endpoint**, escolha **Básico**.
1. Escolha **Salvar alterações**.
1. Configure um registro DNS para apontar o nome de domínio regional personalizado para esse nome de host regional. Consulte mais informações sobre [como configurar o Route 53 para encaminhar o tráfego ao API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html).
1. Depois de confirmar que a configuração de DNS está usando o endpoint correto, você exclui a configuração de endpoint otimizado para borda. Escolha o nome de domínio personalizado e, em **Configuração de endpoint otimizado para borda**, escolha **Excluir**.
1. Confirme sua escolha e exclua o endpoint.
------
#### [ AWS CLI ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) indicado abaixo migra o nome de domínio personalizado otimizado para borda para um nome de domínio personalizado regional:
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "REGIONAL" },
{ "op":"replace", "path": "/securityPolicy", "value":"SecurityPolicy_TLS13_1_3_2025_09"},
{ "op":"add", "path": "/regionalCertificateArn", "value": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149" }
]'
```
O certificado regional deve ser da mesma região da API regional.
A saída será exibida da seguinte forma:
```
{
"certificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "BASIC",
"regionalCertificateArn": "arn:aws:acm:us-west-2:123456789012:certificate/cd833b28-58d2-407e-83e9-dce3fd852149",
"regionalDomainName": "d-fdisjghyn6.execute-api.us-west-2.amazonaws.com"
}
```
Para o nome de domínio personalizado regional migrado, a propriedade `regionalDomainName` resultante retorna o nome de host da API regional. Você deve configurar um registro DNS para apontar o nome de domínio personalizado regional para esse nome de host regional. Isso permite que o tráfego direcionado para o nome de domínio personalizado seja roteado para o host regional.
Depois que o registro DNS for definido, você poderá remover o nome de domínio personalizado otimizado para borda. O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) indicado abaixo remove o nome de domínio personalizado otimizado para borda.
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", "value":"EDGE"},
{"op":"remove", "path":"certificateName"},
{"op":"remove", "path":"certificateArn"}
]'
```
------
O procedimento a seguir mostra como migrar um nome de domínio personalizado regional para um nome de domínio personalizado otimizado para borda.
------
#### [ Console de gerenciamento da AWS ]
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 regional personalizado.
1. Em **Configuração de endpoint**, escolha **Editar**.
1. Escolha **Adicionar endpoint otimizado para borda**.
1. Em **Certificado do ACM**, escolha um certificado.
O certificado de domínio otimizado para bordas deve ser criado na região `us-east-1`.
1. Escolha **Salvar**.
1. Configure um registro DNS para apontar o nome de domínio personalizado otimizado para borda para esse nome de host otimizado para borda. Consulte mais informações sobre [como configurar o Route 53 para encaminhar o tráfego ao API Gateway](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-api-gateway.html).
1. Depois de confirmar que a configuração de DNS está usando o endpoint correto, você exclui a configuração de endpoint regional. Escolha o nome de domínio personalizado e, em **Configuração de endpoint (regional)**, escolha **Excluir**.
1. Confirme sua escolha e exclua o endpoint.
------
#### [ AWS CLI ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) indicado abaixo migra o nome de domínio personalizado regional para um nome de domínio personalizado otimizado para borda:
```
aws apigateway update-domain-name \
--domain-name 'api.example.com' \
--patch-operations '[
{ "op":"add", "path": "/endpointConfiguration/types","value": "EDGE" },
{ "op":"add", "path": "/certificateName", "value": "edge-cert" },
{"op":"add", "path": "/certificateArn", "value": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a"}
]'
```
O certificado de domínio otimizado para bordas deve ser criado na região `us-east-1`.
A saída será exibida da seguinte forma:
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": [
"EDGE",
"REGIONAL"
]
},
"regionalCertificateArn": "arn:aws:acm:us-east-1:123456789012:certificate/3d881b54-851a-478a-a887-f6502760461d",
"regionalDomainName": "d-cgkq2qwgzf.execute-api.us-east-1.amazonaws.com"
}
```
Para o nome de domínio personalizado especificado, o API Gateway retorna o nome de host da API otimizada para bordas como o valor da propriedade `distributionDomainName`. Você deve definir um registro DNS para apontar o nome de domínio personalizado otimizado para fronteiras para esse nome de domínio de distribuição. Isso permite que o tráfego direcionado para o nome de domínio personalizado otimizado para bordas seja roteado para o nome de host da API otimizada para bordas.
Depois que o registro DNS for definido, você poderá remover o tipo de endpoint `REGION` do nome de domínio personalizado. O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) indicado abaixo remove o tipo de endpoint regional:
```
aws apigateway update-domain-name \
--domain-name api.example.com \
--patch-operations '[
{"op":"remove", "path":"/endpointConfiguration/types", value:"REGIONAL"},
{"op":"remove", "path":"regionalCertificateArn"}
]'
```
A saída será exibida como a seguir:
```
{
"certificateArn": "arn:aws:acm:us-east-1:738575810317:certificate/34a95aa1-77fa-427c-aa07-3a88bd9f3c0a",
"certificateName": "edge-cert",
"certificateUploadDate": "2017-10-16T23:22:57Z",
"distributionDomainName": "d1frvgze7vy1bf.cloudfront.net",
"domainName": "api.example.com",
"endpointConfiguration": {
"types": "EDGE"
}
}
```
------
# Encaminhar o tráfego às APIs por meio do nome de domínio personalizado no API Gateway
Ao configurar o modo de roteamento para o nome de domínio personalizado, você define como o tráfego de entrada é direcionado às APIs. Você envia tráfego às APIs usando regras de roteamento, mapeamentos de API ou regras de roteamento e mapeamentos de API. A seção a seguir explica quando usar regras de roteamento, quando usar mapeamentos de API e como definir o modo de roteamento para o nome de domínio personalizado.
## Quando usar regras de roteamento
Ao usar regras de roteamento, você direciona as solicitações recebidas que correspondem a determinadas condições para estágios específicos das APIs REST. Por exemplo, uma regra pode encaminhar uma solicitação ao estágio `production` da API REST `users` se ela contiver o cabeçalho `version:v1` e o caminho base `/users`. Use regras de roteamento para criar topologias avançadas de roteamento dinâmico que atendam a determinados casos de uso, como testes A/B ou aumento do uso de novas versões das APIs.
Recomendamos que, ao direcionar o tráfego para uma API REST, você use regras de roteamento para o nome de domínio personalizado. Você pode recriar qualquer mapeamento de API usando regras de roteamento. Para obter mais informações, consulte [Recriar um mapeamento de API usando regras de roteamento](rest-api-routing-rules-recreate-api-mapping.md).
Para APIs REST, você também pode usar regras de roteamento e mapeamentos de API ao mesmo tempo. Quando você usa regras de roteamento e mapeamentos de API ao mesmo tempo, o API Gateway sempre avalia as regras de roteamento antes de avaliar qualquer mapeamento de API. Use regras de roteamento e mapeamentos de API juntos para migrar seus nomes de domínio personalizados atuais ou para examinar as regras de roteamento.
### Considerações sobre regras de roteamento
As seguintes considerações podem afetar o uso de APIs privadas:
+ As APIs HTTP ou de WebSocket não são permitidas como APIs de destino para regras de roteamento.
+ Se o nome de domínio personalizado tiver mapeamentos de API para APIs REST e HTTP, não será possível usar regras de roteamento.
+ Você pode criar uma regra de roteamento de um domínio personalizado privado para uma API REST privada. Você pode criar uma regra de roteamento para um domínio público personalizado para uma API regional ou otimizada para borda.
+ Não é possível criar uma regra de roteamento de um domínio personalizado privado para uma API REST privada. Não é possível criar uma regra de roteamento de um domínio personalizado privado para uma API REST privada.
## Escolha entre regras de roteamento e mapeamentos de API
Recomendamos que, quando possível, você use regras de roteamento. Use mapeamentos de API somente para enviar tráfego a uma API HTTP ou de WebSocket.
# Definir o modo de roteamento para o nome de domínio personalizado
Você pode escolher qual modo de roteamento o API Gateway deve usar para rotear o tráfego para as APIs. 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). Esta seção aborda modos de roteamento para nomes de domínio personalizados. Você deve definir um modo de roteamento para o nome de domínio personalizado para rotear o tráfego para as APIs. Os seguintes modos de roteamento são permitidos:
+ **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**: use esse modo para enviar tráfego às APIs com regras de roteamento e mapeamentos de API. Nesse modo, todas as regras de roteamento têm prioridade sobre qualquer mapeamento de API. Para obter um exemplo desse modo, consulte [Exemplo 2: regras de roteamento e mapeamentos de API](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings).
+ **ROUTING\$1RULE\$1ONLY**: use esse modo para permitir que somente as regras de roteamento enviem tráfego às APIs. Quando o nome de domínio personalizado usa esse modo, não é possível criar um mapeamento de API, mas você pode usar o comando [get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html) para visualizá-lo. Os autores de chamada de API não podem usar mapeamentos de API para acessar esse nome de domínio.
+ **API\$1MAPPING\$1ONLY**: use esse modo para permitir que somente mapeamentos de API enviem tráfego às APIs. Quando o nome de domínio personalizado usa esse modo, não é possível criar um mapeamento de API, mas você pode usar o comando `list-routing-rules` para visualizá-lo. Os autores de chamada de API não podem usar regras de roteamento para acessar esse nome de domínio.
Esse é o modo de roteamento padrão para todos os nomes de domínio existentes e quaisquer novos nomes de domínio que você criar.
Ao criar um nome de domínio personalizado usando `apigateway`, `API_MAPPING_ONLY` é chamado `BASE_PATH_MAPPING_ONLY` e `ROUTING_RULE_THEN_API_MAPPING` é chamado `ROUTING_RULE_THEN_BASE_PATH_MAPPING`. Esse comportamento ocorre somente na AWS CLI, no CloudFormation ou em qualquer SDK, não no Console de gerenciamento da AWS.
O procedimento a seguir mostra como alterar o modo de roteamento para um nome de domínio personalizado existente. Ao alterar o modo de roteamento do nome de domínio personalizado, os autores de chamada de API não podem acessar seu nome de domínio usando nenhum modo de roteamento incompatível.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado.
1. Em **Detalhes do domínio**, escolha **Editar**.
1. Em **Modo de roteamento**, escolha **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**.
1. Escolha **Salvar**.
Se você alterar o modo de roteamento para `ROUTING_RULE_ONLY` ou `API_MAPPING_ONLY`, todos os mapeamentos de API ou regras de roteamento que você criou serão removidos da página de detalhes do nome de domínio do console. Se você alterar o modo de roteamento para permitir o uso de regras de roteamento ou mapeamentos de API, esses recursos retornarão.
------
#### [ AWS CLI - apigatewayv2 ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) indicado abaixo atualiza um nome de domínio para usar o modo de roteamento `ROUTING_RULE_THEN_API_MAPPING`:
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
A saída será exibida da seguinte forma:
```
{
"ApiMappingSelectionExpression": "$request.basepath",
"DomainName": "api.example.com",
"DomainNameArn": "arn:aws:apigateway:us-west-2::/domainnames/api.example.com",
"DomainNameConfigurations": [
{
"ApiGatewayDomainName": "d-abcdefg.execute-api.us-west-2.amazonaws.com",
"CertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/abcdefg-123456-abcdefg",
"DomainNameStatus": "AVAILABLE",
"EndpointType": "REGIONAL",
"HostedZoneId": "Z2OJLYMUO9EFXC",
"SecurityPolicy": "TLS_1_2"
}
],
"RoutingMode": "ROUTING_RULE_THEN_API_MAPPING",
"Tags": {}
}
```
------
#### [ AWS CLI - apigateway ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) indicado abaixo atualiza um nome de domínio personalizado privado para usar o modo de roteamento `ROUTING_RULE_THEN_BASE_PATH_MAPPING`:
```
aws apigateway update-domain-name \
--domain-name 'private.example.com' \
--patch-operations "op='replace',path='/routingMode',value='ROUTING_RULE_THEN_BASE_PATH_MAPPING'"
```
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"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"policy": "...",
"routingMode" : "ROUTING_RULE_THEN_BASE_PATH_MAPPING"
}
```
------
# Regras de roteamento para associar estágios da API a um nome de domínio personalizado para APIs REST
Uma regra de roteamento é um conjunto de condições que, quando correspondidas, invocam uma ação. Por exemplo, uma regra pode rotear qualquer solicitação recebida em um nome de domínio personalizado que contenha o cabeçalho `Hello:World` e o caminho base `users` para o estágio `production` de uma API REST.
As regras são avaliadas em ordem de prioridade e, se você definir o modo de roteamento com o `ROUTING_RULE_THEN_API_MAPPING`, o API Gateway sempre avaliará todas as regras de roteamento antes de avaliar qualquer mapeamento de API. A lista a seguir descreve como uma regra de roteamento usa condições, ações e prioridades.
**Condições**
Quando as condições de uma regra forem atendidas, a ação será executada. O API Gateway permite até duas condições de cabeçalho e uma condição de caminho. O API Gateway avalia as condições do cabeçalho e as condições do caminho base ao mesmo tempo.
Você pode criar uma regra sem nenhuma condição. Quando o API Gateway avalia essa regra, a ação sempre é executada. Você pode criar uma regra sem nenhuma condição como uma regra abrangente.
Para ter mais informações sobre condições de cabeçalho, consulte [Correspondência com condições de cabeçalho](#rest-api-routing-rules-condition-headers). Para ter mais informações sobre as condições de caminho, consulte [Correspondência com condições de caminho](#rest-api-routing-rules-condition-path).
**Ações**
As ações resultam da correspondência entre condições e uma regra de roteamento. No momento, a única ação possível é invocar um estágio de uma API REST.
Cada regra pode ter uma ação.
**Prioridade**
A prioridade determina em qual ordem as regras são avaliadas, do valor mais baixo para o valor mais alto. As regras não podem ter a mesma prioridade.
Você pode definir a prioridade de 1 a 1.000.000. Se a prioridade de uma regra for 1, o API Gateway a avaliará primeiro. Recomendamos que, ao criar uma regra, você adicione intervalos nas prioridades. Isso ajuda você a mudar a prioridade das regras e adicionar novas regras. Para obter mais informações, consulte [Alterar a prioridade de uma regra de roteamento](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority).
Para ver exemplos de como o API Gateway avalia as regras de roteamento, consulte [Exemplos de como o API Gateway avalia regras de roteamento](rest-api-routing-rules-examples.md).
## Tipos de condição da regra de roteamento do API Gateway
A seção a seguir descreve os tipos de condição de regra de roteamento. O API Gateway só encontrará correspondência com uma regra se todas as condições forem verdadeiras.
### Correspondência com condições de cabeçalho
Ao criar uma condição de cabeçalho, você pode fazer a correspondência entre o nome do cabeçalho e o valor glob do cabeçalho, como `Hello:World`. O API Gateway usa uma correspondência literal para validar a correspondência com condições de cabeçalho. Sua condição pode utilizar até dois cabeçalhos usando `AND` entre eles. Por exemplo, pode haver correspondência com sua condição se uma solicitação recebida contiver `Hello:World` e `x-version:beta`.
A correspondência do nome do cabeçalho não diferencia maiúsculas de minúsculas, mas o valor glob do cabeçalho diferencia maiúsculas de minúsculas. `Hello:World` corresponderá a `hello:World`, mas não a `Hello:world`.
Para obter uma lista de valores de cabeçalho restritos, consulte [Restrições](#rest-api-routing-rules-restrictions).
#### Uso de curingas com condições de cabeçalho
Você só pode usar curingas no valor glob do cabeçalho, e eles devem ser `*prefix-match`, `suffix-match*` ou `*contains*`. A tabela a seguir mostra exemplos de como usar curingas para fazer a correspondência com as condições do cabeçalho.
| Condições de cabeçalho | Solicitações que correspondem à regra de roteamento | Solicitações que não correspondem à regra de roteamento |
| --- | --- | --- |
| `x-version: a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` e `x-version: *b*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: b*` e `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) | Nenhum |
Se você criar condições para vários valores de cabeçalho, como `Accept:application/json,text/xml`, é recomendável usar `*contains*` para as condições de cabeçalho e evitar criar condições usando o caractere vírgula (`,`).
Como o API Gateway faz a correspondência com as condições de cabeçalho de maneira literal, as correspondências semânticas podem ser roteadas de forma diferente. A tabela a seguir mostra a diferença nos resultados das regras de roteamento.
| Condições de cabeçalho | Solicitações que correspondem à regra de roteamento | Solicitações que não correspondem à regra de roteamento |
| --- | --- | --- |
| `Accept: *json` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `Accept: *json*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/rest-api-routing-rules.html) | Nenhum |
### Correspondência com condições de caminho
Quando você cria uma condição de caminho base, se a solicitação de entrada contiver o caminho especificado, haverá correspondência com a regra. A correspondência diferencia maiúsculas de minúsculas, portanto, o caminho `New/Users` não corresponderá a `new/users`.
Você pode criar uma condição de caminho base somente para um caminho base.
Para obter uma lista de condições restritas de caminho base, consulte [Restrições](#rest-api-routing-rules-restrictions).
#### Remoção do caminho base com as condições do caminho base
Ao criar uma condição de caminho base, você pode optar por remover o caminho base. Ao remover o caminho base, o API Gateway remove o caminho base correspondente de entrada ao invocar a API de destino. Esse comportamento é igual ao de quando você usa um mapeamento de API. Quando você não remove o caminho base, o API Gateway encaminha o caminho base completo para a API de destino. Recomendamos que você remova o caminho base somente ao recriar um mapeamento de API.
A tabela a seguir mostra exemplos de como o API Gateway avalia a condição de remoção do caminho base.
| Condição | Remover o caminho base | Solicitação de entrada | Resultado |
| --- | --- | --- | --- |
| Se o caminho base contiver `PetStoreShopper/dogs` | Verdadeiro | `GET https://example.com/PetStoreShopper/dogs` | O API Gateway chamará o método `GET` do recurso `/`. |
| Se o caminho base contiver `PetStoreShopper/dogs` | Falso | `GET https://example.com/PetStoreShopper/dogs` | O API Gateway chamará o método `GET` do recurso `PetStoreShopper/dogs`. |
| Se o caminho base contiver `PetStoreShopper` | Verdadeiro | `GET https://example.com/PetStoreShopper/dogs` | O API Gateway chamará o método `GET` do recurso `dogs`. |
| Se o caminho base contiver `PetStoreShopper` | Falso | `GET https://example.com/PetStoreShopper/dogs` | O API Gateway chamará o método `GET` do recurso `PetStoreShopper/dogs`. |
| Se o caminho base contiver `PetStoreShopper` | Verdadeiro | `GET https://example.com/PetStoreShopper?birds=available` | O API Gateway chamará o método `GET` do recurso `/` com o parâmetro de string de consulta `birds=available`. |
| Se o caminho base contiver `PetStoreShopper` | Falso | `GET https://example.com/PetStoreShopper?birds=available` | O API Gateway chamará o `GET` método do `/PetStoreShopper` recurso com o parâmetro de string de consulta `birds=available`. |
## Restrições
+ A API de destino e o nome de domínio personalizado devem estar na mesma conta da AWS.
+ Cada regra pode ter uma API de destino.
+ Você só pode criar uma regra de roteamento entre um nome de domínio personalizado privado e uma API privada e entre um nome de domínio personalizado público e uma API pública. Não é permitido misturar recursos públicos e privados.
+ Se o nome de domínio personalizado tiver mapeamentos de API para APIs REST e HTTP, não será possível usar regras de roteamento.
+ O número máximo de prioridade é 1.000.000.
+ Restrições de cabeçalho:
+ Cada condição `anyOf` só pode conter um valor de cabeçalho.
+ Os únicos caracteres permitidos para nomes de cabeçalho e valores glob de cabeçalho são especificados pela [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230), que são `a-z`, `A-Z` e `0-9`, e estes caracteres especiais: `*?-!#$%&'.^_`|~`.
+ Você só pode usar um curinga no valor glob do cabeçalho, mas ele deve ser `*prefix-match`, `suffix-match*` ou `*contains*`. Não é possível usar `*` no meio de um valor glob de cabeçalho.
+ Nomes de cabeçalho curinga não são permitidos.
+ O nome do cabeçalho deve ter menos de 40 caracteres.
+ O valor glob do cabeçalho deve ter menos de 128 caracteres.
+ O valor glob do cabeçalho para uma correspondência infixa deve ter menos de 40 caracteres.
+ Os seguintes cabeçalhos não são permitidos como condições:
+ `access-control-*`
+ `apigw-*`
+ `Authorization`
+ `Connection`
+ `Content-Encoding`
+ `Content-Length`
+ `Content-Location`
+ `Forwarded`
+ `Keep-Alive`
+ `Origin`
+ `Proxy-Authenticate`
+ `Proxy-Authorization`
+ `TE`
+ `Trailers`
+ `Transfer-Encoding`
+ `Upgrade`
+ `x-amz-*`
+ `x-amzn-*`
+ `x-apigw-api-id`
+ `X-Forwarded-For`
+ `X-Forwarded-Host`
+ `X-Forwarded-Proto`
+ `x-restAPI`
+ `Via`
+ Restrições do caminho base:
+ O caminho base deve ter menos de 128 caracteres.
+ O caminho base deve conter apenas letras, números e os seguintes caracteres: `$-_.+!*'()/`.
Esses caracteres não são compatíveis com expressões regulares (regex).
+ O caminho base não pode começar ou terminar com o caractere de barra invertida (`\`).
# Exemplos de como o API Gateway avalia regras de roteamento
A seção a seguir mostra quatro exemplos de como o API Gateway avalia regras de roteamento e mapeamentos de API.
## Exemplo 1: somente regras de roteamento
Neste exemplo, o nome de domínio personalizado `https://petstore.example.com` tem o modo de roteamento definido como `ROUTING_RULE_ONLY` e as regras e prioridades de roteamento a seguir.
| ID da regra | Prioridade | Condições | Ação |
| --- | --- | --- | --- |
| `abc123` | 10 | Se a solicitação contiver cabeçalho: `Hello:World` | API de destino 1 |
| `zzz000` | 50 | Se a solicitação contiver cabeçalhos `Accept:image/webp` e `Pet:Dog-*` e se o caminho base contiver `PetStoreShopper` | API de destino 2 |
| `efg456` | 100 | Nenhum | API de destino 3 |
A tabela a seguir mostra como o API Gateway aplica as regras de roteamento anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://petstore.example.com -h "Hello:World"` | API de destino 1 | As solicitações correspondem à regra de roteamento `abc123`. |
| `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | API de destino 1 | O API Gateway avalia todas as regras de roteamento em ordem de prioridade. A regra de roteamento `abc123` é a primeira em prioridade e as condições correspondem, então o API Gateway invoca a API de destino 1. Embora as condições da solicitação também correspondam à regra de roteamento `zzz000`, o API Gateway não avalia nenhuma outra regra de roteamento depois que encontra uma correspondência. |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | API de destino 2 | As solicitações correspondem à regra de roteamento `zzz000`. Houve correspondência porque `Pet:Dog-Bella` era uma string compatível com `Pet:Dog-*`. |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | API de destino 3 | A solicitação não corresponde à regra de roteamento `abc123`. A solicitação não corresponde à regra de roteamento `zzz000` porque todos os cabeçalhos necessários não estão presentes. A próxima regra prioritária corresponde a todas as solicitações recebidas, então o API Gateway invoca a API de destino 3. |
## Exemplo 2: regras de roteamento e mapeamentos de API
Neste exemplo, o nome de domínio personalizado `https://petstore.diagram.example.com` tem o modo de roteamento definido como `ROUTING_RULE_THEN_API_MAPPING` e as regras de roteamento e mapeamentos de API a seguir.
| ID da regra | Prioridade | Condições | Ação |
| --- | --- | --- | --- |
| `abc123` | 1 | Se a solicitação contiver `pets` | Invoque o estágio `Prod` da API `PetStore`. |
| `000zzz` | 5 | Se a solicitação contiver cabeçalhos `Cookie` e `*ux=beta*` e se o caminho base contiver `/refunds` | Invoque o estágio `Beta` da API `Refunds`. |
A tabela a seguir mostra mapeamentos de API para `https://petstore.backup.example.com`.
| Mapeamento de API | API selecionada |
| --- | --- |
| `/refunds` | Invoque o estágio `Prod` da API `Refunds`. |
| `(none)` | Invoque o estágio `Prod` da API `Search`. |
O diagrama a seguir mostra como o API Gateway aplica as regras de roteamento e os mapeamentos de API anteriores a solicitações de exemplo. As solicitações de exemplo estão resumidas na tabela após esse diagrama.
![\[Diagrama de como o API Gateway aplica as regras de roteamento e os mapeamentos de API anteriores.\]](http://docs.aws.amazon.com/pt_br/apigateway/latest/developerguide/images/rr-diagram.png)
A tabela a seguir mostra como o API Gateway aplica as regras de roteamento e os mapeamentos de API anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://petstore.diagram.com/pets` | O estágio `Prod` da API `PetStore`. | A solicitação corresponde à regra de roteamento `abc123`. |
| `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | O estágio `Beta` da API `Refunds`. | A solicitação corresponde à regra de roteamento `000zzz`. O cabeçalho `Cookie` contém a correspondência `*contains*` correta e a correspondência do caminho base para essa condição. |
| `https://petstore.diagram.example.com/refunds` | O estágio `Prod` da API `Refunds`. | A solicitação não tem os cabeçalhos necessários para fazer a correspondência com a regra de roteamento `zzz000`. Se o API Gateway não conseguir fazer a correspondência com uma regra de roteamento, ele retornará aos mapeamentos de API. O API Gateway pode associar o caminho base ao estágio `Prod` da API `Refunds`. |
| `https://petstore.diagram.example.com/` | O estágio `Prod` da API `Search`. | A solicitação faz a correspondência entre o mapeamento de API e o caminho vazio `(none)`. |
## Exemplo 3: regras de roteamento e mapeamentos de API com vários níveis
Neste exemplo, o nome de domínio personalizado `https://petstore.backup.example.com` tem o modo de roteamento definido como `ROUTING_RULE_THEN_API_MAPPING` e as regras de roteamento e mapeamentos de API a seguir.
A tabela a seguir mostra regras de roteamento para `https://petstore.backup.example.com`.
| ID da regra | Prioridade | Condições | Ação |
| --- | --- | --- | --- |
| `abc123` | 10 | Se a solicitação contiver cabeçalho: `Hello:World` | API de destino 1 |
| `000zzz` | 50 | Se a solicitação contiver cabeçalhos `Accept`:`image/webp` e `Pet:Dog-*` e se o caminho base contiver `PetStoreShopper` | API de destino 2 |
A tabela a seguir mostra mapeamentos de API para `https://petstore.backup.example.com`.
| Mapeamento de API | API selecionada |
| --- | --- |
| `PetStoreShopper` | API de destino 3 |
| `PetStoreShopper/cats` | API de destino 4 |
A tabela a seguir mostra como o API Gateway aplica as regras de roteamento e os mapeamentos de API anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | API de destino 3 | A solicitação não tem os cabeçalhos necessários para fazer a correspondência com a regra de roteamento `zzz000`. Se o API Gateway não conseguir fazer a correspondência com uma regra de roteamento, ele retornará aos mapeamentos de API. O API Gateway pode associar o caminho base à API de destino 3. |
| `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | API de destino 1 | A solicitação corresponde à regra de roteamento `abc123`. Se o modo de roteamento estiver definido como `ROUTING_RULE_THEN_API_MAPPING`, as regras de roteamento sempre terão prioridade sobre os mapeamentos de API. |
| `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | Nenhum | A solicitação não corresponde a nenhuma regra de roteamento ou mapeamento de API. Como não há uma regra de roteamento padrão, o API Gateway rejeita a chamada e envia um código de status `403 Forbidden` ao autor da chamada. |
## Exemplo 4: regras de roteamento para nomes de domínio curinga
Neste exemplo, o nome de domínio personalizado `https://*.example.com` é um nome de domínio curinga. O curinga aceita todos os subdomínios que são roteados de volta para o mesmo domínio. Os exemplos de regra de roteamento a seguir alteram esse comportamento para permitir que subdomínios sejam roteados para diferentes APIs de destino usando o cabeçalho `Host`.
A tabela a seguir mostra regras de roteamento para `https://*.example.com`.
| ID da regra | Prioridade | Condições | Ação |
| --- | --- | --- | --- |
| `abc123` | 10 | Se a solicitação contiver cabeçalho: `Host:a.example.com` | API de destino 1 |
| `000zzz` | 50 | Se a solicitação contiver cabeçalho: `Host:b.example.com` | API de destino 2 |
| `efg456` | 500 | Nenhum | API de destino 3 |
A tabela a seguir mostra como o API Gateway aplica as regras de roteamento anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://a.example.com` | API de destino 1 | O cabeçalho `Host` é `a.example.com`. Essa solicitação corresponde à regra de roteamento `abc123`. |
| `https://b.example.com` | API de destino 2 | O cabeçalho `Host` é `b.example.com`. Essa solicitação corresponde à regra de roteamento `000zzz`. |
| `https://testing.example.com` | API de destino 3 | Isso corresponde à regra de roteamento abrangente `efg456`. |
# Quando usar regras de roteamento
Você pode criar uma regra de roteamento usando o Console de gerenciamento da AWS, a AWS CLI ou qualquer SDK da AWS. Depois que você criar um trabalho, não poderá mais alterar ou atualizar a respectiva prioridade.
## Criar uma regra de roteamento
O procedimento a seguir mostra como criar uma regra de roteamento para um nome de domínio personalizado com um modo de roteamento definido como `ROUTING_RULE_THEN_API_MAPPING` ou `ROUTING_RULE_ONLY`.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado.
1. Na guia **Detalhes do roteamento**, escolha **Adicionar regra de roteamento.**
1. Escolha **Adicionar uma nova condição** para adicionar uma nova condição.
Você pode adicionar uma condição de cabeçalho ou de caminho base. Para fazer a correspondência de todas as solicitações recebidas com seu nome de domínio personalizado, não adicione uma condição.
1. Em **Ação**, use o menu suspenso para selecionar a API e o estágio de destino.
1. Escolha **Próximo**.
1. No campo de prioridade, insira um número para sua prioridade.
O API Gateway avalia as regras em ordem de prioridade, do valor mais baixo para o valor mais alto.
Se você estiver criando uma regra sem uma condição, recomendamos usar uma prioridade com um valor alto.
1. Selecione **Criar regra de roteamento**.
------
#### [ AWS CLI ]
O comando [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) indicado abaixo cria uma regra de roteamento com prioridade 50. Neste exemplo, o API Gateway roteia todas as solicitações recebidas que tenham os cabeçalhos `Hello:World` e `x-version:beta` e o caminho base `PetStoreShopper` para a API de destino `a1b2c3`.
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
A saída será exibida da seguinte forma:
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 50,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
## Alterar a prioridade de uma regra de roteamento
Você pode alterar a prioridade de uma regra de roteamento. Essa alteração entra em vigor imediatamente e pode afetar a forma como os consumidores da API invocam seus nomes de domínio personalizados. Recomendamos que, ao definir a prioridade de suas regras de roteamento, você deixe intervalos entre as regras.
Por exemplo, considere duas regras de roteamento, regra `abc123` com prioridade 50 e regra `zzz000` com prioridade 150. Para alterar a prioridade das regras de modo que o API Gateway avalie a regra `zzz000` primeiro, você pode alterar a prioridade da regra `zzz000` para 30.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado.
1. Na guia **Detalhes do roteamento**, escolha sua regra de roteamento e selecione **Editar**.
1. Escolha **Próximo**.
1. Em prioridade, insira a nova prioridade.
1. Escolha **Salvar alterações**.
------
#### [ AWS CLI ]
O comando [put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html) indicado abaixo altera a prioridade de uma regra de roteamento `abc123`.
```
aws apigatewayv2 put-routing-rule \
--domain-name 'api.example.com' \
--priority 30 \
--routing-rule-id abc123 \
--conditions '[
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
]'\
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod"
}
}
]'
```
A saída será exibida da seguinte forma:
```
{
"Actions": [
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": false
}
}
],
"Conditions": [
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "Hello",
"ValueGlob": "World"
}
]
}
},
{
"MatchHeaders": {
"AnyOf": [
{
"Header": "x-version",
"ValueGlob": "beta"
}
]
}
},
{
"MatchBasePaths": {
"AnyOf": [
"PetStoreShopper"
]
}
}
],
"Priority": 38,
"RoutingRuleArn": "arn:aws:apigateway:us-west-2:111122223333:/domainnames/api.example.com/routingrules/abc123",
"RoutingRuleId": "abc123"
}
```
------
# Recriar um mapeamento de API usando regras de roteamento
Você pode recriar um mapeamento de API usando regras de roteamento. Para recriar um mapeamento de API, ative a remoção do caminho base. Isso preserva o comportamento dos mapeamentos de API. Para obter mais informações, consulte [Remoção do caminho base com as condições do caminho base](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split).
O tutorial a seguir mostra como recriar o mapeamento de API `https:// api.example.com/orders/v2/items/categories/5` como uma regra de roteamento e como atualizar os logs de acesso para registrar em log o ID da regra de roteamento que o API Gateway usa para enviar tráfego à sua API.
------
#### [ Console de gerenciamento da AWS ]
**Como definir o modo de roteamento como ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha seu nome de domínio personalizado.
1. Em **Detalhes do domínio**, escolha **Editar**.
1. Em **Modo de roteamento**, escolha **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**.
1. Escolha **Salvar**
Depois de definir o modo de roteamento, crie a regra de roteamento.
**Como criar a regra de roteamento**
1. Na guia **Detalhes do roteamento**, escolha **Adicionar regra de roteamento.**
1. Escolha **Adicionar condição** e selecione **Caminho**.
1. Em **Caminho**, insira **orders/v2/items/categories/5**.
1. Em **Remover caminho base**, escolha **Ativo**.
1. Em **API de destino**, escolha sua API de destino.
1. Em **Estágio de destino**, escolha seu estágio de destino.
1. Escolha **Próximo**.
1. Em prioridade, insira a prioridade.
Mesmo que você mantiver o mapeamento de API existente, o API Gateway sempre usará a nova regra de roteamento, pois as regras de roteamento sempre têm prioridade sobre os mapeamentos de API.
1. Escolha **Salvar alterações**.
Depois de criar a regra de roteamento, atualize o formato do log de acesso do estágio ou crie um log para confirmar se o API Gateway usa sua regra de roteamento para enviar tráfego à sua API.
**Como atualizar logs de acesso**
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Selecione a API.
1. No painel de navegação principal, selecione **Estágios**.
1. Em **Logs e rastreamento**, escolha **Editar**.
Se você não tiver um grupo de logs, consulte [Configurar o registro em log do CloudWatch para APIs REST no API Gateway](set-up-logging.md).
1. Adicione **\$1context.customDomain.routingRuleIdMatched** ao formato do log.
Esse grupo de logs registra o ID da regra de roteamento que o API Gateway usou para enviar tráfego à sua API. Para obter mais informações, consulte [Não sei como o API Gateway enviou tráfego às minhas APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
1. Escolha **Salvar**.
Depois de atualizar os logs de acesso, invoque seu nome de domínio personalizado. Veja a seguir um exemplo de comando curl para invocar o nome de domínio personalizado `https://api.example.com` com o caminho base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5"
```
Depois de invocar com sucesso seu nome de domínio personalizado, confirme se o CloudWatch Logs mostra `routingRuleIdMatched`. Para saber como usar o console do CloudWatch Logs para visualizar um grupo de logs, consulte [Exibir eventos de log do API Gateway no console do CloudWatch](view-cloudwatch-log-events-in-cloudwatch-console.md).
------
#### [ AWS CLI ]
1. Use o comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) indicado abaixo para atualizar o nome de domínio `api.example.com` e usar modo de roteamento `ROUTING_RULE_THEN_API_MAPPING`.
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode ROUTING_RULE_THEN_API_MAPPING
```
1. Use o comando [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) indicado abaixo para criar uma regra de roteamento e recriar o mapeamento de API `https://api.example.com/orders/v2/items/categories/5`.
```
aws apigatewayv2 create-routing-rule \
--domain-name 'api.example.com' \
--priority 50 \
--conditions '[
{
"MatchBasePaths": {
"AnyOf": [
"orders/v2/items/categories/5"
]
}
}
]' \
--actions '[
{
"InvokeApi": {
"ApiId": "a1b2c3",
"Stage": "prod",
"StripBasePath": true
}
}
]'
```
1. Use o comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) indicado abaixo para atualizar o formato dos logs de acesso e incluir a variável `$context.customDomain.routingRuleIdMatched`. Essa variável registra o ID da regra de roteamento que o API Gateway usou para enviar tráfego à sua API. Você usa esse log para confirmar se o API Gateway usa sua regra de roteamento para enviar tráfego à sua API. Para obter mais informações, consulte [Não sei como o API Gateway enviou tráfego às minhas APIs](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
```
aws apigateway update-stage \
--rest-api-id a1bc2c3 \
--stage-name prod \
--patch-operations "op=replace,path=/accessLogSettings/format,value='\$context.path \$context.customDomain.routingRuleIdMatched \$context.requestId \$context.extendedRequestId'"
```
Se você não tiver um grupo de logs, consulte [Configurar o registro em log do CloudWatch para APIs REST no API Gateway](set-up-logging.md).
1. Use o exemplo de comando curl indicado abaixo para invocar o nome de domínio personalizado com o caminho base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5
```
1. Use o comando [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html) indicado abaixo para obter os eventos de logs do grupo de logs `access-log-group-orders` que contêm o ID da regra de roteamento `abc123`.
```
aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123
```
Isso confirma que o API Gateway usou a regra de roteamento para enviar tráfego à sua API.
------
# Solucionar problemas em regras de roteamento
As diretrizes de solução de problemas a seguir podem ajudar a resolver problemas em suas regras de roteamento.
## Não sei como o API Gateway enviou tráfego às minhas APIs
Você pode usar logs de acesso para o estágio da API REST a fim de registrar em log e solucionar problemas em suas regras de roteamento. Você pode visualizar o ID da regra de roteamento que o API Gateway usou para enviar tráfego à sua API usando a variável `$context.customDomain.routingRuleIdMatched`. Para visualizar o mapeamento de API que o API Gateway usou para enviar tráfego à sua API, use a variável `$context.customDomain.basePathMatched`.
Para registrar suas regras de roteamento em log, você precisa configurar [um ARN de função do CloudWatch Logs apropriado](set-up-logging.md#set-up-access-logging-permissions) para sua conta e criar um grupo de logs.
O exemplo de grupo de logs de acesso a seguir pode recuperar as informações relevantes para solucionar problemas em regras de roteamento e mapeamentos de API. O API Gateway preenche somente a variável de contexto do mecanismo de roteamento que ele usa; do contrário, a variável de contexto é `-`.
------
#### [ CLF ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.requestId $context.extendedRequestId
```
------
#### [ JSON ]
```
{"requestPath": "$context.path", "routingRuleId" : "$context.customDomain.routingRuleIdMatched", "API mapping" : "$context.customDomain.basePathMatched", "requestId":"$context.requestId", "extendedRequestId":"$context.extendedRequestId"}
```
------
#### [ XML ]
```
$context.path $context.customDomain.routingRuleIdMatched $context.customDomain.basePathMatched $context.extendedRequestId
```
------
#### [ CSV ]
```
$context.path,$context.customDomain.routingRuleIdMatched,$context.customDomain.basePathMatched,$context.requestId,$context.extendedRequestId
```
------
Também recomendamos que você confirme o modo de roteamento do nome de domínio personalizado. Para obter mais informações, consulte [Definir o modo de roteamento para o nome de domínio personalizado](set-routing-mode.md).
## Não consigo habilitar as regras de roteamento no meu nome de domínio personalizado
Você pode receber o seguinte erro do API Gateway:
```
Your account doesn’t have permission to use RoutingRules.
This might be caused by an IAM policy in your account with a deny statement on BasePathMapping or ApiMapping.
To grant permission for this account to use RoutingRules, use the UpdateAccount API.
This will impact any existing IAM policies that deny access to BasePathMapping or ApiMapping.
See API Gateway documentation for further details.
```
Você receberá esse erro se tiver ou tenha tido uma política do IAM que nega acesso ao [BasePathMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies) ou ao [ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies). Ao habilitar as regras de roteamento para um nome de domínio personalizado, embora sua política continue negando acesso a `BasePathMapping` ou a `ApiMapping`, a mesma política pode ser usada para acessar a `RoutingRule`. Isso pode permitir que um usuário altere o comportamento de roteamento do seu nome de domínio personalizado.
Por exemplo, se você teve uma política como a seguinte:
```
{
"Sid": "DenyCreatingApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
}
```
Ao habilitar as regras de roteamento para `example.com`, essa política continuará negando o acesso à criação de um `ApiMapping`, mas não negará o acesso à criação de uma `RoutingRule`.
Recomendamos que você audite as políticas do IAM em sua conta. O seguinte exemplo de política negará acesso à criação de `ApiMapping`, `BasePathMapping`e `RoutingRule`:
```
{
"Sid": "DenyCreatingBasePathMappingsApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/basepathmappings",
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
},
{
"Sid": "DenyCreatingRoutingRules",
"Effect": "Deny",
"Action": "apigateway:CreateRoutingRule",
"Resource": [
"arn:aws:apigateway:us-west-2:111122223333:/domainnames/example.com/routingrules/*"
]
}
```
Depois de confirmar que todas as políticas foram atualizadas, você pode atualizar as configurações da API no nível da conta para habilitar as regras de roteamento para uma região.
Use o comando [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) indicado abaixo para atualizar as configurações em nível de conta da API para uma região:
```
aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2
```
Depois de atualizar as configurações em nível de conta da API, você pode alterar o modo de roteamento do nome de domínio personalizado. Você também pode continuar usando as políticas do IAM para negar acesso a `RoutingRules`, `ApiMapping` ou `BasePathMapping`.
# Os mapeamentos de API são usados para associar estágios da API a um nome de domínio personalizado para APIs REST.
Você usa mapeamentos de API para conectar estágios de API a um nome de domínio personalizado. Isso encaminha o tráfego às suas APIs por meio do nome de domínio personalizado.
Um mapeamento de API especifica uma API, um estágio e, opcionalmente, um caminho a usar para o mapeamento. Por exemplo, você pode associar `https://api.example.com/orders` ao estágio `production` de uma API.
Você pode mapear os estágios da API HTTP e REST para o mesmo nome de domínio personalizado.
Antes de criar um mapeamento de API, você deve ter uma API, um estágio e um nome de domínio personalizado. Para saber mais sobre como criar um nome de domínio personalizado, consulte [Configurar um nome de domínio regional personalizado no API Gateway](apigateway-regional-api-custom-domain-create.md).
## Solicitações recebidas em seu nome de domínio personalizado
Quando você associa um nome de domínio personalizado a um estágio da API, o API Gateway remove o caminho base de entrada. Isso remove o caminho base mapeado da invocação para a API. Por exemplo, se o caminho base `https://api.example.com/orders/shop/5` fosse associado ao estágio `test` e você usasse a solicitação `https://api.example.com/orders/shop/5/hats`, o API Gateway invocaria o recurso `/hats` do estágio `test` da API, não o recurso `orders/shop/5/hats`.
## Mapear solicitações de API
Veja a seguir como o API Gateway explica os mapeamentos de API.
Você pode criar um mapeamento de API usando mapeamentos de nível único, como um mapeamento de API de `orders` para o estágio `beta` de uma API e um mapeamento de API de `shipping` para o estágio `alpha` de uma API. No caso de nomes de domínio regionais personalizados com a política de segurança do TLS 1.2, o API Gateway aceita mapeamentos de API de vários níveis. Você pode criar um mapeamento de API de `orders/v1/items` para o estágio `alpha` de uma API e de `orders/v2/items` para o estágio `beta` de uma API. Para mapeamentos de API com vários níveis, o API Gateway encaminha as solicitações ao mapeamento de API que tem o prefixo correspondente mais longo.
Você pode criar um mapeamento de API para o caminho vazio `(none)`. Se nenhum caminho corresponder à solicitação, o API Gateway enviará a solicitação à API que você associou ao caminho vazio `(none)`.
Neste exemplo, o nome de domínio personalizado `https://api.example.com` tem os seguintes mapeamentos de API:
| Mapeamento de API | API selecionada |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
A tabela a seguir mostra como o API Gateway aplica os mapeamentos de API anteriores a solicitações de exemplo.
| Solicitação | API selecionada | Explicação |
| --- | --- | --- |
| `https://api.example.com/orders` | API 2 | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v1/items` | API 3 | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v2/items` | API 4 | A solicitação apresenta correspondência exata a esse mapeamento de API. |
| `https://api.example.com/orders/v1/items/123` | API 3 | O API Gateway escolhe o mapeamento com o caminho correspondente mais longo. O `123` no final da solicitação não afeta a seleção. Consulte [Solicitações recebidas em seu nome de domínio personalizado](#rest-api-mappings-incoming-requests). |
| `https://api.example.com/orders/v2/items/categories/5` | API 5 | O API Gateway escolhe o mapeamento com o caminho correspondente mais longo. |
| `https://api.example.com/customers` | API 1 | O API Gateway usa o mapeamento vazio como um catch-all. |
| `https://api.example.com/ordersandmore` | API 2 | O API Gateway escolhe o mapeamento com o prefixo correspondente mais longo. Para um nome de domínio personalizado configurado com mapeamentos de nível único, como somente `https://api.example.com/orders` e `https://api.example.com/`, o API Gateway escolheria `API 1`, pois não há um caminho correspondente com `ordersandmore`. |
## Restrições
+ Em um mapeamento de API, o nome de domínio personalizado e as APIs mapeadas devem estar na mesma conta da AWS.
+ Os mapeamentos de API devem conter apenas letras, números e os caracteres a seguir: `$-_.+!*'()/`.
+ O comprimento máximo para o caminho em um mapeamento de API é de 300 caracteres.
+ É possível ter 200 mapeamentos de API com vários níveis para cada nome de domínio. Esse limite não inclui mapeamento de API com um único nível, como `/prod`.
+ Você só pode mapear APIs HTTP para um nome de domínio personalizado regional com a política de segurança TLS 1.2.
+ Você não pode mapear APIs WebSocket para o mesmo nome de domínio personalizado que uma API HTTP ou API REST.
+ Depois de criar os mapeamentos de API, você deve criar ou atualizar o registro de recursos do provedor de DNS para ser associado ao endpoint da API.
+ Se você criar mapeamentos de API com vários níveis, o API Gateway mudará todos os nomes de cabeçalho para minúsculas.
## Crie um mapeamento de API
Para criar um mapeamento de API, você deve primeiro criar um nome de domínio personalizado, uma API e um estágio. O nome de domínio personalizado deve ter um modo de roteamento definido como `ROUTING_RULE_THEN_API_MAPPING` ou `API_MAPPING_ONLY`. Para ter informações sobre como configurar o modo de roteamento, consulte [Definir o modo de roteamento para o nome de domínio personalizado](set-routing-mode.md).
Para obter exemplos de modelos do AWS Serverless Application Model que criam todos os recursos, consulte [Sessões com SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) no GitHub.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha **Custom Domain Names (Nomes de domínios personalizados)** no painel de navegação principal.
1. Escolha um nome de domínio personalizado.
1. Na guia **Detalhes do roteamento**, escolha **Configurar mapeamentos de API**.
1. Especifique a **API**, o **Estágio** e o **Caminho** do mapeamento.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) a seguir cria um mapeamento de API. Neste exemplo, o API Gateway envia solicitações para `api.example.com/v1/orders` para a API e o estágio especificados.
**nota**
Para criar mapeamentos de API com vários níveis, você deve usar `apigatewayv2`.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
O exemplo de CloudFormation a seguir cria um mapeamento de API.
**nota**
Para criar mapeamentos de API com vários níveis, você deve usar `AWS::ApiGatewayV2`.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------
# Tipos de endereço IP para nomes de domínio personalizados no API Gateway
Ao criar um nome de domínio personalizado, você especifica o tipo de endereços IP que podem invocar seu domínio. É possível escolher IPv4 para resolver endereços IPv4 e invocar seu domínio ou escolher pilha dupla para permitir que endereços IPv4 e IPv6 invoquem seu domínio. Recomendamos que você defina o tipo de endereço IP como pilha dupla para aliviar o esgotamento do espaço IP ou para seu procedimento de segurança. Para ter mais informações sobre os benefícios de um tipo de endereço IP de pilha dupla, consulte [IPv6 na AWS](https://docs.aws.amazon.com/whitepapers/latest/ipv6-on-aws/internet-protocol-version-6.html).
É possível alterar o tipo de endereço IP atualizando a configuração do endpoint do nome de domínio.
## Considerações sobre tipos de endereço IP
As considerações a seguir podem afetar o uso de tipos de endereço IP.
+ O tipo de endereço IP padrão para nomes de domínio personalizados do API Gateway para APIs públicas é IPv4.
+ Os nomes de domínio personalizados privados só podem ter um tipo de endereço IP de pilha dupla.
+ Seu nome de domínio personalizado não precisa ter o mesmo tipo de endereço IP para todas as APIs associadas a ele. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar seu domínio.
## Alterar o tipo de endereço IP de um nome de domínio personalizado
É possível alterar o tipo de endereço IP atualizando a configuração do endpoint do nome de domínio. É possível atualizar a configuração do endpoint usando o Console de gerenciamento da AWS, a AWS CLI, o CloudFormation ou um SDK da AWS.
------
#### [ Console de gerenciamento da AWS ]
**Como alterar o tipo de endereço IP de 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. Escolha um nome de domínio personalizado público.
1. Escolha **Configurações de endpoint**.
1. Em Tipo de endereço IP, escolha **IPv4** ou **Pilha dupla**.
1. Escolha **Salvar**.
------
#### [ AWS CLI ]
O comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) a seguir atualiza uma API para ter um tipo de endereço IP de pilha dupla:
```
aws apigateway update-domain-name \
--domain-name dualstack.example.com \
--patch-operations "op='replace',path='/endpointConfiguration/ipAddressType',value='dualstack'"
```
A saída será exibida da seguinte forma:
```
{
"domainName": "dualstack.example.com",
"certificateUploadDate": "2025-02-04T14:46:10-08:00",
"regionalDomainName": "d-abcd1234.execute-api.us-east-1.amazonaws.com",
"regionalHostedZoneId": "Z3LQWSYCGH4ADY",
"regionalCertificateArn": "arn:aws:acm:us-east-1:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"endpointConfiguration": {
"types": [
"REGIONAL"
],
"ipAddressType": "dualstack"
},
"domainNameStatus": "AVAILABLE",
"securityPolicy": "TLS_1_2",
"tags": {}
}
```
------
# Escolher uma política de segurança para o domínio personalizado no API Gateway
Uma *política de segurança* é uma combinação predefinida da versão mínima do TLS e dos pacotes de criptografia oferecida pelo Amazon API Gateway. Quando seus clientes estabelecem um handshake do TLS para a API ou o nome do domínio personalizado, a política de segurança aplica a versão do TLS e o pacote de criptografia aceitos pelo API Gateway. As políticas de segurança protegem suas APIs e nomes de domínio personalizados contra problemas de segurança de rede, como violação e espionagem entre um cliente e o servidor.
O API Gateway aceita políticas de segurança legadas e políticas de segurança aprimoradas. `TLS_1_0` e `TLS_1_2` são políticas de segurança legadas. Use essas políticas de segurança para workloads generalizadas ou para começar a criar uma API. Qualquer política que comece com `SecurityPolicy_` é uma política de segurança aprimorada. Use essas políticas para workloads reguladas, governança avançada ou para usar criptografia pós-quântica. Ao usar uma política de segurança aprimorada, você também deve definir o modo de acesso ao endpoint para governança adicional. Para obter mais informações, consulte [Modo de acesso ao endpoint](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
## Considerações
Veja a seguir algumas considerações sobre políticas de segurança para nomes de domínio personalizados para APIs REST no API Gateway:
+ Você não pode habilitar o TLS mútuo em um nome de domínio que utilize uma política de segurança aprimorada.
+ Não é possível associar uma API HTTP a um nome de domínio que use uma política de segurança aprimorada.
+ Se você habilitar o mapeamento de caminho de base de vários níveis a uma API REST que utilize uma política de segurança aprimorada, não poderá criar um mapeamento de caminho de base para uma API HTTP com o mesmo nome de domínio.
+ Sua API pode ser associada a um nome de domínio personalizado com uma política de segurança diferente da política da sua API. Quando você invoca esse nome de domínio personalizado, o API Gateway utiliza a política de segurança da API para negociar o handshake TLS. Se você desabilitar seu endpoint de API padrão, isso poderá afetar como os chamadores podem invocar sua API.
+ O API Gateway aceita políticas de segurança em todas as APIs. No entanto, você só pode escolher uma política de segurança para as APIs REST. O API Gateway comporta apenas a política de segurança `TLS_1_2` para APIs HTTP ou de WebSocket.
+ O API Gateway não comporta a atualização de uma política de segurança para um nome de domínio com vários tipos de endpoint. Caso você tenha vários tipos de endpoint para um nome de domínio, exclua um deles para atualizar a política de segurança.
## Como o API Gateway aplica políticas de segurança
O exemplo a seguir mostra como o API Gateway aplica políticas de segurança utilizando a política `SecurityPolicy_TLS13_1_3_2025_09` como exemplo.
A política de segurança `SecurityPolicy_TLS13_1_3_2025_09` aceita tráfego TLS 1.3 e rejeita tráfego TLS 1.2 e TLS 1.0. Para o tráfego TLS 1.3, a política de segurança aceita os seguintes pacotes de criptografia:
+ `TLS_AES_128_GCM_SHA256`
+ `TLS_AES_256_GCM_SHA384`
+ `TLS_CHACHA20_POLY1305_SHA256`
O API Gateway não aceita nenhum outro pacote de criptografia. Por exemplo, a política de segurança rejeitaria qualquer tráfego TLS 1.3 que utilize o pacote de criptografia `AES128-SHA`.
Para monitorar quais protocolos TLS e criptografias os clientes usaram para acessar seu API Gateway, você pode usar as variáveis de contexto `$context.tlsVersion` e `$context.cipherSuite` em seus logs de acesso. Para obter mais informações, consulte [Monitorar APIs REST no API Gateway](rest-api-monitor.md).
Para ver as políticas de segurança padrão para todas as APIs REST e nomes de domínio personalizados, consulte [Políticas de segurança padrão](apigateway-security-policies-list.md#apigateway-security-policies-default). Para ver as políticas de segurança aceitas para todas as APIs REST e nomes de domínio personalizados, consulte [Políticas de segurança aceitas](apigateway-security-policies-list.md).
## Alterar a política de segurança do seu nome de domínio personalizado
Se você alterar sua política de segurança, a atualização levará cerca de 15 minutos para ser concluída. É possível monitorar o `lastUpdateStatus` de seu nome de domínio personalizado. No decorrer da atualização do seu nome de domínio personalizado, o `lastUpdateStatus` será `PENDING` e, quando for concluído, será `AVAILABLE`.
Quando você usa uma política de segurança que comece com `SecurityPolicy_`, também deve ativar o modo de acesso ao endpoint. Para obter mais informações, consulte [Modo de acesso ao endpoint](apigateway-security-policies.md#apigateway-security-policies-endpoint-access-mode).
------
#### [ Console de gerenciamento da AWS ]
**Como alterar a política de segurança de 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. Escolha um nome de domínio personalizado que envie tráfego para as APIs REST.
Verifique se há apenas um tipo de endpoint associado ao seu nome de domínio personalizado.
1. Escolha **Configurações de nome de domínio personalizado** e, depois, selecione **Editar**.
1. Em **Política de segurança**, selecione uma nova política.
1. Em **Modo de acesso ao endpoint**, escolha **Restrito**.
1. Escolha **Salvar alterações**.
------
#### [ AWS CLI ]
O seguinte comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) atualiza um nome de domínio para utilizar a política de segurança `SecurityPolicy_TLS13_1_3_2025_09`:
```
aws apigateway update-domain-name \
--domain-name example.com \
--patch-operations '[
{
"op": "replace",
"path": "/securityPolicy",
"value": "SecurityPolicy_TLS13_1_3_2025_09"
},
{
"op": "replace",
"path": "/endpointAccessMode",
"value": "STRICT"
}
]'
```
A saída será exibida da seguinte forma:
```
{
"domainName": "example.com",
"endpointConfiguration": {
"types": [ "REGIONAL" ],
"ipAddressType": "dualstack"
},
"regionalCertificateArn": "arn:aws:acm:us-west-2:111122223333:certificate/a1b2c3d4-5678-90ab-cdef",
"securityPolicy": "SecurityPolicy_TLS13_1_3_2025_09",
"endpointAccessMode": "STRICT"
}
```
------
## Informações sobre APIs HTTP e APIs de WebSocket
Para saber mais sobre APIs HTTP e APIs de WebSocket, consulte [Política de segurança para APIs HTTP no API Gateway](http-api-ciphers.md) e [Política de segurança para APIs de WebSocket no API Gateway](websocket-api-ciphers.md).
# Desabilitar o endpoint padrão para APIs REST
Por padrão, os clientes podem invocar sua API usando o endpoint `execute-api` gerado pelo API Gateway para sua API. Para garantir que os clientes possam acessar sua API somente usando um nome de domínio personalizado, desabilite o endpoint `execute-api` padrão. Os clientes ainda podem se conectar ao endpoint padrão, mas receberão um código de status `403 Forbidden`. A desabilitação do endpoint padrão afeta todos os estágios da API. Essa configuração entra em vigor quando você atualiza qualquer configuração em qualquer estágio, como atualizar a implantação no estágio.
O procedimento a seguir mostra como desabilitar o endpoint padrão de uma API REST.
------
#### [ Console de gerenciamento da AWS ]
1. Inicie uma sessão no console do API Gateway em [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Escolha uma API REST.
1. No painel de navegação principal, selecione **Configurações da API**.
1. Escolha uma API.
1. Em **Detalhes da API**, escolha **Editar**.
1. Em **Endpoint padrão**, selecione **Inativo**.
1. Escolha **Salvar alterações**.
1. No painel de navegação principal, selecione **Recursos**.
1. Escolha **Implantar API**.
1. Reimplante sua API em um estágio ou atualize qualquer configuração em um estágio para que a atualização entre em vigor.
------
#### [ AWS CLI ]
O comando [update-rest-api](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-rest-api.html) indicado abaixo desabilita o endpoint padrão:
```
aws apigateway update-rest-api \
--rest-api-id abcdef123 \
--patch-operations op=replace,path=/disableExecuteApiEndpoint,value='True'
```
Depois de desabilitar o endpoint padrão, é necessário implantar sua API para que a alteração entre em vigor.
O comando [create-deployment](https://docs.aws.amazon.com/cli/latest/reference/apigateway/create-deployment.html) indicado abaixo cria uma implantação e a associa a um estágio:
```
aws apigateway create-deployment \
--rest-api-id abcdef123 \
--stage-name dev
```
------
# Configurar verificações de integridade personalizadas para failover de DNS para um API Gateway
É possível usar as verificações de integridade do Amazon Route 53 para controlar o failover de DNS de uma API do API Gateway em uma Região da AWS primária para outra em uma região secundária. Isso pode ajudar a mitigar os impactos no caso de um problema regional. Se você usa um domínio personalizado, pode realizar o failover sem exigir que os clientes alterem os endpoints da API.
Quando você escolhe [Evaluate Target Health](https://docs.aws.amazon.com/Route53/latest/APIReference/API_AliasTarget.html#Route53-Type-AliasTarget-EvaluateTargetHealth>Evaluate Target Health) (Avaliar integridade do destino) para um registro de alias, esses registros falham somente quando o serviço API Gateway não está disponível na região. Em alguns casos, suas próprias APIs do API Gateway podem sofrer interrupções antes desse período. Para controlar o failover de DNS diretamente, configure verificações de integridade personalizadas do Route 53 para as APIs do API Gateway. Neste exemplo, você usa um alarme do CloudWatch que ajuda os operadores a controlar o failover de DNS. Para ver mais exemplos e outras considerações ao configurar o failover, consulte [Criar mecanismos de recuperação de desastres usando o Route 53](https://aws.amazon.com/blogs/networking-and-content-delivery/creating-disaster-recovery-mechanisms-using-amazon-route-53/) e [Realizar verificações de integridade do Route 53 em recursos privados em uma VPC com o AWS Lambda e o CloudWatch](https://aws.amazon.com/blogs/networking-and-content-delivery/performing-route-53-health-checks-on-private-resources-in-a-vpc-with-aws-lambda-and-amazon-cloudwatch/).
**Topics**
+ [Pré-requisitos](#dns-failover-prereqs)
+ [Etapa 1: configurar recursos](#dns-failover-intial-setup)
+ [Etapa 2: iniciar o failover para a região secundária](#dns-failover-initiate)
+ [Etapa 3: testar o failover](#dns-failover-test)
+ [Etapa 4: retornar à região primária](#dns-failover-return)
+ [Próximas etapas: personalizar e testar regularmente](#dns-failover-next-steps)
## Pré-requisitos
Para concluir esse procedimento, você deve criar e configurar os seguintes recursos:
+ Um nome de domínio de sua propriedade.
+ Um certificado do ACM para esse nome de domínio em duas Regiões da AWS. Para obter mais informações, consulte [Pré-requisitos referentes a nomes de domínio personalizados](how-to-custom-domains.md#how-to-custom-domains-prerequisites).
+ Uma zona hospedada no Route 53 para seu nome de domínio. Para obter mais informações, consulte [Trabalhar com zonas hospedadas](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html) no Guia do desenvolvedor do Amazon Route 53.
Para receber mais informações sobre como criar registros DNS de failover do Route 53 para os nomes de domínio, consulte [Escolher uma política de roteamento](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-policy.html) no Guia do desenvolvedor do Amazon Route 53. Para receber mais informações sobre como monitorar um alarme do CloudWatch, consulte [Monitorar um alarme do CloudWatch](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/health-checks-creating-values.html#health-checks-creating-values-cloudwatch) no Guia do desenvolvedor do Amazon Route 53.
## Etapa 1: configurar recursos
Neste exemplo, você cria os seguintes recursos para configurar o failover de DNS para seu nome de domínio:
+ APIs do API Gateway em duas Regiões da AWS
+ Nomes de domínio personalizados do API Gateway com o mesmo nome em duas Regiões da AWS
+ Mapeamentos de API do API Gateway que conectam as APIs do API Gateway aos nomes de domínio personalizados
+ Registros de failover de DNS do Route 53 para os nomes de domínio
+ Um alarme do CloudWatch na região secundária
+ Uma verificação de integridade do Route 53 com base no alarme do CloudWatch na região secundária
Primeiro, certifique-se de que você tenha todos os recursos necessários nas regiões primária e secundária. A região secundária deve conter o alarme e a verificação de integridade. Dessa maneira, você não depende da região primária para realizar o failover. Por exemplo, modelos do CloudFormation que criam esses recursos, consulte [samples/primary.zip](samples/primary.zip) e [samples/secondary.zip](samples/secondary.zip).
**Importante**
Antes do failover para a região secundária, certifique-se de que todos os recursos necessários estejam disponíveis. Caso contrário, a API não estará pronta para o tráfego na região secundária.
## Etapa 2: iniciar o failover para a região secundária
No exemplo a seguir, a região em espera recebe uma métrica do CloudWatch e inicia o failover. Usamos uma métrica personalizada que exige a intervenção do operador para iniciar o failover.
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 1 \
--region us-west-1
```
Substitua os dados de métrica pelos dados correspondentes para o alarme do CloudWatch que você configurou.
## Etapa 3: testar o failover
Invoque a API e verifique se você recebeu uma resposta da região secundária. Se você usou os modelos de exemplo na etapa 1, a resposta muda de `{"message": "Hello from the primary Region!"}` para `{"message": "Hello from the secondary Region!"}` após o failover.
```
curl https://my-api.example.com
{"message": "Hello from the secondary Region!"}
```
## Etapa 4: retornar à região primária
Para retornar à região primária, envie uma métrica do CloudWatch que resulte em aprovação na verificação de integridade.
```
aws cloudwatch put-metric-data \
--metric-name Failover \
--namespace HealthCheck \
--unit Count \
--value 0 \
--region us-west-1
```
Substitua os dados de métrica pelos dados correspondentes para o alarme do CloudWatch que você configurou.
Invoque a API e verifique se você recebeu uma resposta da região primária. Se você usou os modelos de exemplo na etapa 1, a resposta muda de `{"message": "Hello from the secondary Region!"}` para `{"message": "Hello from the primary Region!"}`.
```
curl https://my-api.example.com
{"message": "Hello from the primary Region!"}
```
## Próximas etapas: personalizar e testar regularmente
Este exemplo demonstra uma maneira de configurar o failover de DNS. É possível usar uma variedade de métricas do CloudWatch ou endpoints HTTP para as verificações de integridade que gerenciam o failover. Teste regularmente os mecanismos de failover para garantir que eles funcionem conforme o esperado e que os operadores estejam familiarizados com seus procedimentos de failover.