Sélection dynamique des éléments dorsaux de la passerelle d'API en fonction des éléments de demande

Exemple 1 : Sélectionner un élément dorsal par hôte

Vous pouvez configurer un déploiement d'API pour sélectionner dynamiquement un élément dorsal en fonction de l'hôte auquel la demande initiale a été envoyée (extrait du champ hôte de l'en-tête d'hôte dans la demande). Cette conception vous permet de définir une passerelle d'API qui prend en charge différents locataires.

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

Dans cet exemple, la façon dont la passerelle d'API résout une demande à https://<gateway-hostname>/marketing/sales dépend de l'hôte auquel la demande initiale a été envoyée (extrait du champ hôte de l'en-tête d'hôte dans la demande), comme suit :

• Si la demande a été envoyée à cars.example.com, elle est acheminée vers http://cars-api.example.com.
• Si la demande a été envoyée à minivans.examplecloud.com ou à trucks.example.com, elle est acheminée vers un élément dorsal de fonction sans serveur dans le service des fonctions pour OCI.
• Si la demande a été envoyée à un autre hôte, elle est acheminée vers http://cars-api.example.com par défaut.

Exemple 2 : Sélectionner un élément dorsal par sous-domaine d'hôte

Vous pouvez configurer un déploiement d'API pour sélectionner dynamiquement un élément dorsal en fonction d'un sous-domaine dans la chaîne d'hôte à laquelle la demande initiale a été envoyée. La chaîne hôte est extraite de l'en-tête Host de la demande et masquée par une chaîne que vous spécifiez, laissant le sous-domaine utilisé pour acheminer la demande. Cette conception vous permet de définir une passerelle d'API qui prend en charge différents locataires.

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

Dans cet exemple, la façon dont la passerelle d'API résout une demande à https://<gateway-hostname>/marketing/sales dépend du sous-domaine d'hôte auquel la demande initiale a été envoyée, comme suit :

• si la demande a été envoyée à cars.example.com, la demande est acheminée vers http://cars-api.example.com
• si la demande a été envoyée à minivans.example.com ou à trucks.example.com, elle est acheminée vers un élément dorsal de fonction sans serveur dans le service des fonctions pour OCI
• si la demande a été envoyée à un autre sous-domaine de example.com (par exemple, car.example.com ou sedan.example.com), la demande est acheminée vers http://cars-api.example.com par défaut

Exemple 3a : Sélectionner un élément dorsal par sous-domaine d'hôte (modification du nom d'hôte dans l'URL dorsale et utilisation du type de correspondance ANY_OF)

Vous pouvez configurer un déploiement d'API pour sélectionner dynamiquement un élément dorsal en fonction d'un sous-domaine dans la chaîne d'hôte à laquelle la demande initiale a été envoyée. La chaîne hôte est extraite de l'en-tête Host de la demande et masquée par une chaîne que vous spécifiez, laissant le sous-domaine utilisé pour acheminer la demande. Pour une validation supplémentaire, vous pouvez inclure le masque de sous-domaine en tant que variable de contexte dans l'URL dorsale afin de vous assurer que les demandes ne sont acheminées qu'aux éléments dorsaux que vous souhaitez exposer. Si vous spécifiez ANY_OF comme type de correspondance, la valeur de la variable de contexte ne peut pas inclure de caractères génériques et doit correspondre exactement à l'une des valeurs routes.routingBackends.key pour que la demande soit envoyée au serveur dorsal.

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

Dans cet exemple, la façon dont la passerelle d'API résout une demande à https://<gateway-hostname>/marketing/sales dépend du sous-domaine d'hôte auquel la demande initiale a été envoyée, comme suit :

• si la demande a été envoyée à cars.example.com ou à hatchbacks.example.com, la demande est acheminée vers http://cars-api.example.com ou http://hatchbacks-api.example.com
• si la demande a été envoyée à un autre sous-domaine de example.com (par exemple, suvs.example.com ou sedans.example.com), la demande échoue.

Si vous envisagez de modifier le nom d'hôte dans l'URL dorsale en incluant une variable de contexte comme illustré dans cet exemple, notez les points suivants :

• Vous pouvez uniquement modifier l'URL dorsale à l'aide de la variable de contexte spécifiée pour selector.
• Pour appliquer la liste des éléments dorsaux autorisés, ne définissez "isDefault: "true" pour aucune règle.

Exemple 3b : Sélectionner un élément dorsal par sous-domaine d'hôte (modification du nom d'hôte dans l'URL d'élément dorsal et utilisation d'un type de correspondance WILDCARD)

Vous pouvez configurer un déploiement d'API pour sélectionner dynamiquement un élément dorsal en fonction d'un sous-domaine dans la chaîne d'hôte à laquelle la demande initiale a été envoyée. La chaîne hôte est extraite de l'en-tête Host de la demande et masquée par une chaîne que vous spécifiez, laissant le sous-domaine utilisé pour acheminer la demande. Pour une validation supplémentaire, vous pouvez inclure le masque de sous-domaine en tant que variable de contexte dans l'URL dorsale afin de vous assurer que les demandes ne sont acheminées qu'aux éléments dorsaux que vous souhaitez exposer. Si vous spécifiez WILDCARD comme type de correspondance, la valeur de la variable de contexte peut inclure des caractères génériques et doit correspondre à l'une des valeurs routes.routingBackends.key pour que la demande soit envoyée au serveur dorsal.

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

Dans cet exemple, la façon dont la passerelle d'API résout une demande à https://<gateway-hostname>/marketing/sales dépend du fait que le sous-domaine d'hôte auquel la demande initiale a été envoyée correspond à la valeur routes.routingBackends.key, y compris le caractère générique. Dans ce cas, si la demande initiale a été envoyée à un sous-domaine hôte qui se termine par la lettre 's', comme suit :

• Si la demande a été envoyée à un sous-domaine qui se termine par la lettre 's', la demande est acheminée de manière appropriée. Par exemple, les demandes envoyées à cars.example.com, hatchbacks.example.com, suvs.example.com ou sedans.example.com sont acheminées vers http://cars-api.example.com, http://hatchbacks-api.example.com, http://suvs-api.example.com ou http://sedans-api.example.com, respectivement.
• Si la demande a été envoyée à un sous-domaine qui ne se termine pas par la lettre 's', la demande échoue. Par exemple, les demandes envoyées à truck.example.com ou tractor.example.com échouent.

Si vous envisagez de modifier le nom d'hôte dans l'URL dorsale en incluant une variable de contexte comme illustré dans cet exemple, notez les points suivants :

• Vous pouvez uniquement modifier l'URL dorsale à l'aide de la variable de contexte spécifiée pour selector.
• Lors de l'utilisation de caractères génériques, configurez le caractère générique avec soin. Une configuration de caractère générique incorrecte peut entraîner l'acheminement des demandes vers des éléments dorsaux non voulus. Par exemple, dans l'exemple, les demandes envoyées à buses.example.com sont correctement acheminées vers http://buses-api.example.com, comme prévu. Toutefois, cette configuration achemine également les demandes initialement envoyées à bus.example.com et s.example.com à http://bus-api.example.com et http://s-api.example.com respectivement, dont aucune n'était prévue.

Exemple 4 : Sélectionner un élément dorsal par plan d'utilisation

Vous pouvez configurer un déploiement d'API pour sélectionner de manière dynamique un élément dorsal en fonction de l'OCID d'un plan d'utilisation auquel le client d'API est abonné (identifié à partir d'un jeton de client dans la demande initiale). L'OCID du plan d'utilisation est stocké dans la variable de contexte 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"
            }
          }
        ]
      }
    }
  ]
}

Dans cet exemple, la façon dont la passerelle d'API résout une demande à https://<gateway-hostname>/marketing/sales dépend du plan d'utilisation auquel le client d'API est abonné. Deux plans d'utilisation ont été définis comme suit :

• Free Tier, qui a l'OCID ocid1.usageplan.oc1..aaaaaaaaab______gap. Lorsque cet OCID est la valeur de la variable de contexte request.usage_plan[id], la demande est acheminée vers http://dev.example.com/. Le plan d'utilisation Free Tier est également utilisé par défaut si la demande n'incluait pas de jeton client.
• Premium Tier, qui a l'OCID ocid1.usageplan.oc1..aaaaaaaaay______lcf. Lorsque cet OCID est la valeur de la variable de contexte request.usage_plan[id], la demande est acheminée vers http://api.example.com

Exemple 5 : Sélectionner un élément dorsal par paramètre d'en-tête

Vous pouvez configurer un déploiement d'API pour sélectionner dynamiquement un élément dorsal en fonction d'un paramètre transmis dans l'en-tête de la demande initiale.

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

Dans cet exemple, la façon dont la passerelle d'API résout une demande à https://<gateway-hostname>/marketing/sales dépend de la valeur de l'en-tête Accept dans la demande initiale, comme suit :

• si l'en-tête Accept demande une réponse au format application/json, la demande est acheminée vers http://api.example.com
• si l'en-tête Accept demande une réponse au format application/xml, la demande est acheminée vers http://xml.example.com

Exemple 6 : Sélectionner un élément dorsal par paramètre d'authentification

Vous pouvez configurer un déploiement d'API pour sélectionner dynamiquement un élément dorsal en fonction d'un paramètre d'authentification (également appelé 'claim') retourné par une fonction d'autorisation ou contenu dans un jeton 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"
            }
          }
        ]
      }
    }
  ]
}

Dans cet exemple, la façon dont la passerelle d'API résout une demande à https://<gateway-hostname>/marketing/sales dépend de la valeur de la revendication tenant retournée par une fonction d'autorisation, comme suit :

• si la variable de contexte request.auth[tenant] est réglée à tenant-cars, la demande est acheminée vers http://cars-api.example.com
• si la variable de contexte request.auth[tenant] est réglée à tenant-trucks, la demande est acheminée vers http://trucks-api.example.com

Exemple 7 : Sélectionner un élément dorsal par paramètre d'interrogation

Vous pouvez configurer un déploiement d'API pour sélectionner dynamiquement un élément dorsal en fonction d'un paramètre d'interrogation transmis par la demande initiale.

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

Dans cet exemple, la façon dont la passerelle d'API résout une demande à https://<gateway-hostname>/marketing/sales dépend de la valeur du paramètre d'interrogation vehicle-type transmis par la demande initiale, comme suit :

• Si le paramètre d'interrogation vehicle-type a la valeur car, la demande est acheminée vers cars-api.example.com.
• Si le paramètre d'interrogation vehicle-type a la valeur truck ou minivan, la demande est acheminée vers une fonction sans serveur dans le service des fonctions pour OCI pour traitement.
• Si la valeur du paramètre d'interrogation vehicle-type n'est ni car, ni truck, ni minivan, la demande est acheminée vers cars-api.example.com par défaut :