Documentación de Oracle Cloud Infrastructure

Agregación de variables de contexto a políticas y definiciones de backend HTTP

Descubra cómo utilizar parámetros en llamadas de API mediante variables de contexto de API Gateway.

Las llamadas a las API desplegadas en un gateway de API suelen incluir parámetros que deseará utilizar al definir los siguientes elementos en especificaciones de despliegue de API:

  • políticas de solicitud y políticas de respuesta
  • backends HTTP y HTTPS

Para que pueda utilizar los parámetros incluidos en llamadas de API, el servicio de gateway de API guarda los valores de los siguientes tipos de parámetros en 'tablas de contexto' temporales:

Cada registro de una tabla de contexto se identifica mediante una clave única.

Al definir las políticas de solicitud y respuesta, y backends HTTP y HTTPS, puede hacer referencia al valor de un parámetro en una tabla de contexto mediante una 'variable de contexto'. Una variable de contexto tiene el formato <context-table-name>[<key>] donde:

  • <context-table-name> es uno de los siguientes: request.path, request.query, request.headers, request.auth, request.cert o request.host
  • <key> es uno de los siguientes elementos:
    • nombre de parámetro de ruta de acceso definido en la especificación de despliegue de API
    • nombre de parámetro de consulta incluido en la solicitud para la API
    • nombre de cabecera incluido en la solicitud para la API
    • un nombre de parámetro de autenticación devuelto por una función de autorizador o contenido en un token JWT
    • el nombre [client_base64], que representa un certificado validado correctamente codificado con Base64 presentado por un cliente de API durante un establecimiento de comunicación mTLS
    • la parte final del nombre de host que se debe ignorar (al capturar la parte inicial del nombre de host al que se envió la solicitud original)
    • el nombre de un host al que se ha enviado la solicitud (extraído del campo de cabecera Host de la solicitud)

Si desea incluir la variable de contexto en una cadena de la especificación de despliegue de API (por ejemplo, en la propiedad de URL de una definición de backend HTTP), utilice el formato ${<context-table-name>[<key>]}.

Por ejemplo, la variable de contexto request.path[region] del siguiente ejemplo devuelve el valor del registro identificado por la clave region en la tabla de contexto request.path.

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

Tenga en cuenta que:

  • En la tabla de contexto, se crea un único registro para cada parámetro discreto de una solicitud HTTP. Si la solicitud HTTP incluye dos (o más) parámetros del mismo tipo y con el mismo nombre, el valor de cada parámetro con ese nombre se guarda en el mismo registro en la tabla de contexto y se identifica con la misma clave. Sin embargo, solo el primer valor del registro de tabla de contexto se puede sustituir en lugar de una variable de contexto. Si va a agregar una variable de contexto para la que pueden existir varios valores en el registro de tabla de contexto y desea que el primer valor del registro de tabla de contexto se sustituya en lugar de la variable de contexto, debe agregar la variable de contexto a la especificación de despliegue de API con el formato ${<context-table-name>[<key>]}
  • Si un valor de parámetro incluye caracteres especiales que se han codificado, la codificación se mantiene al guardar el valor en la tabla de contexto. Si el valor se sustituye por una variable de contexto, el valor codificado se sustituye en lugar de la variable de contexto. Por ejemplo, si San José se incluye en un parámetro de consulta como San+Jos&#233;, la versión codificada es lo que se sustituirá en lugar de la variable de contexto de ese parámetro de consulta.
  • Si una clave de variable de contexto no existe en la tabla de contexto especificada, se sustituye una cadena vacía en lugar de la variable de contexto.
  • Si una clave de variable de contexto contiene un punto, el punto se trata como cualquier otro carácter. No se trata como un indicador de una relación principal-secundario entre las cadenas a ambos lados.
  • Si un parámetro de ruta de acceso incluye un comodín (por ejemplo, generic_welcome*), el parámetro de ruta de acceso sin el comodín se utiliza como clave.

  • Puede incluir una variable de contexto como segmento de ruta de acceso en la propiedad de URL de una definición de backend HTTP, pero no como parámetro de consulta. Por ejemplo:

    • Puede utilizar la variable de contexto request.query[state] como segmento de ruta de acceso en la propiedad de URL, como se muestra en la siguiente definición de backend HTTP válida: 

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

    • No puede utilizar la variable de contexto request.query[state] como parámetro de consulta en la propiedad de URL, como se muestra en la siguiente definición de backend HTTP no válida: 

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

    Si desea transferir una variable de contexto como parámetro de consulta, utilice una política de solicitud de transformación de parámetro de consulta en lugar de incluir la variable de contexto como parámetro de consulta en la propiedad URL (consulte Adición de Políticas de Solicitud de Transformación de Parámetros de Consulta).

Ejemplos

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 básico en un archivo 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": {}
}

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: parámetro de ruta de acceso de consulta en una definición

Puede definir un parámetro de ruta de acceso en la especificación de despliegue de API y, a continuación, utilizarlo en otra parte de la especificación de despliegue de API como una variable de contexto.

En este ejemplo se crea un parámetro de ruta de acceso region, que se utiliza en una variable de contexto request.path[region] en la definición de backend HTTP.

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

En este ejemplo, una solicitud como https://<gateway-hostname>/marketing/weather/west se resuelve en https://api.weather.gov/west.

Ejemplo 2: diferentes tipos de variable de contexto en la misma definición

Puede incluir distintos tipos de variable de contexto en la misma definición de la especificación de despliegue de API.

En este ejemplo se utilizan los siguientes elementos en la definición de backend HTTP:

  • una variable de contexto de parámetro de ruta de acceso, request.path[region]
  • una variable de contexto de parámetro de consulta, request.query[state]
      {
        "path": "/weather/{region}",
        "methods": ["GET"],
        "backend": {
          "type": "HTTP_BACKEND",
          "url": "https://api.weather.gov/${request.path[region]}/${request.query[state]}"
        }
      }

En este ejemplo, una solicitud como https://<gateway-hostname>/marketing/weather/west?state=california se resuelve en https://api.weather.gov/west/california.

Ejemplo 3: diversas variables de contexto del mismo tipo en la misma definición

Puede incluir el mismo tipo de variable de contexto varias veces en la misma definición.

En este ejemplo se utilizan los siguientes elementos en la definición de backend HTTP:

  • una variable de contexto de parámetro de ruta de acceso, request.path[region]
  • dos variables de contexto de parámetro de consulta, request.query[state] y 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]}"
        }
      }

En este ejemplo, una solicitud como https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont se resuelve en https://api.weather.gov/west/california/fremont.

Ejemplo 4: varios valores para el mismo parámetro

Normalmente es válido que una solicitud HTTP incluya el mismo parámetro de consulta varias veces. El servicio de gateway de API guarda el valor de cada parámetro con el mismo nombre en el mismo registro de la tabla de contexto. Sin embargo, en la especificación de despliegue de API, normalmente solo un único valor se puede sustituir por una variable de contexto. En estas situaciones, puede indicar que solo el primer valor registrado en la tabla de contexto para una clave se sustituye en lugar de una variable de contexto delimitando la variable de contexto en ${...}.

Por ejemplo, una solicitud válida como "https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont&city=belmont" tiene dos incidencias del parámetro de consulta city. Al recibir la solicitud HTTP, el servicio de gateway de API escribe ambos valores del parámetro de consulta city (fremont y belmont) en el mismo registro de la tabla request.query. Si la definición de un backend HTTP incluye ${request.query[city]}, solo se sustituye el primer valor del registro en lugar de la variable de contexto.

En este ejemplo se utilizan los siguientes elementos en la definición de backend HTTP:

  • una variable de contexto de parámetro de ruta de acceso, request.path[region]
  • dos variables de contexto de parámetro de consulta, request.query[state] y 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]}"
        }
      }

En este ejemplo, una solicitud como https://<gateway-hostname>/marketing/weather/west?state=california&city=fremont&city=belmont se resuelve en https://api.weather.gov/west/california/fremont. Tenga en cuenta que solo fremont (como el primer valor del registro de tabla de contexto request.query identificado por la clave city) se sustituye para la variable de contexto request.query[city].

Ejemplo 5: el valor de parámetro incluye caracteres especiales codificados

Si una solicitud HTTP incluye caracteres especiales (por ejemplo, el carácter é o el espacio) que se han codificado, el valor se almacena en la tabla de contexto con su formato codificado. Si el valor de la tabla de contexto se sustituye por una variable de contexto, la codificación se mantiene.

En este ejemplo se utilizan los siguientes elementos en la definición de backend HTTP:

  • una variable de contexto de parámetro de ruta de acceso, request.path[region]
  • una variable de contexto de parámetro de consulta, 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]}"
        }
      }

En este ejemplo, una solicitud como https://<gateway-hostname>/marketing/weather/west?city=San+Jos&#233; se resuelve en https://api.weather.gov/west/california/San+Jos&#233;.

Ejemplo 6: parámetros de cabecera en una definición

Puede incluir los valores transferidos en las cabeceras de una solicitud como variables de contexto en una definición. Si la solicitud incluye una cabecera, el valor de la cabecera se almacena en la tabla request.headers y el nombre de la cabecera se utiliza como clave.

En este ejemplo se utilizan los siguientes elementos en la definición de backend HTTP:

  • una variable de contexto de parámetro de ruta de acceso, request.path[region]
  • una variable de contexto de parámetro de cabecera, 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]}"
        }
      }

En este ejemplo, una solicitud como https://<gateway-hostname>/marketing/weather/west incluía una cabecera X-Api-Key con el valor abc123def456fhi789. La solicitud se resuelve en https://api.weather.gov/west/abc123def456fhi789.

Ejemplo 7: Parámetros de autenticación en una definición

Puede incluir valores devueltos de una función de autorizador o contenidos en un token JWT como variables de contexto en una definición:

  • Una función de autorizador valida el token transferido por un cliente de API al llamar al servicio de gateway de API. La función de autorizador devuelve una respuesta que incluye información como la validez de la autorización, información sobre el usuario final, el ámbito de acceso y una serie de reclamaciones en pares de clave-valor. Según el token de autorización, la información puede estar contenida en el token o la función de autorizador puede llamar a los puntos finales proporcionados por el servidor de autorización para validar el token y recuperar información sobre el usuario final. Cuando el servicio de gateway de API recibe un par clave-valor de la función de autorizador, guarda el par clave-valor en la tabla request.auth como un parámetro de autenticación.
  • Un token JWT puede incluir opcionalmente una reclamación personalizada denominada scope, que comprende un par de clave-valor. Cuando se ha validado el token JWT, el servicio de gateway de API guarda el par de clave-valor en la tabla request.auth como parámetro de autenticación.

    En el caso del flujo de autorización de Connect OpenID, se devuelven dos tokens denominados id_token (siempre con codificación JWT) y access_token (se puede codificar JWT). El servicio de gateway de API guarda los valores de token en las variables de contexto request.auth[id_token] y request.auth[access_token], junto con las reclamaciones personalizadas en las variables de contexto request.auth[id_token_claims][<claim-name>] y request.auth[access_token_claims][<claim-name>] respectivamente.

En este ejemplo se utiliza el par clave-valor devuelto por una función de autorizador como la variable de contexto del parámetro de autenticación request.auth[region] en la definición de backend 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" ]
          }
        }
      }
    ]
  }

Supongamos que una función de autorizador ocid1.fnfunc.oc1.phx.aaaaaaaaac2______kg6fq valida el token transferido por un cliente de API en una llamada al servicio de gateway de API. La función de autorizador devuelve una respuesta al servicio de gateway de API que incluye la región asociada al usuario final como par clave-valor y también el ámbito de acceso del usuario final autenticado. Cuando el servicio de gateway de API recibe el par clave-valor, lo guarda en la tabla request.auth como un parámetro de autenticación.

En este ejemplo, un usuario final jdoe realiza una solicitud como https://<gateway-hostname>/marketing/weather mediante un cliente de API. La función de autorizador valida el token transferido por el cliente de API en la solicitud y también determina que jdoe tiene el ámbito de acceso "weatherwatcher". La función de autorizador identifica que jdoe está asociado a la región oeste. La función de autorizador devuelve el ámbito de acceso de jdoe al servicio de gateway de API junto con la región asociada a jdoe. El servicio de gateway de API guarda la región asociada a jdoe como un parámetro de autenticación. La definición de backend HTTP especifica que los usuarios finales con el ámbito de acceso "weatherwatcher" pueden acceder al backend HTTP. El servicio API Gateway utiliza el valor de la variable de contexto del parámetro de autenticación request.auth[region] en la solicitud. La solicitud se resuelve en https://api.weather.gov/west.

Ejemplo 8: parámetro de certificado TLS en una definición

Puede incluir una versión codificada por Base64 del certificado TLS presentado por un cliente de API durante un establecimiento de comunicación de mTLS como variable de contexto en una definición. La versión codificada por Base64 del certificado TLS se almacena en la tabla request.cert, con el nombre client_base64 utilizado como clave. Consulte Adición de soporte de mTLS a despliegues de API.

En este ejemplo se utilizan los siguientes elementos en la definición de backend HTTP:

  • la variable de contexto del certificado, 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]}"]
                }
              ]
            }
          }
        }
      }
    ]
  }

En este ejemplo, se agrega una cabecera denominada certificate-header a la solicitud y se le asigna el valor de la versión codificada Base64 del certificado TLS presentado por el cliente de API durante el establecimiento de comunicación mTLS con el gateway de API.