Seleção Dinâmica de Back-Ends do API Gateway com Base em Elementos de Solicitação

Exemplo 1: Selecionar back-end por Host

Você pode configurar uma implantação de API para selecionar dinamicamente um back-end com base no host para o qual a solicitação original foi enviada (extraída do campo do host do cabeçalho Host na solicitação). Esse design permite definir um gateway de API que suporte tenants diferentes.

{
  "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"
            }
          }
        ]
      }
    }
  ]
}

Neste exemplo, a forma como o gateway de API resolve uma solicitação para https://<gateway-hostname>/marketing/sales depende do host para o qual a solicitação original foi enviada (extraída do campo do host do cabeçalho Host na solicitação), da seguinte forma:

• Se a solicitação tiver sido enviada para cars.example.com, a solicitação será roteada para http://cars-api.example.com.
• Se a solicitação tiver sido enviada para minivans.examplecloud.com ou trucks.example.com, ela será roteada para um back-end de função sem servidor no OCI Functions.
• Se a solicitação tiver sido enviada para outro host, a solicitação será roteada para http://cars-api.example.com por padrão.

Exemplo 2: Selecionar back-end por Subdomínio de Host

Você pode configurar uma implantação de API para selecionar dinamicamente um back-end com base em um subdomínio na string de host para a qual a solicitação original foi enviada. A string do host é extraída do cabeçalho do Host na solicitação e mascarada por uma string especificada, deixando o subdomínio usado para rotear a solicitação. Esse design permite definir um gateway de API que suporte tenants diferentes.

{
  "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"
            }
          }
        ]
      }
    }
  ]
}

Neste exemplo, a forma como o gateway de API resolve uma solicitação para https://<gateway-hostname>/marketing/sales depende do subdomínio do host para o qual a solicitação original foi enviada, da seguinte forma:

• se a solicitação tiver sido enviada para cars.example.com, a solicitação será roteada para http://cars-api.example.com
• se a solicitação tiver sido enviada para minivans.example.com ou trucks.example.com, a solicitação será roteada para um back-end de função sem servidor no OCI Functions
• se a solicitação tiver sido enviada para outro subdomínio de example.com (como car.example.com ou sedan.example.com), a solicitação será roteada para http://cars-api.example.com por padrão

Exemplo 3a: Selecione back-end por Subdomínio de Host (modificando o nome do host no URL de back-end e usando um tipo de correspondência ANY_OF)

Você pode configurar uma implantação de API para selecionar dinamicamente um back-end com base em um subdomínio na string de host para a qual a solicitação original foi enviada. A string do host é extraída do cabeçalho Host na solicitação e mascarada por uma string especificada, deixando o subdomínio usado para rotear a solicitação. Para validação adicional, você pode incluir a máscara de subdomínio como uma variável de contexto no url de back-end para garantir que as solicitações sejam roteadas apenas para back-ends que você pretende expor. Se você especificar ANY_OF como o tipo de correspondência, o valor da variável de contexto não poderá incluir curingas e deverá corresponder exatamente a um dos valores routes.routingBackends.key para que a solicitação seja enviada ao back-end.

{
  "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"
            }
          }
        ]
      }
    }
  ]
}

Neste exemplo, a forma como o gateway de API resolve uma solicitação para https://<gateway-hostname>/marketing/sales depende do subdomínio do host para o qual a solicitação original foi enviada, da seguinte forma:

• se a solicitação tiver sido enviada para cars.example.com ou hatchbacks.example.com, a solicitação será roteada para http://cars-api.example.com ou http://hatchbacks-api.example.com
• se a solicitação tiver sido enviada para outro subdomínio de example.com (como suvs.example.com ou sedans.example.com), a solicitação falhará.

Se você estiver considerando modificar o nome do host no URL de back-end incluindo uma variável de contexto, conforme mostrado neste exemplo, observe o seguinte:

• Você só pode modificar o url de back-end usando a variável de contexto especificada para selector.
• Para impor a lista de back-ends permitidos, não defina "isDefault: "true" para nenhuma regra.

Exemplo 3b: Selecione back-end por Subdomínio de Host (modificando o nome do host no URL de back-end e usando um tipo de correspondência de WILDCARD)

Você pode configurar uma implantação de API para selecionar dinamicamente um back-end com base em um subdomínio na string de host para a qual a solicitação original foi enviada. A string do host é extraída do cabeçalho Host na solicitação e mascarada por uma string especificada, deixando o subdomínio usado para rotear a solicitação. Para validação adicional, você pode incluir a máscara de subdomínio como uma variável de contexto no url de back-end para garantir que as solicitações sejam roteadas apenas para back-ends que você pretende expor. Se você especificar WILDCARD como o tipo de correspondência, o valor da variável de contexto poderá incluir curingas e deverá corresponder a um dos valores routes.routingBackends.key para que a solicitação seja enviada ao back-end.

{
  "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"
            }
          }
        ]
      }
    }
  ]
}

Neste exemplo, a forma como o gateway de API resolve uma solicitação para https://<gateway-hostname>/marketing/sales depende de se o subdomínio do host ao qual a solicitação original foi enviada corresponde ao valor routes.routingBackends.key, incluindo o curinga. Nesse caso, se a solicitação original foi enviada para um subdomínio host que termina na letra 's', da seguinte forma:

• Se a solicitação foi enviada para um subdomínio que termina na letra 's', a solicitação é encaminhada adequadamente. Por exemplo, as solicitações enviadas para cars.example.com, hatchbacks.example.com, suvs.example.com ou sedans.example.com são roteadas para http://cars-api.example.com, http://hatchbacks-api.example.com, http://suvs-api.example.com ou http://sedans-api.example.com, respectivamente.
• Se a solicitação foi enviada para um subdomínio que não termina na letra 's', a solicitação falha. Por exemplo, as solicitações enviadas para truck.example.com ou tractor.example.com falham.

Se você estiver considerando modificar o nome do host no URL de back-end incluindo uma variável de contexto, conforme mostrado neste exemplo, observe o seguinte:

• Você só pode modificar o url de back-end usando a variável de contexto especificada para selector.
• Ao usar curingas, configure o curinga com cuidado. A configuração incorreta do curinga pode fazer com que as solicitações sejam roteadas para back-ends não intencionais. Por exemplo, no exemplo, as solicitações enviadas para buses.example.com são roteadas corretamente para http://buses-api.example.com conforme esperado. No entanto, essa configuração também roteia solicitações enviadas originalmente para bus.example.com e s.example.com para http://bus-api.example.com e http://s-api.example.com, respectivamente, nenhuma das quais foi planejada.

Exemplo 4: Selecionar back-end por Plano de Uso

Você pode configurar uma implantação de API para selecionar dinamicamente um back-end com base no OCID de um plano de uso no qual o cliente de API está inscrito (identificado com base em um token de cliente na solicitação original). O OCID do plano de uso é armazenado na variável 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"
            }
          }
        ]
      }
    }
  ]
}

Neste exemplo, a forma como o gateway de API resolve uma solicitação para https://<gateway-hostname>/marketing/sales depende do plano de uso no qual o cliente de API está inscrito. Dois planos de uso foram definidos da seguinte forma:

• Free Tier, que tem o OCID ocid1.usageplan.oc1..aaaaaaaaab______gap. Quando esse OCID é o valor da variável de contexto request.usage_plan[id], a solicitação é roteada para http://dev.example.com/. O plano de uso Free Tier também será usado como padrão se a solicitação não incluir um token do cliente.
• Premium Tier, que tem o OCID ocid1.usageplan.oc1..aaaaaaaaay______lcf. Quando esse OCID é o valor da variável de contexto request.usage_plan[id], a solicitação é roteada para http://api.example.com

Exemplo 5: Selecionar back-end por Parâmetro de Cabeçalho

Você pode configurar uma implantação de API para selecionar dinamicamente um back-end com base em um parâmetro passado no cabeçalho da solicitação 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"
            }
          }
        ]
      }
    }
  ]
}

Neste exemplo, a forma como o gateway de API resolve uma solicitação para https://<gateway-hostname>/marketing/sales depende do valor do cabeçalho Accept na solicitação original, da seguinte forma:

• se o cabeçalho Accept solicitar uma resposta no formato application/json, a solicitação será roteada para http://api.example.com
• se o cabeçalho Accept solicitar uma resposta no formato application/xml, a solicitação será roteada para http://xml.example.com

Exemplo 6: Selecionar back-end por Parâmetro de Autenticação

Você pode configurar uma implantação de API para selecionar dinamicamente um back-end com base em um parâmetro de autenticação (também conhecido como 'claim') retornado por uma função de autorizador ou contido em um JWT (JSON Web Token).

{
  "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"
            }
          }
        ]
      }
    }
  ]
}

Neste exemplo, a forma como o gateway de API resolve uma solicitação para https://<gateway-hostname>/marketing/sales depende do valor da reivindicação tenant retornada por uma função de autorizador, da seguinte forma:

• se a variável de contexto request.auth[tenant] for definida como tenant-cars, a solicitação será roteada para http://cars-api.example.com
• se a variável de contexto request.auth[tenant] for definida como tenant-trucks, a solicitação será roteada para http://trucks-api.example.com

Exemplo 7: Selecionar back-end por Parâmetro de Consulta

Você pode configurar uma implantação de API para selecionar dinamicamente um back-end com base em um parâmetro de consulta transmitido pela solicitação 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"
            }
          }
        ]
      }
    }
  ]
}

Neste exemplo, a forma como o gateway de API resolve uma solicitação para https://<gateway-hostname>/marketing/sales depende do valor do parâmetro de consulta vehicle-type informado pela solicitação original, da seguinte forma:

• Se o parâmetro de consulta vehicle-type tiver o valor car, a solicitação será roteada para cars-api.example.com.
• Se o parâmetro de consulta vehicle-type tiver um valor truck ou minivan, a solicitação será roteada para uma função sem servidor no OCI Functions para processamento.
• Se o valor do parâmetro de consulta vehicle-type não for car, nem truck nem minivan, a solicitação será roteada para cars-api.example.com por padrão: