Estás consultando la documentación de Apigee Edge.
Consulta la
documentación de Apigee X. Información
En este tema, aprenderás a usar JavaScript para agregar encabezados HTTP de forma dinámica a un mensaje de respuesta y a analizar una respuesta JSON y mostrar un subconjunto de sus propiedades a la app solicitante.
Descarga y prueba el código de muestra
Acerca de este ejemplo de libro de recetas
En este ejemplo de la guía de soluciones, se muestra un patrón de proxy de API en el que se implementa el comportamiento de la API en JavaScript. Los ejemplos de JavaScript están diseñados para mostrarte cómo trabajar con variables simples y contenido de mensajes. En un ejemplo, se muestra cómo obtener y configurar variables. En el segundo ejemplo, se muestra cómo analizar JSON y crear un mensaje a partir del resultado.
Hay dos muestras de JavaScript en el proxy de API:
setHeaders.js: Este JavaScript obtiene los valores de algunas variables que se establecen cuando se invoca un proxy de API. JavaScript agrega esas variables al mensaje de respuesta para que puedas ver sus valores en cada solicitud que realices.minimize.js: Este JavaScript te muestra cómo trabajar con el contenido de los mensajes. La idea detrás de esta muestra es que un servicio suele mostrar más datos de los necesarios. JavaScript analiza el mensaje de respuesta, extrae algunas propiedades interesantes y, luego, las usa para compilar el contenido del mensaje de respuesta.
El código para setHeader.js:
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));
El código para minimize.js:
// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);
// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
state: res.root.state };
// Set the response variable.
context.proxyResponse.content = JSON.stringify(minimizedResponse);
Puedes acceder a las variables de flujo en JavaScript a través del objeto de contexto. Este objeto forma parte del modelo de objetos de Edge de JavaScript. Para obtener detalles sobre el modelo de objetos, consulta Modelo de objetos de JavaScript.
Antes de comenzar
Antes de que explores este ejemplo de la guía de soluciones, también debes estar familiarizado con estos conceptos fundamentales:
- Qué son las políticas y cómo adjuntarlas a los proxies Para obtener una buena introducción a las políticas, consulta ¿Qué es una política?.
- La estructura de un flujo de proxy, como se explica en Configura flujos. Los flujos te permiten especificar la secuencia en la que un proxy de API ejecuta las políticas. En este ejemplo, se crean varias políticas y se agregan a un flujo de proxy de API.
- Cómo se organiza un proyecto de proxy de API en el sistema de archivos, como se explica en la referencia de configuración de proxy de API.
- Conocimientos prácticos de XML, JSON y JavaScript En este ejemplo, debes compilar el proxy de la API y sus políticas con los archivos en formato XML que se encuentran en el sistema de archivos.
Si descargaste el código de muestra, puedes encontrar todos los archivos analizados en este tema en la carpeta de muestra javascript-cookbook. En las siguientes secciones, se analiza el código de muestra en detalle.
Información sobre el flujo del proxy
Para que JavaScript se ejecute en un proxy de API, debes adjuntarlo a un flujo mediante un adjunto de política denominado “Paso”. Una política de tipo JavaScript (mayúsculas de notas) simplemente contiene una referencia al nombre de un archivo JavaScript. Apunta la política a un archivo JavaScript con el elemento ResourceURL.
Por ejemplo, la siguiente política hace referencia al archivo JavaScript llamado setHeader.js.
<Javascript name='setHeaders' timeLimit='200'>
<ResourceURL>setHeaders.js</ResourceURL>
</Javascript>
Puedes adjuntar esta política a un flujo de proxy de API como lo harías con cualquier otro tipo de política. Si adjuntas la política al flujo de proxy de la API, indicarás dónde se debe ejecutar JavaScript. Esto te permite ejecutar JavaScript que interactúa con los mensajes de solicitud o de respuesta a medida que esos mensajes “fluyen” por el proxy de API. En este ejemplo, ambos JavaScript se ejecutan en el flujo de respuesta, ya que las políticas hacen dos cosas: establecer encabezados HTTP en el mensaje de respuesta y “minimizar” el mensaje de respuesta que Apigee Edge muestra a la app solicitante.
Si abres esta configuración de flujo en la IU de administración, verás la configuración de flujo a continuación.
Selecciona Proxy Endpoints > default > PostFlow en el panel Navigator.
A continuación, se muestra la configuración XML correspondiente para el ProxyEndpoint denominado “default”.
<ProxyEndpoint name="default">
<PostFlow>
<Response>
<!-- Steps reference policies under /apiproxy/policies -->
<!-- First, set a few HTTP headers with variables for this transaction. -->
<Step><Name>setHeaders</Name></Step>
<!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
<Step><Name>transform</Name></Step>
<!-- Finally, use JavaScript to create minimized response with just city and state. -->
<Step><Name>minimize</Name></Step>
</Response>
</PostFlow>
<HTTPProxyConnection>
<!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
<BasePath>/javascript-cookbook</BasePath>
<!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
<VirtualHost>default</VirtualHost>
</HTTPProxyConnection>
<RouteRule name="default">
<TargetEndpoint>default</TargetEndpoint>
</RouteRule>
</ProxyEndpoint>
Este es un resumen de los elementos del flujo.
- <Request>: El elemento <Request> consta de varios elementos <Step>. En cada paso, se llama a una de las políticas que creas en el resto de este tema. Estas políticas adjuntan un código JavaScript al flujo de proxy de API, y la ubicación del adjunto de política determina cuándo se ejecuta JavaScript.
- <Response>: El elemento <Response> también incluye <Steps>. Estos pasos también llaman a las políticas que son responsables de procesar la respuesta final desde el destino (que, en este ejemplo, es el destino del servicio simulado de Apigee; observa la configuración de HTTPTargetConnection en
/apiproxy/targets/default.xml). - <HTTPProxyConnection>: Especifica el host y la ruta de acceso del URI que definen la dirección de red que las apps llaman para consumir esta API.
- <RouteRule>: Este elemento especifica qué configuración de TargetEndpoint invoca el ProxyEndpoint.
Agrega código de JavaScript a un proxy
JavaScript (como las secuencias de comandos de Python, los archivos JAR de Java y los archivos XSLT, entre otros) se almacena como recursos. Cuando recién comienzas a trabajar con JavaScript, es más fácil almacenar tus archivos JavaScript en el proxy de API. A medida que avances, JavaScript debe ser lo más genérico y reutilizable posible y, luego, almacenarse en el nivel del entorno o de la organización. De esta manera, no tendrás que almacenar los mismos archivos JavaScript en varios proxies de API, lo que puede volverse rápidamente inmanejable.
Para obtener información sobre el almacenamiento de recursos a nivel de organización y entorno, consulta Archivos de recursos.
Probar
Para obtener instrucciones sobre cómo implementar y llamar al proxy, consulta el archivo README de la guía de soluciones de JavaScript.
Importa e implementa el proxy de API
Después de realizar los cambios, puedes guardar el proxy de API en la herramienta del compilador de proxy de API en la IU de administración.
También puedes ejecutar el siguiente comando en el directorio /api-platform-samples/doc-samples/javascript-cookbook.
$ sh deploy.sh
Cómo probar JavaScript
Ejecuta el siguiente comando en el directorio /api-platform-samples/doc-samples/javascript-cookbook.
$ sh invoke.sh
La marca curl -v se usa en la secuencia de comandos de shell para ver los encabezados HTTP en el mensaje de respuesta modificado por JavaScript.
Puedes enviar una solicitud directamente de la siguiente manera:
$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook
Si el código JavaScript se ejecuta correctamente, verás una respuesta como la siguiente:
< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
{"city":"San Jose","state":"CA"}
Ahora puedes modificar el código JavaScript para probar cosas nuevas, volver a implementar el proxy de API y verificar los resultados enviando la misma solicitud. Siempre asegúrate de implementar el proxy de API que contiene tu código JavaScript para que se apliquen los cambios.
Errores de secuencia de comandos
Inevitablemente, aparecerán errores cuando escribas JavaScript. A continuación, se muestra el formato de los errores de JavaScript que verás emitidos por un proxy de API.
{
"fault":{
"faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
"detail":{
"errorcode":"steps.javascript.ScriptExecutionFailed"
}
}
}
Cuándo usar JavaScript
En Apigee Edge, suele haber más de una forma de implementar funcionalidades específicas. Usa políticas listas para usar siempre que sea posible y evita la tentación de codificar toda la lógica de proxy de tu API en JavaScript. Aunque Apigee Edge aprovecha JavaScript compilado para mejorar el rendimiento, es poco probable que JavaScript funcione tan bien como las políticas. JavaScript puede ser más difícil de mantener y depurar. Reserva JavaScript para una funcionalidad única según tus requisitos.
Si el rendimiento es motivo de preocupación para la funcionalidad personalizada, usa Java siempre que sea posible.
Resumen
En este tema de la guía de soluciones, aprendiste cómo se puede incluir JavaScript en una configuración de proxy de API para implementar un comportamiento personalizado. El comportamiento personalizado que implementan las muestras demuestra cómo obtener variables y cómo analizar JSON y crear mensajes de respuesta personalizados.