# Envío de tráfico a las API a través del nombre de dominio personalizado en API Gateway
Cuando configura el modo de enrutamiento para el nombre de dominio personalizado, establece cómo se dirige el tráfico entrante a las API. Puede enviar tráfico a las API mediante reglas de enrutamiento, asignaciones de API o reglas de enrutamiento y asignaciones de API. En la siguiente sección se explica cuándo utilizar reglas de enrutamiento, cuándo utilizar asignaciones de API y cómo establecer el modo de enrutamiento para el nombre de dominio personalizado.
## Cuándo utilizar reglas de enrutamiento
Cuando utiliza reglas de enrutamiento, dirige las solicitudes entrantes que coinciden con determinadas condiciones a etapas específicas de las API de REST. Por ejemplo, una regla puede enrutar una solicitud a la etapa `production` de la API de REST `users` si contiene el encabezado `version:v1` y la ruta base `/users`. Utilice reglas de enrutamiento para crear topologías avanzadas de enrutamiento dinámico que admitan casos de uso como las pruebas A/B o el aumento del uso de nuevas versiones de las API.
Le recomendamos que, cuando dirija el tráfico a una API de REST, utilice reglas de enrutamiento para el nombre de dominio personalizado. Puede recrear cualquier asignación de API mediante reglas de enrutamiento. Para obtener más información, consulte [Nueva creación de una asignación de API mediante reglas de enrutamiento](rest-api-routing-rules-recreate-api-mapping.md).
En el caso de las API de REST, también puede utilizar conjuntamente reglas de enrutamiento y asignaciones de API. Cuando utiliza reglas de enrutamiento y asignaciones de API de forma conjunta, API Gateway siempre evalúa las reglas de enrutamiento antes de evaluar cualquier asignación de API. Utilice las reglas de enrutamiento y las asignaciones de API conjuntamente para migrar los nombres de dominio personalizados actuales o para explorar las reglas de enrutamiento.
### Consideraciones sobre las reglas de enrutamiento
Las siguientes consideraciones pueden afectar la utilización de las reglas de enrutamiento:
+ Las API de WebSocket o HTTP no son compatibles como API de destino para las reglas de enrutamiento.
+ Si el nombre de dominio personalizado tiene asignaciones de API tanto a las API de REST como de HTTP, no se admiten las reglas de enrutamiento.
+ Puede crear una regla de enrutamiento para un dominio personalizado privado a una API de REST privada. Puede crear una regla de enrutamiento para un dominio personalizado público a una API regional u optimizada para la periferia.
+ No puede crear una regla de enrutamiento para un dominio personalizado público a una API privada. No puede crear una regla de enrutamiento para un dominio personalizado privado a una API pública.
## Elección entre reglas de enrutamiento y asignaciones de API
Le recomendamos que, siempre que sea posible, utilice reglas de enrutamiento. Solo utilice asignaciones de API para enviar tráfico a una API de HTTP o WebSocket.
# Establecimiento del modo de enrutamiento para el nombre de dominio personalizado
Puede elegir qué modo de enrutamiento utiliza API Gateway para enrutar el tráfico a las API. Para obtener más información, consulte [Envío de tráfico a las API a través del nombre de dominio personalizado en API Gateway](rest-api-routing-mode.md). En esta sección se explican los modos de enrutamiento para nombres de dominio personalizados. Debe establecer un modo de enrutamiento para el nombre de dominio personalizado a fin de enrutar el tráfico a las API. Se admiten los siguientes modos de enrutamiento:
+ **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**: utilice este modo para enviar tráfico a las API tanto con reglas de enrutamiento como con asignaciones de API. En este modo, todas las reglas de enrutamiento tienen prioridad sobre cualquier asignación de API. Para ver un ejemplo de este modo, consulte [Ejemplo 2: reglas de enrutamiento y asignaciones de API](rest-api-routing-rules-examples.md#rest-api-routing-rules-examples-rule-and-mappings).
+ **ROUTING\$1RULE\$1ONLY**: utilice este modo para permitir solo que las reglas de enrutamiento envíen tráfico a las API. Cuando el dominio personalizado utiliza este modo, no puede crear una asignación de API, pero puede utilizar el comando [get-api-mappings](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/get-api-mappings.html) para verlas. Los intermediarios que llaman a la API no pueden utilizar asignaciones de API para acceder a este nombre de dominio.
+ **API\$1MAPPING\$1ONLY**: utilice este modo para permitir solo que las asignaciones de API envíen tráfico a las API. Cuando el nombre de dominio personalizado utiliza este modo, no puede crear una regla de enrutamiento, pero puede utilizar el comando `list-routing-rules` para verlas. Los intermediarios que llaman a la API no pueden utilizar reglas de enrutamiento para acceder a este nombre de dominio.
Este es el modo de enrutamiento predeterminado para todos los nombres de dominio existentes y para cualquier nombre de dominio nuevo que cree.
Cuando crea un nombre de dominio personalizado mediante `apigateway`, `API_MAPPING_ONLY` se llama `BASE_PATH_MAPPING_ONLY` y `ROUTING_RULE_THEN_API_MAPPING` se llama `ROUTING_RULE_THEN_BASE_PATH_MAPPING`. Este comportamiento solo está presente para la AWS CLI, CloudFormation o cualquier SDK, no en la Consola de administración de AWS.
El procedimiento siguiente muestra cómo cambiar el modo de enrutamiento de un nombre de dominio personalizado existente. Cuando cambie el modo de enrutamiento del nombre de dominio personalizado, los intermediarios que llamen a la API no podrán acceder al nombre de dominio con ningún modo de enrutamiento no admitido.
------
#### [ Consola de administración de AWS ]
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija **Custom domain names (Nombres de dominios personalizados)** en el panel de navegación principal.
1. Elija un nombre de dominio personalizado.
1. En **Detalles del dominio**, elija **Editar**.
1. En **Modo de enrutamiento**, elija **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**.
1. Seleccione **Save**.
Si cambia el modo de enrutamiento a `ROUTING_RULE_ONLY` o `API_MAPPING_ONLY`, cualquier asignación de API o regla de enrutamiento que haya creado se eliminará de la página de detalles del nombre de dominio de la consola. Si cambia el modo de enrutamiento para que admita reglas de enrutamiento o asignaciones de API, estos recursos volverán a aparecer.
------
#### [ AWS CLI - apigatewayv2 ]
El siguiente comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) actualiza un nombre de dominio para utilizar el modo de enrutamiento `ROUTING_RULE_THEN_API_MAPPING`:
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode "ROUTING_RULE_THEN_API_MAPPING"
```
El resultado será similar al siguiente:
```
{
"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 ]
El siguiente comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-domain-name.html) actualiza un nombre de dominio personalizado privado para utilizar el modo de enrutamiento `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'"
```
El resultado será similar al siguiente:
```
{
"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"
}
```
------
# Reglas de enrutamiento para conectar las etapas de API a un nombre de dominio personalizado para las API de REST
Una regla de enrutamiento es un conjunto de condiciones que, cuando coinciden, invocan una acción. Por ejemplo, una regla puede enrutar cualquier solicitud entrante a un nombre de dominio personalizado que contenga el encabezado `Hello:World` y contenga la ruta base `users` a la etapa `production` de una API de REST.
Las reglas se evalúan por orden de prioridad, y si establece el modo de enrutamiento en `ROUTING_RULE_THEN_API_MAPPING`, API Gateway siempre evalúa todas las reglas de enrutamiento antes de evaluar cualquier asignación de API. En la siguiente lista se describe cómo una regla de enrutamiento utiliza condiciones, acciones y prioridades.
**Condiciones**
Cuando se cumplen las condiciones de una regla, se llevan a cabo sus acciones. API Gateway admite hasta dos condiciones de encabezado y una condición de ruta. API Gateway evalúa conjuntamente las condiciones de encabezado y las condiciones de ruta base.
Puede crear una regla sin condiciones. Cuando API Gateway evalúa esta regla, siempre se realiza la acción. Puede crear una regla sin ninguna condición como regla catch-all.
Para obtener más información sobre las condiciones de encabezado, consulte [Condiciones de encabezado de coincidencia](#rest-api-routing-rules-condition-headers). Para obtener más información sobre las condiciones de ruta, consulte [Coincidencia de condiciones de ruta base](#rest-api-routing-rules-condition-path).
**Acciones**
Las acciones son el resultado de la coincidencia de condiciones con una regla de enrutamiento. Actualmente, la única acción admitida es invocar una etapa de una API de REST.
Cada regla puede tener una acción.
**Prioridad**
La prioridad determina en qué orden se evalúan las reglas, del valor más bajo al más alto. Las reglas no pueden tener la misma prioridad.
Puede establecer la prioridad entre 1 y 1 000 000. Si una regla tiene una prioridad de uno, API Gateway la evalúa en primer lugar. Le recomendamos que, cuando cree una regla, agregue espacios en las prioridades. Esto lo ayuda a cambiar la prioridad de las reglas y a agregar nuevas reglas. Para obtener más información, consulte [Cambio de la prioridad de una regla de enrutamiento](apigateway-routing-rules-use.md#rest-api-routing-rules-change-priority).
Para ver ejemplos de cómo API Gateway evalúa las reglas de enrutamiento, consulte [Ejemplos de cómo API Gateway evalúa las reglas de enrutamiento](rest-api-routing-rules-examples.md).
## Tipos de condiciones de las reglas de enrutamiento de API Gateway
En la siguiente sección se describen los tipos de condiciones de las reglas de enrutamiento. API Gateway solo hace coincidir una regla si se cumplen todas las condiciones.
### Condiciones de encabezado de coincidencia
Al crear una condición de encabezado, puede hacer coincidir el nombre del encabezado y el valor glob del encabezado, como `Hello:World`. API Gateway utiliza una coincidencia literal para validar las condiciones de encabezado de coincidencia. La condición puede utilizar hasta dos encabezados con `AND` entre ellos. Por ejemplo, la condición puede coincidir si una solicitud entrante contiene `Hello:World` y `x-version:beta`.
La coincidencia del nombre del encabezado no distingue entre mayúsculas y minúsculas, pero el valor glob del encabezado sí. `Hello:World` coincidirá con `hello:World`, pero no con `Hello:world`.
Para ver una lista de valores de encabezado restringidos, consulte [Restricciones](#rest-api-routing-rules-restrictions).
#### Uso de caracteres comodín con condiciones de encabezado
Solo puede utilizar caracteres comodín en el valor glob del encabezado y el carácter comodín debe ser `*prefix-match`, `suffix-match*` o `*contains*`. En la siguiente tabla se muestran ejemplos de cómo utilizar comodines para la coincidencia de condiciones de encabezado.
| Condiciones de encabezado | Solicitudes que coinciden con la regla de enrutamiento | Solicitudes que no coinciden con la regla de enrutamiento |
| --- | --- | --- |
| `x-version: a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *a*` y `x-version: *b*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: b*` y `x-version: *a` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `x-version: *` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) | Ninguno |
Si crea condiciones para varios valores de encabezado, como `Accept:application/json,text/xml`, le recomendamos que utilice `*contains*` para las condiciones de encabezado y evite crear condiciones utilizando el carácter de coma (`,`).
Dado que API Gateway enruta las condiciones de encabezado literalmente, las coincidencias semánticas podrían enrutarse de forma diferente. En la siguiente tabla se muestra la diferencia en los resultados de las reglas de enrutamiento.
| Condiciones de encabezado | Solicitudes que coinciden con la regla de enrutamiento | Solicitudes que no coinciden con la regla de enrutamiento |
| --- | --- | --- |
| `Accept: *json` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) |
| `Accept: *json*` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/rest-api-routing-rules.html) | Ninguno |
### Coincidencia de condiciones de ruta base
Al crear una condición de ruta base, si la solicitud entrante contiene la ruta especificada, la regla coincide. La coincidencia distingue entre mayúsculas y minúsculas, por lo que la ruta `New/Users` no coincidirá con `new/users`.
Puede crear una condición de ruta base solo para una ruta base.
Para obtener una lista de condiciones de ruta base restringidas, [Restricciones](#rest-api-routing-rules-restrictions).
#### Eliminación de la ruta base con condiciones de ruta base
Cuando crea una condición de ruta base, puede elegir eliminar la ruta base. Cuando elimina la ruta base, API Gateway elimina la ruta base coincidente entrante cuando invoca la API de destino. Este es el mismo comportamiento que cuando utiliza una asignación de API. Si no elimina la ruta base, API Gateway reenvía toda la ruta base a la API de destino. Le recomendamos que solo elimine la ruta base cuando vuelva a crear una asignación de API.
En la siguiente tabla se muestran ejemplos de cómo API Gateway evalúa la condición de eliminación de la ruta base.
| Condición | Eliminación de la ruta base | Solicitud entrante | Resultado |
| --- | --- | --- | --- |
| Si la ruta base contiene `PetStoreShopper/dogs` | True | `GET https://example.com/PetStoreShopper/dogs` | API Gateway llama al método `GET` del recurso `/`. |
| Si la ruta base contiene `PetStoreShopper/dogs`. | False | `GET https://example.com/PetStoreShopper/dogs` | API Gateway llama al método `GET` del recurso `PetStoreShopper/dogs`. |
| Si la ruta base contiene `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper/dogs` | API Gateway llama al método `GET` del recurso `dogs`. |
| Si la ruta base contiene `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper/dogs` | API Gateway llama al método `GET` del recurso `PetStoreShopper/dogs`. |
| Si la ruta base contiene `PetStoreShopper` | True | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway llama al método `GET` del recurso `/` con el parámetro de cadena de consulta `birds=available`. |
| Si la ruta base contiene `PetStoreShopper` | False | `GET https://example.com/PetStoreShopper?birds=available` | API Gateway llama al método `GET` del recurso `/PetStoreShopper` con el parámetro de cadena de consulta `birds=available`. |
## Restricciones
+ La API de destino y el nombre de dominio personalizado deben estar en la misma cuenta de AWS.
+ Cada regla puede tener una API de destino.
+ Solo puede crear una regla de enrutamiento para un nombre de dominio personalizado privado hacia una API privada y para un nombre de dominio personalizado público hacia una API pública. No puede mezclar recursos públicos y privados.
+ Si el nombre de dominio personalizado tiene asignaciones de API tanto a las API de REST como de HTTP, no se admiten las reglas de enrutamiento.
+ El número de prioridad máximo es 1 000 000.
+ Restricciones de encabezado:
+ Cada condición `anyOf` solo puede contener un valor de encabezado.
+ Los únicos caracteres permitidos para los nombres de encabezado y los valores glob de encabezado están especificados por [RFC 7230](https://datatracker.ietf.org/doc/html/rfc7230), que son `a-z`, `A-Z`, `0-9` y los siguientes caracteres especiales: `*?-!#$%&'.^_`|~`.
+ Puede utilizar un comodín en el valor glob del encabezado, pero el comodín debe ser `*prefix-match`, `suffix-match*` o `*contains*`. No puede utilizar `*` en medio de un valor glob de encabezado.
+ No se admiten nombres de encabezado con caracteres comodín.
+ El nombre del encabezado debe tener menos de 40 caracteres.
+ El valor glob del encabezado debe tener menos de 128 caracteres.
+ El valor glob del encabezado para una coincidencia de infijo debe tener menos de 40 caracteres.
+ Los siguientes encabezados no se admiten como condiciones:
+ `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`
+ Restricciones de la ruta base:
+ La longitud de la ruta base debe ser inferior a 128 caracteres.
+ La ruta base debe contener solo letras, números y los siguientes caracteres: `$-_.+!*'()/`.
Estos caracteres no se admiten en expresiones regulares (regex).
+ La ruta base no puede empezar ni terminar por el carácter de barra invertida (`\`).
# Ejemplos de cómo API Gateway evalúa las reglas de enrutamiento
A continuación se muestran cuatro ejemplos de cómo API Gateway evalúa las reglas de enrutamiento y las asignaciones de API.
## Ejemplo 1: solo reglas de enrutamiento
En este ejemplo, el nombre de dominio personalizado `https://petstore.example.com` tiene el modo de enrutamiento establecido en `ROUTING_RULE_ONLY` y tiene las siguientes reglas de enrutamiento y prioridades.
| ID de regla | Prioridad | Condiciones | Acción |
| --- | --- | --- | --- |
| `abc123` | 10 | Si la solicitud contiene el encabezado `Hello:World` | API de destino 1 |
| `zzz000` | 50 | Si la solicitud contiene los encabezados `Accept:image/webp` y `Pet:Dog-*` y si la ruta base contiene `PetStoreShopper` | API de destino 2 |
| `efg456` | 100 | Ninguno | API de destino 3 |
En la siguiente tabla se muestra cómo API Gateway aplica las reglas de enrutamiento anteriores a las solicitudes de ejemplo.
| Solicitud | API seleccionada | Explicación |
| --- | --- | --- |
| `https://petstore.example.com -h "Hello:World"` | API de destino 1 | La solicitud coincide con la regla de enrutamiento `abc123`. |
| `https://petstore.example.com/PetStoreShopper -h "Hello:World", "Pet:Dog-Bella", "Accept:image/webp"` | API de destino 1 | API Gateway evalúa todas las reglas de enrutamiento por orden de prioridad. La regla de enrutamiento `abc123` tiene la primera prioridad y las condiciones coinciden, por lo que API Gateway invoca la API de destino 1. Aunque las condiciones de la solicitud también coinciden con la regla de enrutamiento `zzz000`, API Gateway no evalúa ninguna otra regla de enrutamiento después de establecer una coincidencia. |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella", "Accept:image/webp"` | API de destino 2 | La solicitud coincide con la regla de enrutamiento `zzz000`. Esta coincidencia se debe a que la cadena `Pet:Dog-Bella` coincidía con `Pet:Dog-*` |
| `https://petstore.example.com/PetStoreShopper -h "Pet:Dog-Bella"` | API de destino 3 | La solicitud no coincide con la regla de enrutamiento `abc123`. La solicitud no coincide con la regla de enrutamiento `zzz000` porque no están presentes todos los encabezados requeridos. La siguiente regla de prioridad coincide con todas las solicitudes entrantes, por lo que API Gateway invoca la API de destino 3. |
## Ejemplo 2: reglas de enrutamiento y asignaciones de API
En este ejemplo, el nombre de dominio personalizado `https://petstore.diagram.example.com` tiene el modo de enrutamiento establecido en `ROUTING_RULE_THEN_API_MAPPING` y tiene las siguientes reglas de enrutamiento y asignaciones de API.
| ID de regla | Prioridad | Condiciones | Acción |
| --- | --- | --- | --- |
| `abc123` | 1 | Si la base de la solicitud contiene `pets` | Invoque la etapa `Prod` de la API `PetStore`. |
| `000zzz` | 5 | Si la solicitud contiene los encabezados `Cookie`:`*ux=beta*` y si la ruta base contiene `/refunds` | Invoque la etapa `Beta` de la API `Refunds`. |
En la siguiente tabla se muestran las asignaciones de la API para `https://petstore.backup.example.com`.
| Mapeo de API | API seleccionada |
| --- | --- |
| `/refunds` | Invoque la etapa `Prod` de la API `Refunds`. |
| `(none)` | Invoque la etapa `Prod` de la API `Search`. |
En el siguiente diagrama se muestra cómo API Gateway aplica las reglas de enrutamiento anteriores a las solicitudes de ejemplo. Las solicitudes de ejemplo se resumen en la tabla que sigue a este diagrama.
![\[Diagrama de cómo API Gateway aplica las reglas de enrutamiento anteriores y las asignaciones de API.\]](http://docs.aws.amazon.com/es_es/apigateway/latest/developerguide/images/rr-diagram.png)
En la siguiente tabal se muestra cómo API Gateway aplica las reglas de enrutamiento anteriores a las solicitudes de ejemplo.
| Solicitud | API seleccionada | Explicación |
| --- | --- | --- |
| `https://petstore.diagram.com/pets` | La etapa `Prod` de la API `PetStore`. | La solicitud coincide con la regla de enrutamiento `abc123`. |
| `https://petstore.diagram.example.com/refunds -h "Cookie:lang=en-us;ux=beta"` | La etapa `Beta` de la API `Refunds`. | La solicitud coincide con la regla de enrutamiento `000zzz`. El encabezado `Cookie` contiene la coincidencia `*contains*` correcta y la coincidencia de ruta base para esta condición. |
| `https://petstore.diagram.example.com/refunds` | La etapa `Prod` de la API `Refunds`. | La solicitud no tiene los encabezados necesarios para la coincidencia con la regla de enrutamiento `zzz000`. Si API Gateway no puede hacer coincidir correctamente una regla de enrutamiento, recurre a las asignaciones de API. API Gateway puede asignar la ruta base a la etapa `Prod` de la API `Refunds`. |
| `https://petstore.diagram.example.com/` | La etapa `Prod` de la API `Search`. | La solicitud coincide con la asignación de la API a la ruta vacía `(none)`. |
## Ejemplo 3: reglas de enrutamiento y asignaciones de API con varios niveles
En este ejemplo, el nombre de dominio personalizado `https://petstore.backup.example.com` tiene el modo de enrutamiento establecido en `ROUTING_RULE_THEN_API_MAPPING` y tiene las siguientes reglas de enrutamiento y asignaciones de API.
En la siguiente tabla se muestran las reglas de enrutamiento para `https://petstore.backup.example.com`.
| ID de regla | Prioridad | Condiciones | Acción |
| --- | --- | --- | --- |
| `abc123` | 10 | Si la solicitud contiene el encabezado `Hello:World` | API de destino 1 |
| `000zzz` | 50 | Si la solicitud contiene los encabezados `Accept`:`image/webp` y `Pet:Dog-*` y si la ruta base contiene `PetStoreShopper` | API de destino 2 |
En la siguiente tabla se muestran las asignaciones de la API para `https://petstore.backup.example.com`.
| Mapeo de API | API seleccionada |
| --- | --- |
| `PetStoreShopper` | API de destino 3 |
| `PetStoreShopper/cats` | API de destino 4 |
En la siguiente tabal se muestra cómo API Gateway aplica las reglas de enrutamiento anteriores a las solicitudes de ejemplo.
| Solicitud | API seleccionada | Explicación |
| --- | --- | --- |
| `https://petstore.example.com/PetStoreShopper -h "Accept:image/webp", "Pet:Cats" ` | API de destino 3 | La solicitud no tiene los encabezados necesarios para la coincidencia con la regla de enrutamiento `zzz000`. Si API Gateway no puede hacer coincidir correctamente una regla de enrutamiento, recurre a las asignaciones de API. API Gateway puede asignar la ruta base a la API de destino 3. |
| `https://petstore.example.com/PetStoreShopper/cats -h "Hello:World"` | API de destino 1 | La solicitud coincide con la regla de enrutamiento `abc123`. Si el modo de enrutamiento se establece en `ROUTING_RULE_THEN_API_MAPPING`, las reglas de enrutamiento siempre tienen prioridad sobre las asignaciones de API. |
| `https://petstore.example.com/Admin -h "Pet:Dog-Bella"` | Ninguno | La solicitud no coincide con ninguna regla de enrutamiento ni asignación de API. Dado que no hay ninguna regla de enrutamiento predeterminada, API Gateway rechaza la llamada y envía al intermediario un código de estado `403 Forbidden`. |
## Ejemplo 4: reglas de enrutamiento para nombres de dominio comodín
En este ejemplo, el nombre de dominio personalizado `https://*.example.com` es un nombre de dominio comodín. El comodín admite todos los subdominios que enrutan al mismo dominio. Las siguientes reglas de enrutamiento de ejemplo cambian este comportamiento para permitir que los subdominios enruten a diferentes API de destino mediante el encabezado `Host`.
En la siguiente tabla se muestran las reglas de enrutamiento para `https://*.example.com`.
| ID de regla | Prioridad | Condiciones | Acción |
| --- | --- | --- | --- |
| `abc123` | 10 | Si la solicitud contiene el encabezado `Host:a.example.com` | API de destino 1 |
| `000zzz` | 50 | Si la solicitud contiene encabezados `Host:b.example.com` | API de destino 2 |
| `efg456` | 500 | Ninguno | API de destino 3 |
En la siguiente tabla se muestra cómo API Gateway aplica las reglas de enrutamiento anteriores a las solicitudes de ejemplo.
| Solicitud | API seleccionada | Explicación |
| --- | --- | --- |
| `https://a.example.com` | API de destino 1 | El encabezado `Host` es `a.example.com`. Esta solicitud coincide con la regla de enrutamiento `abc123`. |
| `https://b.example.com` | API de destino 2 | El encabezado `Host` es `b.example.com`. Esta solicitud coincide con la regla de enrutamiento `000zzz`. |
| `https://testing.example.com` | API de destino 3 | Coincide con la regla de enrutamiento catch-all `efg456`. |
# Cómo utilizar las reglas de enrutamiento
Puede crear una regla de enrutamiento mediante la Consola de administración de AWS, la AWS CLI o cualquier AWS SDK. Después de crear una regla, puede cambiar la prioridad.
## Creación de una regla de enrutamiento
El siguiente procedimiento muestra cómo crear una regla de enrutamiento para un nombre de dominio personalizado con un modo de enrutamiento establecido en `ROUTING_RULE_THEN_API_MAPPING` o `ROUTING_RULE_ONLY`.
------
#### [ Consola de administración de AWS ]
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija **Custom domain names (Nombres de dominios personalizados)** en el panel de navegación principal.
1. Elija un nombre de dominio personalizado.
1. En la pestaña **Detalles de enrutamiento**, elija **Agregar regla de enrutamiento**.
1. Elija **Agregar una nueva condición** para agregar una nueva condición.
Puede agregar una condición de encabezado o de ruta base. Para hacer coincidir todas las solicitudes entrantes con el nombre de dominio personalizado, no agregue una condición.
1. En **Acción**, utilice la lista desplegable para seleccionar la API de destino y la etapa de destino.
1. Elija **Siguiente**.
1. En el campo de prioridad, introduzca un número para la prioridad.
API Gateway evalúa las reglas en orden de prioridad, del valor más bajo al más alto.
Si va a crear una regla sin una condición, le recomendamos que utilice un valor de prioridad alto.
1. Elija **Crear regla de enrutamiento**.
------
#### [ AWS CLI ]
El siguiente comando [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) crea una regla de enrutamiento con una prioridad de 50. En este ejemplo, API Gateway enruta cualquier solicitud entrante que tenga los encabezados `Hello:World` y `x-version:beta` y la ruta base `PetStoreShopper` a la 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"
}
}
]'
```
El resultado será similar al siguiente.
```
{
"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"
}
```
------
## Cambio de la prioridad de una regla de enrutamiento
Puede cambiar la prioridad de una regla de enrutamiento. Esto tiene efecto inmediato y podría afectar el modo en que los consumidores de API invocan los nombres de dominio personalizados. Le recomendamos que, cuando establezca las prioridades de las reglas de enrutamiento, deje espacios entre las reglas.
Por ejemplo, considere dos reglas de enrutamiento, la regla `abc123` con una prioridad de 50 y la regla `zzz000` con una prioridad de 150. Para cambiar la prioridad de las reglas de modo que API Gateway evalúe primero la regla `zzz000`, puede cambiar la prioridad de la regla `zzz000` a 30.
------
#### [ Consola de administración de AWS ]
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija **Custom domain names (Nombres de dominios personalizados)** en el panel de navegación principal.
1. Elija un nombre de dominio personalizado.
1. En la pestaña **Detalles de enrutamiento**, elija la regla de enrutamiento y, a continuación, **Editar**.
1. Elija **Siguiente**.
1. Para la prioridad, introduzca la nueva prioridad.
1. Seleccione **Save changes (Guardar cambios)**.
------
#### [ AWS CLI ]
El siguiente comando [put-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/put-routing-rule.html) cambia la prioridad de una regla de enrutamiento `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"
}
}
]'
```
El resultado será similar al siguiente:
```
{
"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"
}
```
------
# Nueva creación de una asignación de API mediante reglas de enrutamiento
Puede volver a crear una asignación de API mediante reglas de enrutamiento. Para volver a crear una asignación de API, asegúrese de activar la separación de rutas base. Esto preserva el comportamiento de las asignaciones de API. Para obtener más información, consulte [Eliminación de la ruta base con condiciones de ruta base](rest-api-routing-rules.md#rest-api-routing-rules-condition-path-split).
En el siguiente tutorial se muestra cómo volver a crear la asignación de API `https:// api.example.com/orders/v2/items/categories/5` como una regla de enrutamiento y cómo actualizar los registros de acceso para registrar el ID de la regla de enrutamiento que API Gateway utiliza para enviar tráfico a la API.
------
#### [ Consola de administración de AWS ]
**Establecimiento del modo de enrutamiento en ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija **Custom domain names (Nombres de dominios personalizados)** en el panel de navegación principal.
1. Elija el nombre de dominio personalizado.
1. En **Detalles del dominio**, elija **Editar**.
1. En **Modo de enrutamiento**, elija **ROUTING\$1RULE\$1THEN\$1API\$1MAPPING**.
1. Seleccione **Save**.
Una vez establecido el modo de enrutamiento, cree la regla de enrutamiento.
**Creación de la regla de enrutamiento**
1. En la pestaña **Detalles de enrutamiento**, elija **Agregar regla de enrutamiento**.
1. Seleccione **Agregar nueva condición** y, a continuación, elija **Ruta**.
1. En **Ruta**, introduzca **orders/v2/items/categories/5**.
1. En **Eliminar ruta base**, elija **Activa**.
1. En **API de destino**, elija la API de destino.
1. En **Etapa de destino**, elija la etapa de destino.
1. Elija **Siguiente**.
1. Para la prioridad, introduzca una prioridad.
Aunque mantenga la asignación de API existente, API Gateway utilizará siempre la nueva regla de enrutamiento, ya que las reglas de enrutamiento siempre tienen prioridad sobre las asignaciones de API.
1. Seleccione **Save changes (Guardar cambios)**.
Después de crear la regla de enrutamiento, actualice el formato del registro de acceso de la etapa o cree un nuevo registro para confirmar que API Gateway utiliza la regla de enrutamiento para enviar tráfico a la API.
**Actualización de registros de acceso**
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija la API.
1. En el panel de navegación principal, elija **Etapas**.
1. En **Registros y seguimiento**, elija **Editar**.
Si no dispone de un grupo de registro, consulte [Configuración del registro de CloudWatch para las API de REST en API Gateway](set-up-logging.md).
1. Agregue **\$1context.customDomain.routingRuleIdMatched** al formato de registro.
Este grupo de registro guarda el ID de la regla de enrutamiento que API Gateway utilizó para enviar tráfico a la API. Para obtener más información, consulte [No puedo saber cómo API Gateway ha enviado tráfico a mis API](rest-api-routing-rules-troubleshoot.md#rest-api-routing-rules-logging).
1. Seleccione **Save**.
Después de actualizar los registros de acceso, invoque el nombre de dominio personalizado. El siguiente es un comando curl de ejemplo para invocar el nombre de dominio personalizado `https://api.example.com` con la ruta base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5"
```
Una vez que haya invocado correctamente el nombre de dominio personalizado, confirme que CloudWatch Logs muestra `routingRuleIdMatched`. Para obtener información sobre cómo utilizar la consola de CloudWatch Logs para ver un grupo de registros, consulte [Visualización de eventos de registro de API Gateway en la consola de CloudWatch](view-cloudwatch-log-events-in-cloudwatch-console.md).
------
#### [ AWS CLI ]
1. Utilice el siguiente comando [update-domain-name](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/update-domain-name.html) para actualizar el nombre de dominio `api.example.com` y utilizar el modo de enrutamiento `ROUTING_RULE_THEN_API_MAPPING`.
```
aws apigatewayv2 update-domain-name \
--domain-name 'api.example.com' \
--routing-mode ROUTING_RULE_THEN_API_MAPPING
```
1. Utilice el siguiente comando [create-routing-rule](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-routing-rule.html) para crear una nueva regla de enrutamiento para volver a crear la asignación de la 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. Utilice el siguiente comando [update-stage](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-stage.html) para actualizar el formato de los registros de acceso e incluir la variable `$context.customDomain.routingRuleIdMatched`. Esta variable registra el ID de la regla de enrutamiento que API Gateway utilizó para enviar tráfico a la API. Utilice este registro para confirmar que API Gateway utiliza la regla de enrutamiento para enviar tráfico a la API. Para obtener más información, consulte [No puedo saber cómo API Gateway ha enviado tráfico a mis API](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'"
```
Si no dispone de un grupo de registro, consulte [Configuración del registro de CloudWatch para las API de REST en API Gateway](set-up-logging.md).
1. Utilice el siguiente comando curl de ejemplo para invocar el nombre de dominio personalizado con la ruta base `orders/v2/items/categories/5`.
```
curl "https://api.example.com/orders/v2/items/categories/5
```
1. Utilice el siguiente comando [filter-log-events](https://docs.aws.amazon.com/cli/latest/reference/logs/filter-log-events.html) para obtener los eventos de registro del grupo de registro `access-log-group-orders` que contengan el ID de regla de enrutamiento `abc123`.
```
aws logs filter-log-events --log-group-name access-log-group-orders --filter-pattern abc123
```
Esto confirma que API Gateway utilizó la regla de enrutamiento para enviar tráfico a la API.
------
# Solución de problemas con las reglas de enrutamiento
La siguiente guía para la solución de problemas puede ayudarlo a resolver problemas con las reglas de enrutamiento.
## No puedo saber cómo API Gateway ha enviado tráfico a mis API
Puede utilizar los registros de acceso de la etapa de API de REST para registrar y solucionar problemas de las reglas de enrutamiento. Puede ver el ID de la regla de enrutamiento que API Gateway utilizó para enviar tráfico a la API mediante la variable `$context.customDomain.routingRuleIdMatched`. Para ver la asignación de API que API Gateway utilizó para enviar tráfico a la API, utilice la variable `$context.customDomain.basePathMatched`.
Para registrar las reglas de enrutamiento, debe configurar un ARN de [rol de CloudWatch Logs apropiado](set-up-logging.md#set-up-access-logging-permissions) para la cuenta y crear un grupo de registro.
El siguiente ejemplo de grupo de registro de acceso puede recuperar la información pertinente para la solución de problemas de reglas de enrutamiento y asignaciones de API. API Gateway solo rellena la variable de contexto para el mecanismo de enrutamiento que utilizó; de lo contrario, la variable de contexto es `-`.
------
#### [ 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
```
------
También le recomendamos que confirme el modo de enrutamiento para el nombre de dominio personalizado. Para obtener más información, consulte [Establecimiento del modo de enrutamiento para el nombre de dominio personalizado](set-routing-mode.md).
## No puedo habilitar las reglas de enrutamiento en mi nombre de dominio personalizado
Es posible que reciba el siguiente error de 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.
```
Recibirá este error si tiene o tenía una política de IAM que deniega el acceso a [BasePathMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagement.html#amazonapigatewaymanagement-resources-for-iam-policies) o [ApiMapping](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonapigatewaymanagementv2.html#amazonapigatewaymanagementv2-resources-for-iam-policies). Cuando habilite reglas de enrutamiento para un nombre de dominio personalizado, aunque la política seguirá denegando el acceso a `BasePathMapping` o `ApiMapping`, la misma política puede utilizarse para acceder a `RoutingRule`. Esto podría permitir a un usuario cambiar el comportamiento de enrutamiento del nombre de dominio personalizado.
Por ejemplo, si tuviera una política como la siguiente:
```
{
"Sid": "DenyCreatingApiMappings",
"Effect": "Deny",
"Action": "apigateway:POST",
"Resource": [
"arn:aws:apigateway:us-west-2::/domainnames/example.com/apimappings"
]
}
```
Cuando habilite las reglas de enrutamiento para `example.com`, esta política seguirá denegando el acceso a la creación de `ApiMapping` pero no denegará el acceso a la creación de `RoutingRule`.
Le recomendamos que audite las políticas de IAM de la cuenta. La siguiente política de ejemplo denegará el acceso a la creación de `ApiMapping`, `BasePathMapping` y `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/*"
]
}
```
Una vez que haya confirmado que todas las políticas se han actualizado, puede actualizar la configuración de cuenta de la API para habilitar las reglas de enrutamiento para una región.
Utilice el siguiente comando [update-account](https://docs.aws.amazon.com/cli/latest/reference/apigateway/update-account.html) para actualizar la configuración de cuenta de la API para una región:
```
aws apigateway update-account --patch-operations 'op=remove,path=/features,value=BlockedForRoutingRules' --region us-west-2
```
Después de actualizar la configuración de cuenta de la API, puede cambiar el modo de enrutamiento del nombre de dominio personalizado. También puede seguir utilizando las políticas de IAM para denegar el acceso a `RoutingRules`, `ApiMapping` o `BasePathMapping`.
# Uso de las asignaciones de API para conectar etapas de API a un nombre de dominio personalizado para las API de REST
Las asignaciones de API se utilizan para conectar etapas de la API a un nombre de dominio personalizado. Esto envía el tráfico a sus API a través de su nombre de dominio personalizado.
Una asignación de API especifica una API, una etapa y, de forma opcional, una ruta que se utilizará para la asignación. Por ejemplo, puede asignar `https://api.example.com/orders` a la etapa `production` de una API.
Puede asignar etapas de API HTTP y de API de REST al mismo nombre de dominio personalizado.
Antes de crear una asignación de API, debe tener una API, una etapa y un nombre de dominio personalizado. Para obtener más información sobre cómo crear un nombre de dominio personalizado, consulte [Configuración de un nombre de dominio personalizado regional en API Gateway](apigateway-regional-api-custom-domain-create.md).
## Solicitudes entrantes para el nombre de dominio personalizado
Cuando asigna un nombre de dominio personalizado a una etapa de la API, API Gateway elimina la ruta base entrante. Esto elimina la ruta base asignada de la invocación a la API. Por ejemplo, si la asignación de ruta base fuera `https://api.example.com/orders/shop/5` para la etapa `test` y utilizara la siguiente solicitud, `https://api.example.com/orders/shop/5/hats`, API Gateway invocaría el recurso `/hats` de la etapa `test` de la API, no el recurso `orders/shop/5/hats`.
## Asignación de solicitudes a la API
A continuación se explica cómo API Gateway evalúa las asignaciones de la API.
Puede crear una asignación de la API mediante asignaciones de un solo nivel, como una asignación de la API desde `orders` a la etapa `beta` de una API y una asignación de la API desde `shipping` a la etapa `alpha` de una API. En el caso de los nombres de dominio personalizados regionales con la política de seguridad TLS 1.2, API Gateway admite asignaciones de la API de varios niveles. Puede crear una asignación de la API de `orders/v1/items` a la etapa `alpha` de una API y de `orders/v2/items` a la etapa `beta` de una API. Cuando crea una asignación con varios niveles, API Gateway envía las solicitudes a la asignación de la API que tenga la ruta de coincidencia más larga.
Puede crear una asignación de la API a la ruta vacía `(none)`. Si ninguna ruta coincide con la solicitud, API Gateway envía la solicitud a la ruta vacía `(none)`.
En este ejemplo, el nombre de dominio personalizado `https://api.example.com` tiene las siguientes asignaciones de la API.
| Asignación de API | API seleccionada |
| --- | --- |
| `(none)` | API 1 |
| `orders` | API 2 |
| `orders/v1/items` | API 3 |
| `orders/v2/items` | API 4 |
| `orders/v1/items/categories` | API 5 |
En la siguiente tabla se muestra cómo API Gateway aplica las asignaciones de API anteriores a las solicitudes de ejemplo.
| Solicitud | API seleccionada | Explicación |
| --- | --- | --- |
| `https://api.example.com/orders` | API 2 | La solicitud coincide exactamente con esta asignación de API. |
| `https://api.example.com/orders/v1/items` | API 3 | La solicitud coincide exactamente con esta asignación de API. |
| `https://api.example.com/orders/v2/items` | API 4 | La solicitud coincide exactamente con esta asignación de API. |
| `https://api.example.com/orders/v1/items/123` | API 3 | API Gateway elige la asignación con la ruta de coincidencia más larga. El `123` al final de la solicitud no afecta a la selección. Consulte [Solicitudes entrantes para el nombre de dominio personalizado](#rest-api-mappings-incoming-requests). |
| `https://api.example.com/orders/v2/items/categories/5` | API 5 | API Gateway elige la asignación con la ruta de coincidencia más larga. |
| `https://api.example.com/customers` | API 1 | API Gateway utiliza la asignación vacía como un catch-all. |
| `https://api.example.com/ordersandmore` | API 2 | API Gateway elige la asignación con el prefijo de coincidencia más largo. En el caso de un nombre de dominio personalizado configurado con asignaciones de un solo nivel, por ejemplo, solo `https://api.example.com/orders` y `https://api.example.com/`, API Gateway elegiría `API 1`, ya que no hay una ruta que coincida con `ordersandmore`. |
## Restricciones
+ En el caso de una asignación de API, el nombre de dominio personalizado y las API asignadas deben pertenecer a la misma cuenta de AWS.
+ Las asignaciones de API deben contener solo letras, números y los siguientes caracteres: `$-_.+!*'()/`.
+ La longitud máxima de la ruta en una asignación de API es de 300 caracteres.
+ Puede tener 200 asignaciones de API con varios niveles para cada nombre de dominio. Este límite no incluye la asignación de la API con niveles únicos, como `/prod`.
+ Solo puede asignar API HTTP a un nombre de dominio regional personalizado con la política de seguridad de TLS 1.2.
+ No puede asignar las API de WebSocket al mismo nombre de dominio personalizado que una API HTTP o API REST.
+ Después de crear sus asignaciones de API, debe crear o actualizar el registro de recursos del proveedor de DNS para asignarlo al punto de conexión de la API.
+ Si crea una asignación de API con varios niveles, API Gateway convierte todos los nombres de encabezado a minúsculas.
## Creación de una asignación de API
Para crear una asignación de API, primero debe crear un nombre de dominio personalizado, una API y una etapa. El nombre de dominio personalizado debe tener un modo de enrutamiento establecido en `ROUTING_RULE_THEN_API_MAPPING` o `API_MAPPING_ONLY`. Para obtener información sobre cómo establecer el modo de enrutamiento, consulte [Establecimiento del modo de enrutamiento para el nombre de dominio personalizado](set-routing-mode.md).
Para ver ejemplos de las plantillas de AWS Serverless Application Model que crean todos los recursos, consulte [Sessions With SAM](https://github.com/aws-samples/sessions-with-aws-sam/tree/master/custom-domains) en GitHub.
------
#### [ Consola de administración de AWS ]
1. Inicie sesión en la consola de API Gateway en [https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway).
1. Elija **Custom domain names (Nombres de dominios personalizados)** en el panel de navegación principal.
1. Elija un nombre de dominio personalizado.
1. En la pestaña **Detalles de enrutamiento**, elija **Configurar los mapeos de la API**.
1. Especifique los valores de **API**, **Etapa** y **Ruta** para el mapeo.
1. Seleccione **Save**.
------
#### [ AWS CLI ]
El siguiente comando [create-api-mapping](https://docs.aws.amazon.com/cli/latest/reference/apigatewayv2/create-api-mapping.html) permite crear una asignación de API. En este ejemplo, API Gateway envía solicitudes a `api.example.com/v1/orders` a la API y a la etapa especificadas.
**nota**
Para crear mapeos de la API con varios niveles, debe utilizar `apigatewayv2`.
```
aws apigatewayv2 create-api-mapping \
--domain-name api.example.com \
--api-mapping-key v1/orders \
--api-id a1b2c3d4 \
--stage test
```
------
#### [ CloudFormation ]
El siguiente ejemplo de CloudFormation crea un mapeo de la API.
**nota**
Para crear mapeos de la API con varios niveles, debe utilizar `AWS::ApiGatewayV2`.
```
MyApiMapping:
Type: 'AWS::ApiGatewayV2::ApiMapping'
Properties:
DomainName: api.example.com
ApiMappingKey: 'orders/v2/items'
ApiId: !Ref MyApi
Stage: !Ref MyStage
```
------