Ejemplos de transformación
Utilice ejemplos para aprender a modificar las solicitudes entrantes y las respuestas salientes que se envían desde y hacia los servicios backend con API Gateway.
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"
},
"requestPolicies": {}
}
]
},
"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: transformación de parámetros de cabecera en parámetros de consulta
En este ejemplo, supongamos que un backend HTTP existente solo maneja solicitudes que contienen parámetros de consulta, no parámetros de cabecera. Sin embargo, desea que el backend HTTP maneje solicitudes que incluyen parámetros de cabecera. Para ello, cree una especificación de despliegue de API que incluya una política de solicitud de transformación de parámetros de consulta para transferir el valor obtenido de una cabecera de solicitud al backend HTTP como parámetro de consulta.
"requestPolicies": {
"queryParameterTransformations": {
"setQueryParameters": {
"items": [
{
"name": "region",
"values": ["${request.headers[region]}"],
"ifExists": "OVERWRITE"
}
]
}
}
}En este ejemplo, una solicitud como curl -H "region: west" https://<gateway-hostname>/marketing/weather se resuelve en https://api.weather.gov?region=west.
Ejemplo 2: transformación de una cabecera en otra
En este ejemplo, supongamos que un backend HTTP existente solo maneja solicitudes que contienen una cabecera concreta. Sin embargo, desea que el backend HTTP maneje solicitudes que incluyen una cabecera diferente. Para lograrlo, cree una especificación de despliegue de API que incluya una política de solicitud de transformación de cabecera para adoptar el valor obtenido de una cabecera de solicitud y transferirla al backend HTTP como una cabecera de solicitud diferente.
"requestPolicies": {
"headerTransformations": {
"setHeaders": {
"items": [
{
"name": "region",
"values": ["${request.headers[locale]}"],
"ifExists": "OVERWRITE"
}
]
}
}
}En este ejemplo, una solicitud como curl -H "locale: west" https://<gateway-hostname>/marketing/weather se resuelve en la solicitud curl -H "region: west" https://api.weather.gov.
Ejemplo 3: agregación de un parámetro de autenticación obtenido de un JWT como cabecera de solicitud
En este ejemplo, supongamos que un backend HTTP existente requiere que el valor de la reclamación sub en un token web JSON (JWT) validado se incluya en una solicitud como cabecera con el nombre JWT_SUBJECT. El servicio de gateway de API ha guardado el valor de la reclamación sub incluida en el JWT como parámetro de autenticación en la tabla request.auth.
Para incluir el valor sub en una cabecera denominada JWT_SUBJECT, cree una especificación de despliegue de API que incluya una política de solicitud de transformación de cabecera. La política de solicitud obtiene el valor sub de la tabla request.auth y lo transfiere al backend HTTP como valor de la cabecera JWT_SUBJECT.
"requestPolicies": {
"headerTransformations": {
"setHeaders": {
"items": [
{
"name": "JWT_SUBJECT",
"values": ["${request.auth[sub]}"],
"ifExists": "OVERWRITE"
}
]
}
}
}En este ejemplo, cuando una solicitud se ha validado correctamente, la cabecera JWT_SUBJECT se agrega a la solicitud transferida al backend HTTP.
Ejemplo 4: agregación de una clave obtenida de una función de autorizador como parámetro de consulta
En este ejemplo, supongamos que un backend HTTP existente requiere que las solicitudes incluyan un parámetro de consulta denominado access_key con fines de autenticación. Desea que el parámetro de consulta access_key tenga el valor de una clave denominada apiKey que ha devuelto una función de autorizador que ha validado correctamente la solicitud. El servicio de gateway de API ha guardado el valor apiKey como parámetro de autenticación en la tabla request.auth.
Para incluir el parámetro de consulta access_key en la solicitud, cree una especificación de despliegue de API que incluya una política de solicitud de transformación de parámetros de consulta. La política de solicitud obtiene el valor apiKey de la tabla request.auth y lo transfiere al backend HTTP como valor del parámetro de consulta access_key.
"requestPolicies": {
"queryParameterTransformations": {
"setQueryParameters": {
"items": [
{
"name": "access_key",
"values": ["${request.auth[apiKey]}"],
"ifExists": "OVERWRITE"
}
]
}
}
}En este ejemplo, el parámetro de consulta access_key se agrega a la solicitud transferida al backend HTTP, con el valor apiKey de la tabla request.auth. Una solicitud como https://<gateway-hostname>/marketing/weather se resuelve en una solicitud como https://api.weather.gov?access_key=fw5n9abi0ep
Ejemplo 5: agregación de un valor por defecto para un parámetro de consulta opcional
En este ejemplo, supongamos que un backend HTTP existente requiere que las solicitudes incluyan un parámetro de consulta denominado country. Sin embargo, el parámetro de consulta country es opcional y no lo incluyen algunas de las solicitudes de envío de clientes de API. Si una solicitud ya incluye un parámetro de consulta country y un valor, desea que ambos se transfieran tal como están al backend HTTP. Sin embargo, si una solicitud aún no incluye un parámetro de consulta country, desea agregar el parámetro de consulta country y un valor por defecto a la solicitud.
Para asegurarse de que cada solicitud incluye un parámetro de consulta country, cree una especificación de despliegue de API que incluya una política de solicitud de transformación de parámetros de consulta. La política de solicitud agrega el parámetro de consulta country y un valor por defecto a cualquier solicitud que aún no incluya el parámetro de consulta country.
"requestPolicies": {
"queryParameterTransformations": {
"setQueryParameters": {
"items": [
{
"name": "country",
"values": ["usa"],
"ifExists": "SKIP"
}
]
}
}
}En este ejemplo, una solicitud como https://<gateway-hostname>/marketing/weather se resuelve en https://api.weather.gov?country=usa. Una solicitud como https://<gateway-hostname>/marketing/weather?country=canada se resuelve en https://api.weather.gov?country=canada.