Documentation Oracle Cloud Infrastructure

Ajout de variables de contexte aux stratégies et aux définitions de back-end HTTP

Découvrez comment utiliser les paramètres dans les appels d'API à l'aide des variables de contexte API Gateway.

Les appels aux API déployées sur une passerelle d'API incluent généralement les paramètres à utiliser lors de la définition des éléments suivants dans les spécifications de déploiement d'API :

  • stratégies de demande et de réponse,
  • back-ends HTTP et HTTPS.

Pour vous permettre d'utiliser les paramètres inclus dans les appels d'API, le service API Gateway enregistre les valeurs des types de paramètre suivants dans des tables de contexte temporaires :

Chaque enregistrement dans une table de contexte est identifié par une clé unique.

Lors de la définition des stratégies de demande et de réponse ainsi que des back-ends HTTP et HTTPS, vous pouvez référencer la valeur d'un paramètre dans une table de contexte à l'aide d'une variable de contexte. Une variable de contexte se présente au format <context-table-name>[<key>], où :

  • <context-table-name> est l'un des éléments suivants : request.path, request.query, request.headers, request.auth, request.cert ou request.host
  • <key> correspond à l'une des valeurs suivantes :
    • un nom de paramètre de chemin défini dans la spécification de déploiement d'API,
    • un nom de paramètre de requête inclus dans la demande adressée à l'API,
    • un nom d'en-tête inclus dans la demande adressée à l'API.
    • un nom de paramètre d'authentification renvoyé par une fonction d'autorisation ou contenu dans un jeton JWT
    • le nom [client_base64], représentant un certificat validé, encodé Base64, présenté par un client d'API lors d'une liaison mTLS
    • la dernière partie du nom d'hôte à ignorer (lors de la capture de la première partie du nom d'hôte à laquelle la demande d'origine a été envoyée)
    • le nom d'un hôte auquel la demande a été envoyée (extrait du champ d'en-tête Host dans la demande)

Pour inclure la variable de contexte dans une chaîne de la spécification de déploiement d'API (par exemple, dans la propriété url d'une définition de back-end HTTP), utilisez le format ${<context-table-name>[<key>]}.

Par exemple, la variable de contexte request.path[region] dans l'exemple ci-dessous renvoie la valeur de l'enregistrement identifié par la clé region dans la table de contexte request.path.

{
  "routes": [
    {
      "path": "/weather/{region}",
      "methods": ["GET"],
      "backend": {
        "type": "HTTP_BACKEND",
        "url": "https://api.weather.gov/${request.path[region]}"
      }
    }
  ]
}

Tenez compte des points suivants :

  • Un seul enregistrement est créé dans la table de contexte pour chaque paramètre discret d'une demande HTTP. Si la demande HTTP inclut deux paramètres (ou plus) du même type et portant le même nom, la valeur de chaque paramètre ayant ce nom est enregistrée dans le même enregistrement de la table de contexte et est identifiée par la même clé. Toutefois, seule la première valeur de l'enregistrement de la table de contexte peut servir à remplacer une variable de contexte. Lorsque vous ajoutez une variable de contexte pour laquelle plusieurs valeurs peuvent exister dans l'enregistrement de table de contexte et que vous voulez utiliser la première valeur de l'enregistrement de la table de contexte à la place de la variable de contexte, ajoutez la variable de contexte à la spécification de déploiement d'API au format ${<context-table-name>[<key>]}.
  • Si une valeur de paramètre inclut des caractères spéciaux qui ont été encodés, l'encodage est conservé lorsque la valeur est enregistrée dans la table de contexte. Lorsque la valeur remplace une variable de contexte, la valeur encodée est utilisée à la place de la variable de contexte. Par exemple, si San José est inclus dans un paramètre de requête sous la forme San+Jos&#233;, la version encodée est la valeur qui remplacera la variable de contexte pour ce paramètre de requête.
  • Si la table de contexte indiquée ne contient aucune variable de contexte, cette dernière est remplacée par une chaîne vide.
  • Si une clé de variable de contexte contient un point, celui-ci est traité comme n'importe quel autre caractère. Il n'est pas traité comme un indicateur d'une relation parent-enfant entre l'une ou l'autre des parties de la chaîne.
  • Si un paramètre de chemin inclut un caractère générique (par exemple, generic_welcome*), le paramètre de chemin sans caractère générique est utilisé en guise de clé.

  • Vous pouvez inclure une variable de contexte en tant que segment de chemin dans la propriété d'URL d'une définition de back-end HTTP, mais pas en tant que paramètre de requête. Par exemple :

    • Vous pouvez utiliser la variable de contexte request.query[state] comme segment de chemin dans la propriété d'URL, comme indiqué dans la définition de back-end HTTP valide suivante : 

            {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}"
        }
      }

    • Vous ne pouvez pas utiliser la variable de contexte request.query[state] comme paramètre de requête dans la propriété d'URL, comme indiqué dans la définition de back-end HTTP non valide suivante : 

            {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}?state=${request.query[state]}"
        }
      }

    Si vous voulez transmettre une variable de contexte en tant que paramètre de requête, utilisez une stratégie de demande de transformation de paramètre de requête plutôt que d'inclure la variable de contexte en tant que paramètre de requête dans la propriété d'URL (reportez-vous à Ajout de stratégies de demande de transformation de paramètre de requête).

Exemples

Les exemples de cette section utilisent la définition de déploiement d'API et la spécification de déploiement d'API de base suivantes dans un fichier JSON :

{
  "displayName": "Marketing Deployment",
  "gatewayId": "ocid1.apigateway.oc1..aaaaaaaab______hga",
  "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
  "pathPrefix": "/marketing",
  "specification": {
    "routes": [
      {
        "path": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov"
        }
      }
    ]
  },
  "freeformTags": {},
  "definedTags": {}
}

Ces exemples s'appliquent lorsque vous définissez une spécification de déploiement d'API à l'aide des boîtes de dialogue de la console.

Exemple 1 : paramètre de chemin de requête dans une définition

Vous pouvez définir un paramètre de chemin dans la spécification de déploiement d'API, puis l'utiliser ailleurs dans celle-ci en tant que variable de contexte.

Cet exemple crée un paramètre de chemin region et l'utilise dans une variable de contexte request.path[region] dans la définition du back-end HTTP.

      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}"
        }
      }

Dans cet exemple, une demande telle que https://<gateway-hostname>/marketing/weather/west est résolue en https://api.weather.gov/west.

Exemple 2 : différents types de variable de contexte dans la même définition

Vous pouvez inclure différents types de variable de contexte dans la même définition au sein de la spécification de déploiement d'API.

Cet exemple utilise les éléments suivants dans la définition du back-end HTTP :

  • une variable de contexte de paramètre de chemin : request.path[region],
  • une variable de contexte de paramètre de requête : request.query[state].
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}"
        }
      }

Dans cet exemple, une demande telle que https://<gateway-hostname>/marketing/weather/west?state=california est résolue en https://api.weather.gov/west/california.

Exemple 3 : plusieurs variables de contexte du même type dans la même définition

Vous pouvez inclure le même type de variable de contexte plusieurs fois dans la même définition.

Cet exemple utilise les éléments suivants dans la définition du back-end HTTP :

  • une variable de contexte de paramètre de chemin : request.path[region],
  • deux variables de contexte de paramètre de requête : request.query[state] et request.query[city].
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}/${request.query[city]}"
        }
      }

Dans cet exemple, une demande telle que https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont est résolue en https://api.weather.gov/west/california/fremont.

Exemple 4 : plusieurs valeurs pour le même paramètre

Une demande HTTP peut souvent inclure plusieurs fois le même paramètre de requête. Le service API Gateway enregistre la valeur de chaque paramètre portant le même nom dans le même enregistrement de la table de contexte. Toutefois, la spécification de déploiement d'API est un cas habituel où une seule valeur peut servir à remplacer une variable de contexte. Dans ce type de situation, vous pouvez indiquer que seule la première valeur enregistrée dans la table de contexte d'une clé doit servir à remplacer la variable de contexte en plaçant la variable de contexte entre accolades ${...}.

Par exemple, une demande valide telle que "https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont&city=belmont" compte deux occurrences du paramètre de requête city. Lors de la réception de la demande HTTP, le service API Gateway écrit les deux valeurs du paramètre de requête city (fremont et belmont) dans le même enregistrement de la table request.query. Lorsque la définition d'un backend HTTP inclut ${request.query[city]}, seule la première valeur de l'enregistrement remplacera la variable de contexte.

Cet exemple utilise les éléments suivants dans la définition du back-end HTTP :

  • une variable de contexte de paramètre de chemin : request.path[region],
  • deux variables de contexte de paramètre de requête : request.query[state] et request.query[city]. 
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}/${request.query[city]}"
        }
      }

Dans cet exemple, une demande telle que https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont&city=belmont est résolue est https://api.weather.gov/west/california/fremont. Seule la valeur fremont (en tant que première valeur de l'enregistrement de la table de contexte request.query identifié par la clé city) remplace la variable de contexte request.query[city].

Exemple 5 :valeur de paramètre comprenant des caractères spéciaux encodés

Si une demande HTTP inclut des caractères spéciaux (par exemple, le caractère é ou l'espace) qui ont été encodés, la valeur est stockée dans la table de contexte sous sa forme encodée. Lorsque la valeur de la table de contexte remplace une variable de contexte, le codage est conservé.

Cet exemple utilise les éléments suivants dans la définition du back-end HTTP :

  • une variable de contexte de paramètre de chemin : request.path[region],
  • une variable de contexte de paramètre de requête : request.query[city].
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}/${request.query[city]}"
        }
      }

Dans cet exemple, une demande telle que https://<gateway-hostname>/marketing/weather/west?city=San+Jos&#233; est résolue en https://api.weather.gov/west/california/San+Jos&#233;.

Exemple 6 : paramètres d'en-tête dans une définition

Vous pouvez inclure les valeurs transmises dans les en-têtes d'une demande en tant que variables de contexte dans une définition. Si la demande inclut un en-tête, la valeur de cet en-tête est stockée dans la table request.headers et le nom de l'en-tête est utilisé comme clé.

Cet exemple utilise les éléments suivants dans la définition du back-end HTTP :

  • une variable de contexte de paramètre de chemin : request.path[region],
  • une variable de contexte de paramètre d'en-tête : request.headers[X-Api-Key].
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.headers[X-Api-Key]}"
        }
      }

Dans cet exemple, une demande telle que https://<gateway-hostname>/marketing/weather/west inclut un en-tête X-Api-Key avec la valeur abc123def456fhi789. La demande est résolue en https://api.weather.gov/west/abc123def456fhi789.

Exemple 7 : paramètres d'authentification dans une définition

Vous pouvez inclure des valeurs renvoyées par une fonction d'autorisation ou contenues dans un jeton JWT en tant que variables de contexte dans une définition :

  • Une fonction d'autorisation valide le jeton transmis par un client d'API lors de l'appel du service API Gateway. La fonction d'autorisation renvoie une réponse qui inclut des informations telles que la validité de l'autorisation, des informations sur l'utilisateur final, la portée d'accès et un certain nombre de demandes dans des paires clé-valeur. Selon le jeton d'autorisation, les informations peuvent être contenues dans le jeton, ou la fonction d'autorisation peut appeler les adresses fournies par le serveur d'autorisation pour valider le jeton et extraire les informations relatives à l'utilisateur final. Lorsque le service API Gateway reçoit une paire clé-valeur de la fonction d'autorisation, il enregistre cette paire dans la table request.auth en tant que paramètre d'authentification.
  • Un jeton JWT peut éventuellement inclure une demande personnalisée nommée scope, qui se compose d'une paire clé-valeur. Une fois le jeton JWT validé, le service API Gateway enregistre la paire clé-valeur dans la table request.auth en tant que paramètre d'authentification.

    Dans le cas du flux d'autorisation OpenID Connect, deux jetons nommés id_token (toujours encodés par JWT) et access_token (peut être encodés par JWT) sont renvoyés. Le service API Gateway enregistre les valeurs de jeton dans les variables de contexte request.auth[id_token] et request.auth[access_token], ainsi que les demandes personnalisées dans les variables de contexte request.auth[id_token_claims][<claim-name>] et request.auth[access_token_claims][<claim-name>], respectivement.

Cet exemple utilise la paire clé-valeur renvoyée par une fonction d'autorisation en tant que variable de contexte de paramètre d'authentification request.auth[region] dans la définition de back-end HTTP.

  {
    "requestPolicies": {
      "authentication": {
        "type": "CUSTOM_AUTHENTICATION",
        "isAnonymousAccessAllowed": false,
        "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq",
        "tokenHeader": "Authorization"
      }
    },
    "routes": [
      {
        "path": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.auth[region]}"
        },
        "requestPolicies": {
          "authorization": {
            "type": "ANY_OF",
            "allowedScope": [ "weatherwatcher" ]
          }
        }
      }
    ]
  }

Supposons qu'une fonction d'autorisation ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq valide le jeton transmis par un client d'API dans un appel au service API Gateway. La fonction d'autorisation renvoie une réponse au service API Gateway qui inclut la région associée à l'utilisateur final en tant que paire clé-valeur, ainsi que la portée d'accès de l'utilisateur final authentifié. Lorsque le service API Gateway reçoit la paire valeur-clé, il l'enregistre dans la table request.auth en tant que paramètre d'authentification.

Dans cet exemple, une demande comme https://<gateway-hostname>/marketing/weather est effectuée par l'utilisateur final jdoe à l'aide d'un client d'API. La fonction d'autorisation valide le jeton transmis par le client d'API dans la demande et détermine également que jdoe possède la portée d'accès "weatherwatcher". La fonction d'autorisation identifie que jdoe est associé à la région west. La fonction d'autorisation renvoie la portée d'accès de jdoe au service API Gateway, ainsi que la région associée à jdoe. Le service API Gateway enregistre la région associée à jdoe en tant que paramètre d'authentification. La définition de back-end HTTP indique que les utilisateurs finals disposant de la portée d'accès "weatherwatcher" sont autorisés à accéder au back-end HTTP. Le service API Gateway utilise la valeur de la variable de contexte de paramètre d'authentification request.auth[region] dans la demande. La demande est résolue en https://api.weather.gov/west.

Exemple 8 : paramètre de certificat TLS dans une définition

Vous pouvez inclure une version codée en Base64 du certificat TLS présenté par un client d'API lors d'un établissement de liaison mTLS en tant que variable de contexte dans une définition. La version codée en Base64 du certificat TLS est stockée dans la table request.cert, avec le nom client_base64 utilisé comme clé. Reportez-vous à Ajout de la prise en charge de mTLS aux déploiements d'API.

Cet exemple utilise les éléments suivants dans la définition du back-end HTTP :

  • la variable de contexte de certificat, request.cert[client_base64]
  {
    "requestPolicies": {
      "mutualTls":{
        "isVerifiedCertificateRequired": true,
        "allowedSans": ["api.weather.com"]
      }
    },
    "routes": [
      {
        "path": "/weather",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov"
        },
        "requestPolicies": {
          "headerTransformations": {
            "setHeaders": {
              "items":[
                {
                  "name": "certificate-header",
                  "values": ["${request.cert[client_base64]}"]
                }
              ]
            }
          }
        }
      }
    ]
  }

Dans cet exemple, un en-tête nommé certificate-header est ajouté à la demande, en fonction de la valeur de la version codée Base64 du certificat TLS présentée par le client d'API lors de l'établissement de liaison mTLS avec la passerelle d'API.