Documentación de Oracle Cloud Infrastructure

Selección dinámica de backends de gateway de API según los elementos de solicitud

Descubra cómo enrutar las solicitudes enviadas al mismo gateway de API a diferentes backends según los elementos de la solicitud con API Gateway.

Un requisito común es enrutar las solicitudes enviadas al mismo gateway de API a distintos backends según los elementos de la solicitud. Por ejemplo, para enrutar solicitudes a distintos backends en función de:

  • Host y/o dominio y/o subdominio al que se envió una solicitud. Por ejemplo, para enrutar las solicitudes entrantes de cars.example.com y trucks.example.com que se han enviado al mismo gateway de API a dos backends completamente diferentes.
  • Plan de uso al que está suscrito el cliente de API que envía una solicitud. Por ejemplo, para enrutar solicitudes entrantes a un host estándar para clientes de API suscritos a un plan de uso Free Tier o a un host de alto rendimiento para clientes de API suscritos al plan de uso Premium Tier.
  • Cabeceras y valores de cabecera en una solicitud. Por ejemplo, para enrutar una solicitud que incluya una cabecera Accept con un valor application/xml a un backend adecuado que devuelva una respuesta de ese tipo de contenido.

La selección dinámica de un backend le permite presentar una única fachada a los consumidores de API y protegerlos de la complejidad de varios sistemas backend.

Puede direccionar solicitudes de forma dinámica a:

  • backend HTTP
  • backends de función sin servidor
  • backends de respuesta de stock

Al definir varios backends para el mismo despliegue de API, cree reglas para permitir que el gateway de API seleccione de forma dinámica el backend al que enrutar una solicitud, en función de un elemento de la solicitud original.

Para permitir que el gateway de API seleccione de forma dinámica el backend correcto, utilice las siguientes variables de contexto para capturar elementos de la solicitud:

  • request.auth[<key>] donde <key> es el nombre de una reclamación devuelta por una función de autorizador o contenida en un token de JWT.
  • request.headers[<key>] donde <key> es el nombre de una cabecera incluida en la solicitud a la API.
  • request.host como nombre del host al que se ha enviado la solicitud original.
  • request.path[<key>] donde <key> es el nombre de un parámetro de ruta de acceso definido en la especificación de despliegue de API.
  • request.query[<key>] donde <key> es el nombre de un parámetro de consulta incluido en la solicitud a la API.
  • request.subdomain[<key>], donde <key> es la parte final del nombre de host que se debe ignorar al capturar la parte inicial del nombre de host al que se ha enviado la solicitud original.
  • request.usage_plan[id] donde id es el OCID de un plan de uso al que está suscrito el cliente de API.

Tenga en cuenta que si una variable de contexto tiene varios valores, solo se utiliza el primer valor al seleccionar el backend. Para obtener más información sobre las variables de contexto, consulte Agregación de variables de contexto a políticas y definiciones de backend HTTP.

Puede definir el critiria para seleccionar backends de forma dinámica en una especificación de despliegue de API mediante:

  • uso de la consola
  • edición de un archivo JSON

Notas sobre la coincidencia de reglas de backend

Al crear las reglas para determinar qué backend utilizar, puede especificar el grado de coincidencia del valor de variable de contexto con un valor determinado para que la solicitud se enrute a un backend concreto. Puede necesitar una coincidencia exacta o puede especificar un valor que empiece por un comodín o que termine por él. El gateway de API evalúa las reglas en el orden especificado (las reglas de coincidencia exacta primero, seguidas de las reglas comodín) y utiliza la primera regla de coincidencia. También puede especificar una regla por defecto que utilizar si el valor de variable de contexto no coincide con ninguna regla de backend. Si no se especifica ninguna regla como valor por defecto y el valor de variable de contexto en una solicitud entrante no coincide con ninguna regla de backend, la solicitud devuelve un error. El orden de prioridad para determinar qué regla de backend (y, por lo tanto, qué backend) utilizar se puede resumir como:

  • Si el valor de la variable de contexto coincide exactamente con el valor de una regla, utilice esa regla.
  • De lo contrario, si el valor de la variable de contexto coincide con el valor de una regla que empieza o termina con un comodín, utilice la primera regla que contenga un comodín que coincida.
  • De lo contrario, si se especifica una regla como regla por defecto, utilice esa regla.
  • De lo contrario, devolverá un error.

Uso de la consola para agregar una selección de backend dinámica a una especificación de despliegue de API

Para agregar una selección de backend dinámica a una especificación de despliegue de API mediante la consola:

  1. Cree o actualice un despliegue de API con la consola, seleccione la opción Desde cero e introduzca los detalles en la página Información básica.

    Para obtener más información, consulte Despliegue de una API en un gateway de API mediante la creación de un despliegue de API y Actualización de un gateway de API.

  2. En la página Autenticación, especifique cómo autenticar las solicitudes realizadas a las rutas en el despliegue de API.

    Para obtener más información, consulte Adding Authentication and Authorization to API Deployments.

  3. En la página Rutas, cree una nueva ruta y especifique:

    • Ruta de acceso: ruta de acceso al servicio de backend para llamadas de API mediante los métodos enumerados. Tenga en cuenta que la ruta de acceso especificada:

    • Métodos: uno o varios métodos aceptados por el servicio de backend. Por ejemplo, GET, PUT.
  4. Seleccione Agregar varios backends para especificar que desea que las solicitudes se enruten a diferentes backends, según la variable de contexto y las reglas que introduzca.
    1. En la lista Selector, seleccione la tabla de contexto (que contiene la variable de contexto) que se utilizará al determinar el backend al que enviar la solicitud, de la siguiente manera:
      • Autenticación: utilice el valor de una reclamación devuelta por una función de autorizador o incluida en un JWT (y guardada en la tabla de contexto request.auth) para determinar el backend.
      • Cabeceras: utilice el valor de una cabecera de la solicitud original (y guardado en la tabla de contexto request.headers) para determinar el backend.
      • Host: utilice el nombre del host al que se ha enviado la solicitud original (extendido del campo de host de la cabecera Host en la solicitud y guardado en la tabla de contexto request.host) para determinar el backend.
      • Ruta de acceso: utilice un parámetro de ruta de acceso de la solicitud original (y guardado en la tabla de contexto request.path) para determinar el backend.
      • Parámetros de consulta: utilice el valor de un parámetro de consulta de la solicitud original (y guardado en la tabla de contexto request.query) para determinar el backend.
      • Subdominio: utilice la parte inicial del nombre de host al que se envió la solicitud original (solo esa parte del nombre de host no especificada como clave y guardada en la tabla de contexto request.subdomain) para determinar el backend. Tenga en cuenta que la clave es la parte final del nombre de host que no se debe utilizar.
      • OCID de plan de uso: utilice el OCID de un plan de uso al que está suscrito el cliente de API (identificado a partir de un token de cliente en la solicitud original y guardado en la tabla de contexto request.usage_plan) para determinar el backend.
    2. En función de la tabla de contexto seleccionada, introduzca el nombre de la clave que se va a utilizar al determinar el backend al que se va a enviar la solicitud.
  5. Seleccione Definir backend para introducir una regla para la variable de contexto que, si se cumple, direccione la solicitud al backend que defina.
  6. Introduzca los detalles de la regla de la siguiente manera:
    • Nombre: introduzca un nombre para la regla. Utilice el nombre que introduzca para identificar el backend al hacer referencia a logs y métricas.
    • Tipo de coincidencia: especifique la precisión con la que el valor de la variable de contexto debe coincidir con un valor que introduzca para que la solicitud se direccione a este backend. Seleccione Cualquiera de si desea que la variable de contexto coincida exactamente con el valor del campo Valores. Seleccione Comodín si la variable de contexto debe coincidir con un valor del campo Expresión que contenga comodines. La coincidencia de valores no distingue entre mayúsculas y minúsculas si selecciona Cualquiera de y si selecciona Comodín.
    • Valores: (se muestra si ha seleccionado Cualquiera de en el campo Tipo de coincidencia). Especifique un valor (o varios valores en una lista separada por comas) que la variable de contexto debe coincidir exactamente. Tenga en cuenta que la coincidencia no distingue entre mayúsculas y minúsculas si ha seleccionado Cualquiera de. Tenga en cuenta también que los valores deben ser únicos en una única regla de backend y en todas las reglas de backend definidas para el despliegue de API.
    • Expresión: (se muestra si ha seleccionado Comodín en el campo Tipo de coincidencia) Especifique un valor que empiece por o termine por un comodín que la variable de contexto debe coincidir. Utilice el comodín * (asterisco) para indicar cero o más caracteres y/o el comodín + (signo más) para indicar uno o más caracteres. Tenga en cuenta que la coincidencia distingue entre mayúsculas y minúsculas si ha seleccionado Comodín. Tenga en cuenta que no puede incluir más de un comodín en un valor y no puede incluir un comodín en el medio de un valor. Tenga en cuenta también que una configuración de comodín incorrecta podría provocar que las solicitudes se enruten a backends no deseados.
    • Convertir en valor por defecto: especifique si desea utilizar el backend definido para esta regla si no hay ninguna regla de backend coincidente.
  7. Introduzca los detalles del backend de la siguiente manera:
    1. En el campo Tipo de backend, seleccione HTTP/HTTPS, Oracle Functions, Respuesta de stock o Desconexión como backend al que enrutar la solicitud si se cumple la regla introducida.
    2. Introduzca los detalles del backend seleccionado. Los detalles que se deben introducir dependerán del tipo de backend que haya seleccionado y se describen completamente en:
    3. Seleccione Definir para crear el backend y la regla asociada.
  8. (Opcional) Vuelva a seleccionar Definir backend para definir backends adicionales y reglas asociadas.
  9. (Opcional) Seleccione Another Route para introducir detalles de rutas adicionales.
  10. Seleccione Siguiente para revisar los detalles introducidos para el despliegue de API.
  11. Seleccione Crear o Guardar cambios para crear o actualizar el despliegue de API.
  12. (Opcional) Confirme que la API se ha desplegado correctamente llamándola. Para ello, consulte Llamada a una API desplegada en un gateway de API.

Edición de un archivo JSON para agregar una selección de backend dinámica a una especificación de despliegue de API

Para agregar la selección de backend dinámico a una especificación de despliegue de API en un archivo JSON:

  1. Con el editor de JSON de su elección, cree una nueva especificación de despliegue de API (consulte Creación de una especificación de despliegue de API) con el formato: 

    {
  "requestPolicies": {},
  "routes": [
    {
      "path": "<api-route-path>",
      "methods": ["<method-list>"],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "<context-table-key>"
        },
        "routingBackends": [
          {
            "key": {
              "type": "<ANY_OF|WILDCARD>",
              "values": [
                "<context-variable-value>"
              ],
              "isDefault": "<true|false>",
              "name": "<rule-name>"
            },
            "backend": {
              "type": "<backend-type>",
              "<backend-target>": "<identifier>"
            }
          }
        ]
      }
    }
  ]
}

    donde:

    • "requestPolicies" especifica políticas opcionales para controlar el comportamiento de un despliegue de API. Si desea aplicar políticas a todas las rutas de una especificación de despliegue de API, coloque las políticas fuera de la sección routes. Si desea aplicar las políticas únicamente a una ruta concreta, coloque las políticas en la sección routes. Consulte Agregación de políticas de solicitud y políticas de respuesta a especificaciones de despliegue de API.

    • <api-route-path> especifica una ruta de acceso al servicio de backend para las llamadas de API mediante los métodos enumerados. Tenga en cuenta que la ruta de acceso especificada:

    • <method-list> especifica uno o varios métodos aceptados por el servicio de backend, separados por comas. Por ejemplo, "GET, PUT".
    • "type": "DYNAMIC_ROUTING_BACKEND" especifica que desea seleccionar de forma dinámica el backend según los elementos de la solicitud.
    • "type": "SINGLE" especifica que desea utilizar una única variable de contexto para seleccionar de forma dinámica el backend.
    • "selector": "<context-table-key>" especifica la tabla de contexto (y la clave, si procede) a partir de la cual se obtiene el valor de variable de contexto que determina el backend al que se enviará la solicitud, de la siguiente manera:
      • request.auth[<key>] Utilice el valor de una reclamación devuelta por una función de autorizador o contenida en un token web JSON (JWT) para determinar el backend. <key> es el nombre de la reclamación. Por ejemplo, request.auth[tenant]
      • request.headers[<key>] Utilice el valor de una cabecera de la solicitud original para determinar el backend. <key> es el nombre de cabecera. Por ejemplo, request.headers[Accept]
      • request.host Utilice el nombre del host al que se ha enviado la solicitud original (extraído del campo de host de la cabecera Host en la solicitud) para determinar el backend.
      • request.path[<key>] Utilice un parámetro de ruta de acceso de la solicitud original para determinar el backend. <key> es el nombre del parámetro de ruta de acceso. Por ejemplo, request.path[region]
      • request.query[<key>] Utilice el valor de un parámetro de consulta de la solicitud original para determinar el backend. <key> es el nombre del parámetro de consulta. Por ejemplo, request.query[state]
      • request.subdomain[<key>] Utilice la parte inicial del nombre de host al que se ha enviado la solicitud original (solo esa parte del nombre de host no especificada como clave) para determinar el backend. Tenga en cuenta que <key> es la parte final del nombre de host que no se va a utilizar. Por ejemplo, request.subdomain[example.com]
      • request.usage_plan[id] Utilice el OCID de un plan de uso al que está suscrito el cliente de API (identificado a partir de un token de cliente en la solicitud original) para determinar el backend.
    • "key": {...} especifica la regla que se debe cumplir para enviar una solicitud al backend especificado por "backend": {…}.
    • "type": "<ANY_OF|WILDCARD>" especifica el grado de coincidencia entre el valor de la variable de contexto identificada por <context-table-key> y el valor introducido para <context-variable-value> para que la solicitud se envíe al backend especificado por "backend": {…}. Especifique ANY_OF si el valor de la variable de contexto identificada por <context-table-key> debe coincidir exactamente con el valor especificado para <context-variable-value>. Especifique WILDCARD si el valor de la variable de contexto identificada por <context-table-key> debe coincidir con un valor que contenga comodines que especifique para <context-variable-value>. La coincidencia de valores no es sensible a mayúsculas/minúsculas si especifica ANY_OF y sensible a mayúsculas/minúsculas si especifica WILDCARD.
    • <context-variable-value> es un valor que posiblemente coincida con el valor de la variable de contexto identificada por <context-table-key>. Puede incluir varias entradas "<context-variable-value>" en la matriz values:[...], separadas por comas. La solicitud se envía al backend especificado por "backend": {…} si los valores coinciden, de la siguiente manera:
      • Si ha especificado "type": "ANY_OF", los valores deben coincidir exactamente. Tenga en cuenta que los valores deben ser únicos en una única regla de backend y en todas las reglas de backend definidas para un despliegue de API. La coincidencia de valores no es sensible a mayúsculas/minúsculas si ha especificado ANY_OF.
      • Si ha especificado "type": "WILDCARD", puede especificar un valor para <context-variable-value> que empiece por o termine por un comodín. Utilice el comodín * (asterisco) para indicar cero o más caracteres y/o el comodín + (signo más) para indicar uno o más caracteres. Tenga en cuenta que no puede incluir más de un comodín en un valor y no puede incluir un comodín en el medio de un valor. La coincidencia de valores distingue entre mayúsculas y minúsculas si ha especificado WILDCARD. Tenga en cuenta también que una configuración de comodín incorrecta podría provocar que las solicitudes se enruten a backends no deseados.
      Por ejemplo, si desea que una solicitud de un cliente de API que pueda aceptar una respuesta xml (como se indica en la cabecera Accept de la solicitud) se enrute a un backend que devuelva xml, puede especificar:
      • "selector": "request.headers[Accept]"
      • "type": "ANY_OF"
      • "values": ["application/xml"]
    • "isDefault": "<true|false>" es un valor booleano opcional (true o false) que indica si se debe utilizar el backend para esta regla si no coincide ninguna regla de backend. Si no se especifica, se utilizará el valor por defecto de false.
    • "name": "<rule-name>" especifica un nombre para la regla. Utilice este nombre para identificar el backend al hacer referencia a logs y métricas.
    • <backend-type> especifica el tipo de servicio de backend. Los valores válidos son ORACLE_FUNCTIONS_BACKEND, HTTP_BACKEND y STOCK_RESPONSE_BACKEND.
    • <backend-target> y <identifier> especifican el servicio de backend. Los valores válidos para <backend-target> y <identifier> dependen del valor de <backend-type>, como se indica a continuación:

    Por ejemplo, la siguiente especificación de despliegue de API básica incluye la selección de backend dinámica que direcciona las solicitudes según el valor del parámetro de consulta vehicle-type transferido en la solicitud. Si el parámetro de consulta vehicle-type tiene el valor car, la solicitud se direcciona a cars-api.example.com. Si el parámetro de consulta vehicle-type tiene un valor de truck o minivan, la solicitud se direcciona a una función sin servidor en OCI Functions para su procesamiento. Si el valor del parámetro de consulta vehicle-type no es car, ni truck ni minivan, la solicitud se direcciona a cars-api.example.com por defecto:

    {
  "routes": [
    {
      "path": "/users/{path1*}",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.query[vehicle-type]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "cars"
              ],
              "isDefault": "true",
              "name": "car-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "minivan",
                "truck"
              ],
              "name": "truck-minivan-rule"
            },
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    }
  ]
}
  2. Guarde el archivo JSON que contiene la especificación de despliegue de API.

  3. Utilice la especificación de despliegue de API al crear o actualizar un despliegue de API de las siguientes formas:

    • Especificando el archivo JSON en la consola al seleccionar la opción Cargar API.
    • Especificando el archivo JSON en una solicitud para la API REST de gateway de API.

    Para obtener más información, consulte Despliegue de una API en un gateway de API mediante la creación de un despliegue de API.

  4. (Opcional) Confirme que la API se ha desplegado llamándola (consulte Llamada a una API desplegada en un gateway de API).

Ejemplos de selección dinámica de backends de gateway de API

En los ejemplos de esta sección se supone la siguiente definición de despliegue de API y la especificación de despliegue de API incompleto en un archivo JSON:

{
  "displayName": "Marketing Deployment",
  "gatewayId": "ocid1.apigateway.oc1..aaaaaaaab______hga",
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
  "pathPrefix": "/marketing",
  "specification": {
    "routes": [
      {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        .
        .
        .
        }
      }
    ]
  },
  "freeformTags": {},
  "definedTags": {}
}

Tenga en cuenta que los ejemplos también se aplican al definir una especificación de despliegue de API mediante cuadros de diálogo de la consola.

Ejemplo 1: selección de backend por host

Puede configurar un despliegue de API para seleccionar de forma dinámica un backend según el host al que se ha enviado la solicitud original (extraído del campo de host de la cabecera Host de la solicitud). Este diseño permite definir un gateway de API que soporte diferentes inquilinos. 

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.host"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "cars.example.com"
              ],
              "isDefault": "true",
              "name": "car-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "minivans.examplecloud.com",
                "trucks.example.com"
              ],
              "name": "truck-minivan-rule"
            },
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    }
  ]
}

En este ejemplo, la forma en que el gateway de API resuelve una solicitud a https://<gateway-hostname>/marketing/sales depende del host al que se envió la solicitud original (extracción del campo de host de la cabecera Host en la solicitud), de la siguiente manera:

  • Si la solicitud se ha enviado a cars.example.com, la solicitud se direcciona a http://cars-api.example.com.
  • Si la solicitud se ha enviado a minivans.examplecloud.com o trucks.example.com, se direcciona a un backend de función sin servidor en OCI Functions.
  • Si la solicitud se ha enviado a un host diferente, la solicitud se direcciona a http://cars-api.example.com por defecto.

Ejemplo 2: selección de backend por subdominio de host

Puede configurar un despliegue de API para seleccionar de forma dinámica un backend basado en un subdominio de la cadena de host a la que se ha enviado la solicitud original. La cadena de host se extrae de la cabecera Host de la solicitud y se enmascara con una cadena que especifique, dejando el subdominio que se utiliza para direccionar la solicitud. Este diseño permite definir un gateway de API que soporte diferentes inquilinos. 

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.subdomain[example.com]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "cars"
              ],
              "isDefault": "true",
              "name": "car-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "minivans",
                "trucks"
              ],
              "name": "truck-minivan-rule"
            },
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    }
  ]
}

En este ejemplo, la forma en que el gateway de API resuelve una solicitud en https://<gateway-hostname>/marketing/sales depende del subdominio de host al que se envió la solicitud original, de la siguiente manera:

  • si la solicitud se ha enviado a cars.example.com, la solicitud se direcciona a http://cars-api.example.com
  • si la solicitud se ha enviado a minivans.example.com o trucks.example.com, la solicitud se direcciona a un backend de función sin servidor en OCI Functions
  • si la solicitud se ha enviado a un subdominio diferente de example.com (como car.example.com o sedan.example.com), la solicitud se direcciona a http://cars-api.example.com por defecto

Ejemplo 3a: seleccione backend por subdominio de host (modificación del nombre de host en la URL de backend y uso de un tipo de coincidencia ANY_OF)

Puede configurar un despliegue de API para seleccionar dinámicamente un backend basado en un subdominio de la cadena de host a la que se envió la solicitud original. La cadena de host se extrae de la cabecera Host en la solicitud y se enmascara con una cadena que especifique, dejando el subdominio que se utiliza para enrutar la solicitud. Para una validación adicional, puede incluir la máscara de subdominio como una variable de contexto en la URL de backend para garantizar que las solicitudes solo se enruten a los backends que desea exponer. Si especifica ANY_OF como tipo de coincidencia, el valor de la variable de contexto no puede incluir comodines y debe coincidir exactamente con uno de los valores routes.routingBackends.key para que la solicitud se envíe al backend.

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.subdomain[example.com]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "cars",
                "hatchbacks"
              ],
              "name": "car-hatchback-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://${request.subdomain[example.com]}-api.example.com"
            }
          }
        ]
      }
    }
  ]
}

En este ejemplo, la forma en que el gateway de API resuelve una solicitud en https://<gateway-hostname>/marketing/sales depende del subdominio de host al que se envió la solicitud original, de la siguiente manera:

  • si la solicitud se ha enviado a cars.example.com o hatchbacks.example.com, la solicitud se direcciona a http://cars-api.example.com o http://hatchbacks-api.example.com
  • si la solicitud se ha enviado a un subdominio diferente de example.com (como suvs.example.com o sedans.example.com), la solicitud falla.

Si está considerando modificar el nombre de host en la URL de backend mediante la inclusión de una variable de contexto como se muestra en este ejemplo, tenga en cuenta lo siguiente:

  • Solo puede modificar la URL de backend mediante la variable de contexto especificada para selector.
  • Para aplicar la lista de backends permitidos, no defina "isDefault: "true" para ninguna regla.

Ejemplo 3b: seleccione backend por subdominio de host (modificación del nombre de host en la URL de backend y uso de un tipo de coincidencia WILDCARD)

Puede configurar un despliegue de API para seleccionar dinámicamente un backend basado en un subdominio de la cadena de host a la que se envió la solicitud original. La cadena de host se extrae de la cabecera Host en la solicitud y se enmascara con una cadena que especifique, dejando el subdominio que se utiliza para enrutar la solicitud. Para una validación adicional, puede incluir la máscara de subdominio como una variable de contexto en la URL de backend para garantizar que las solicitudes solo se enruten a los backends que desea exponer. Si especifica WILDCARD como tipo de coincidencia, el valor de la variable de contexto puede incluir comodines y debe coincidir con uno de los valores routes.routingBackends.key para que la solicitud se envíe al backend.

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.subdomain[example.com]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "WILDCARD",
              "values": [
                "*s"
              ],
              "name": "domestic-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://${request.subdomain[example.com]}-api.example.com"
            }
          }
        ]
      }
    }
  ]
}

En este ejemplo, la forma en que el gateway de API resuelve una solicitud a https://<gateway-hostname>/marketing/sales depende de si el subdominio de host al que se envió la solicitud original coincide con el valor routes.routingBackends.key, incluido el comodín. En este caso, si la solicitud original se envió a un subdominio de host que termina en la letra 's', de la siguiente manera:

  • Si la solicitud se envió a un subdominio que termina en la letra 's', la solicitud se enruta correctamente. Por ejemplo, las solicitudes enviadas a cars.example.com, hatchbacks.example.com, suvs.example.com o sedans.example.com se direccionan a http://cars-api.example.com, http://hatchbacks-api.example.com, http://suvs-api.example.com o http://sedans-api.example.com, respectivamente.
  • Si la solicitud se envió a un subdominio que no termina en la letra 's', la solicitud falla. Por ejemplo, las solicitudes enviadas a truck.example.com o tractor.example.com fallan.

Si está considerando modificar el nombre de host en la URL de backend mediante la inclusión de una variable de contexto como se muestra en este ejemplo, tenga en cuenta lo siguiente:

  • Solo puede modificar la URL de backend mediante la variable de contexto especificada para selector.
  • Al utilizar comodines, configure el comodín con cuidado. Una configuración de comodín incorrecta puede provocar que las solicitudes se enruten a backends no deseados. Por ejemplo, en el ejemplo, las solicitudes enviadas a buses.example.com se enrutan correctamente a http://buses-api.example.com como se esperaba. Sin embargo, esta configuración también enruta las solicitudes enviadas originalmente a bus.example.com y s.example.com a http://bus-api.example.com y http://s-api.example.com, respectivamente, ninguna de las cuales estaba destinada.

Ejemplo 4: selección de backend por plan de uso

Puede configurar un despliegue de API para seleccionar de forma dinámica un backend basado en el OCID de un plan de uso al que está suscrito el cliente de API (identificado a partir de un token de cliente en la solicitud original). El OCID del plan de uso se almacena en la variable de contexto request.usage_plan[id]. 

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.usage_plan[id]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "ocid1.usageplan.oc1..aaaaaaaaab______gap"
              ],
              "name": "free-rule",
              "isDefault": true
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://dev.example.com/"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "ocid1.usageplan.oc1..aaaaaaaaay______lcf"
              ],
              "name": "premium-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://api.example.com"
            }
          }
        ]
      }
    }
  ]
}

En este ejemplo, la forma en que el gateway de API resuelve una solicitud en https://<gateway-hostname>/marketing/sales depende del plan de uso al que está suscrito el cliente de API. Se han definido dos planes de uso, de la siguiente manera:

  • Free Tier, que tiene el OCID ocid1.usageplan.oc1..aaaaaaaaab______gap. Cuando este OCID es el valor de la variable de contexto request.usage_plan[id], la solicitud se direcciona a http://dev.example.com/. El plan de uso Free Tier también se utiliza como valor por defecto si la solicitud no incluye un token de cliente.
  • Premium Tier, que tiene el OCID ocid1.usageplan.oc1..aaaaaaaaay______lcf. Cuando este OCID es el valor de la variable de contexto request.usage_plan[id], la solicitud se direcciona a http://api.example.com

Ejemplo 5: selección de backend por parámetro de cabecera

Puede configurar un despliegue de API para seleccionar de forma dinámica un backend basado en un parámetro transferido en la cabecera de la solicitud original. 

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.headers[Accept]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "application/json"
              ],
              "name": "json-rule",
              "isDefault": true
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "application/xml"
              ],
              "name": "xml-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://xml.example.com"
            }
          }
        ]
      }
    }
  ]
}

En este ejemplo, la forma en que el gateway de API resuelve una solicitud en https://<gateway-hostname>/marketing/sales depende del valor de la cabecera Accept en la solicitud original, de la siguiente forma:

  • si la cabecera Accept solicita una respuesta en formato application/json, la solicitud se direcciona a http://api.example.com
  • si la cabecera Accept solicita una respuesta en formato application/xml, la solicitud se direcciona a http://xml.example.com

Ejemplo 6: selección de backend por parámetro de autenticación

Puede configurar un despliegue de API para seleccionar de forma dinámica un backend basado en un parámetro de autenticación (también conocido como "reclamación") devuelto por una función de autorizador o incluido en un token web JSON (JWT). 

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.auth[tenant]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "tenant-cars"
              ],
              "name": "cars-tenant-rule",
              "isDefault": true
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "tenant-trucks"
              ],
              "name": "trucks-tenant-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "http://trucks-api.example.com"
            }
          }
        ]
      }
    }
  ]
}

En este ejemplo, la forma en que el gateway de API resuelve una solicitud en https://<gateway-hostname>/marketing/sales depende del valor de la reclamación tenant devuelta por una función de autorizador, de la siguiente forma:

  • si la variable de contexto request.auth[tenant] está definida en tenant-cars, la solicitud se direcciona a http://cars-api.example.com
  • si la variable de contexto request.auth[tenant] está definida en tenant-trucks, la solicitud se direcciona a http://trucks-api.example.com

Ejemplo 7: Selección de backend por parámetro de consulta

Puede configurar un despliegue de API para seleccionar de forma dinámica un backend basado en un parámetro de consulta transferido por la solicitud original.

{
  "routes": [
    {
      "path": "/sales",
      "methods": [
        "GET",
        "POST",
        "PUT",
        "DELETE"
      ],
      "backend": {
        "type": "DYNAMIC_ROUTING_BACKEND",
        "selectionSource": {
          "type": "SINGLE",
          "selector": "request.query[vehicle-type]"
        },
        "routingBackends": [
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "car"
              ],
              "isDefault": "true",
              "name": "car-rule"
            },
            "backend": {
              "type": "HTTP_BACKEND",
              "url": "https://cars-api.example.com"
            }
          },
          {
            "key": {
              "type": "ANY_OF",
              "values": [
                "minivan",
                "truck"
              ],
              "name": "truck-rule"
            },
            "backend": {
              "type": "ORACLE_FUNCTIONS_BACKEND",
              "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
            }
          }
        ]
      }
    }
  ]
}

En este ejemplo, la forma en que el gateway de API resuelve una solicitud en https://<gateway-hostname>/marketing/sales depende del valor del parámetro de consulta vehicle-type transferido por la solicitud original, de la siguiente forma:

  • Si el parámetro de consulta vehicle-type tiene el valor car, la solicitud se direcciona a cars-api.example.com.
  • Si el parámetro de consulta vehicle-type tiene un valor de truck o minivan, la solicitud se direcciona a una función sin servidor en OCI Functions para su procesamiento.
  • Si el valor del parámetro de consulta vehicle-type no es car, ni truck ni minivan, la solicitud se direcciona a cars-api.example.com por defecto: