Documentation sur Oracle Cloud Infrastructure

Ajout de variables de contexte aux politiques et aux définitions d'élément dorsal HTTP

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

Les appels aux API déployées sur une passerelle d'API comprennent généralement les paramètres que vous voulez utiliser lors de la définition des spécifications de déploiement d'API suivantes :

  • Politiques de demande et de réponse
  • Éléments dorsaux HTTP et HTTPS

Pour vous permettre d'utiliser les paramètres inclus dans les appels d'API, le service de passerelle d'API 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.

Lorsque vous définissez des politiques de demande et de réponse ainsi que des éléments dorsaux 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 a le format <context-table-name>[<key>] où :

  • <context-table-name> est l'un des suivants : request.path, request.query, request.headers, request.auth, request.cert ou request.host
  • <key> est l'un des éléments suivants :
    • Un nom de paramètre de chemin défini dans la spécification de déploiement d'API
    • Un nom de paramètre d'interrogation inclus dans la demande à l'API
    • Un nom d'en-tête inclus dans la demande à l'API
    • un nom de paramètre d'authentification retourné par une fonction d'autorisation ou contenu dans un jeton Web JSON (JWT)
    • le nom [client_base64], représentant un certificat validé, encodé en Base64, présenté par un client d'API lors d'une liaison mTLS
    • la partie de fin du nom d'hôte à ignorer (lors de la capture de la partie principale du nom d'hôte à laquelle la demande initiale 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é d'URL d'une définition d'élément dorsal HTTP), utilisez le format ${<context-table-name>[<key>]}.

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

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

Notez ce qui suit :

  • Un seul enregistrement est créé dans la table de contexte pour chaque paramètre discret d'une demande HTTP. Si la demande HTTP comprend deux paramètres (ou plus) du même type et avec 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é. Cependant, seule la première valeur de l'enregistrement de table de contexte peut être remplacée à la place d'une variable de contexte. Lors de l'ajout d'une variable de contexte pour laquelle plusieurs valeurs peuvent exister dans l'enregistrement de la table de contexte et que vous voulez remplacer 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 est remplacée pour une variable de contexte, la valeur encodée est remplacée à la place de la variable de contexte. Par exemple, si San José est inclus dans un paramètre d'interrogation comme San+Jos&#233;, la version encodée est la valeur qui sera remplacée à la place de la variable de contexte pour ce paramètre d'interrogation.
  • Si une clé de variable de contexte n'existe pas dans la table de contexte indiquée, une chaîne vide est remplacée à la place de la variable de contexte.
  • Si une clé de variable de contexte contient un point, le point est traité comme tout autre caractère. Il n'est pas traité comme l'indicateur d'une relation parent-enfant entre les chaînes de chaque côté du point.
  • Si un paramètre de chemin inclut un caractère générique (par exemple, generic_welcome*), le paramètre de chemin sans le caractère générique est utilisé comme clé.

  • Vous pouvez inclure une variable de contexte en tant que segment de chemin dans la propriété URL d'une définition d'élément dorsal HTTP, mais pas en tant que paramètre d'interrogation. Par exemple :

    • Vous pouvez utiliser la variable de contexte request.query[state] en tant que segment de chemin dans la propriété URL, comme dans la définition d'élément dorsal 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] en tant que paramètre d'interrogation dans la propriété URL, comme dans la définition d'élément dorsal 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 d'interrogation, utilisez une politique de demande de transformation de paramètre d'interrogation plutôt que d'inclure la variable de contexte en tant que paramètre d'interrogation dans la propriété d'URL (voir Ajout de politiques de demande de transformation de paramètre d'interrogation).

Exemples

Les exemples de cette section supposent 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": {}
}

Notez que ces exemples s'appliquent également 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 d'interrogation 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 la spécification de déploiement d'API 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] de la définition d'élément dorsal 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 à 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 de la spécification de déploiement d'API.

Cet exemple utilise les variables suivantes dans la définition d'élément dorsal HTTP :

  • Une variable de contexte de paramètre de chemin, request.path[region]
  • Une variable de contexte de paramètre d'interrogation, 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 à 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 variables suivantes dans la définition d'élément dorsal HTTP :

  • Une variable de contexte de paramètre de chemin, request.path[region]
  • Deux variables de contexte de paramètre d'interrogation, 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 à https://api.weather.gov/west/california/fremont.

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

L'inclusion du même paramètre d'interrogation plusieurs fois dans une demande HTTP est souvent valide. Le service Passerelle d'API enregistre la valeur de chaque paramètre ayant le même nom dans le même enregistrement de la table de contexte. Cependant, dans la spécification de déploiement d'API, la plupart du temps une seule valeur peut être remplacée pour une variable de contexte. Dans ces situations, vous pouvez indiquer que seule la première valeur enregistrée dans la table de contextes pour une clé est remplacée à la place d'une variable de contexte en l'incluant entre ${...}.

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

Cet exemple utilise les variables suivantes dans la définition d'élément dorsal HTTP :

  • Une variable de contexte de paramètre de chemin, request.path[region]
  • Deux variables de contexte de paramètre d'interrogation, 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 à https://api.weather.gov/west/california/fremont. Notez que seule la valeur fremont (comme première valeur dans l'enregistrement de la table de contexte request.query identifiée par la clé city) est remplacée pour la variable de contexte request.query[city].

Exemple 5 : Valeur du paramètre incluant des caractères spéciaux encodés

Si une demande HTTP comprend des caractères spéciaux (par exemple, le caractère é, le caractère d'espacement) qui ont été encodés, la valeur est stockée dans la table de contexte sous sa forme encodée. Lors du remplacement de la valeur provenant de la table de contexte pour une variable de contexte, l'encodage est conservé.

Cet exemple utilise les variables suivantes dans la définition d'élément dorsal HTTP :

  • Une variable de contexte de paramètre de chemin, request.path[region]
  • Une variable de contexte de paramètre d'interrogation, 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 à https://api.weather.gov/west/california/San+Jos&#233;.

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

Vous pouvez inclure des valeurs transmises dans les en-têtes d'une demande en tant que variables de contexte dans une définition. Si la demande comprend un en-tête, la valeur de l'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 variables suivantes dans la définition d'élément dorsal 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 à https://api.weather.gov/west/abc123def456fhi789.

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

Vous pouvez inclure les valeurs retournées par une fonction d'autorisation ou contenues dans un jeton Web JSON (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 Passerelle d'API. La fonction d'autorisation retourne une réponse comprenant des informations telles que la validité de l'autorisation, des informations sur l'utilisateur final, l'étendue d'accès et un certain nombre de revendications en paires clé-valeur. Selon le jeton d'autorisation, les informations peuvent être contenues dans le jeton, ou la fonction d'autorisation peut appeler les points d'extrémité fournis par le serveur d'autorisation pour valider le jeton et extraire des informations sur l'utilisateur final. Lorsque le service de passerelle d'API reçoit une paire clé-valeur de la fonction d'autorisation, il enregistre la paire clé-valeur dans la table request.auth en tant que paramètre d'authentification.
  • Un jeton Web JSON (JWT) peut éventuellement inclure une revendication personnalisée nommée scope, composée d'une paire clé-valeur. Une fois le jeton JWT validé, le service de passerelle d'API 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 codés JWT) et access_token (peuvent être codés JWT) sont retournés. Le service de passerelle d'API enregistre les valeurs de jeton dans les variables de contexte request.auth[id_token] et request.auth[access_token], ainsi que les revendications personnalisées dans les variables de contexte request.auth[id_token_claims][<claim-name>] et request.auth[access_token_claims][<claim-name>], respectivement.

Dans cet exemple, la paire clé-valeur retournée par une fonction d'autorisation est utilisée en tant que variable de contexte du paramètre d'authentification request.auth[region] dans la définition d'élément dorsal 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 Passerelle d'API. La fonction d'autorisation retourne une réponse au service Passerelle d'API qui inclut la région associée à l'utilisateur final en tant que paire clé-valeur ainsi que l'étendue d'accès de l'utilisateur final authentifié. Lorsque le service de passerelle d'API reçoit la paire clé- valeur, il l'économise 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 dispose de l'étendue d'accès "weatherwatcher". La fonction d'autorisation détermine que jdoe est associée à la région west. La fonction d'autorisation retourne l'étendue d'accès de jdoe au service de passerelle d'API, ainsi que la région associée à jdoe. Le service de passerelle d'API enregistre la région associée à jdoe en tant que paramètre d'authentification. La définition d'élément dorsal HTTP spécifie que les utilisateurs finaux ayant l'étendue d'accès "weatherwatcher" ont accès à l'élément dorsal HTTP. Le service de passerelle d'API utilise la valeur de la variable de contexte du paramètre d'authentification request.auth[region] dans la demande. La demande est résolue à https://api.weather.gov/west.

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

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

Cet exemple utilise les variables suivantes dans la définition d'élément dorsal 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 et indique la valeur de la version encodée par Base64 du certificat TLS présentée par le client d'API lors de l'établissement d'une liaison mTLS avec la passerelle d'API.