# 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 **Avançar**. 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`.