Política JavaScript

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

La política de JavaScript te permite agregar código JavaScript personalizado que se ejecuta en el contexto del flujo del proxy de API. Esta política te permite implementar un comportamiento personalizado que las políticas de Apigee no cubren de otra manera.

En tu código de JavaScript personalizado, puedes usar los objetos, los métodos y las propiedades del modelo de objetos de JavaScript de Apigee. Puedes obtener, establecer y quitar variables en el contexto del flujo del proxy, ejecutar lógica personalizada, realizar un control de fallas, extraer datos de solicitudes o respuestas y editar de forma dinámica la URL de destino del backend. También puedes usar funciones criptográficas básicas que están disponibles en el modelo de objetos.

La política de JavaScript te permite especificar un archivo fuente de JavaScript para ejecutar. También puedes incluir el código de JavaScript directamente en la configuración de la política con el elemento <Source>. De cualquier manera, el código de JavaScript se ejecuta cuando se ejecuta el paso al que se adjunta la política.

Para la opción de archivo fuente, el código fuente siempre se almacena en una ubicación estándar dentro del paquete de proxy: apiproxy/resources/jsc. También puedes almacenar el código fuente en un archivo de recursos a nivel de la organización o el entorno. Para obtener instrucciones, consulta Archivos de recursos. También puedes subir JavaScript con el editor de proxy de la IU de Apigee.

Apigee no recomienda usar la política de JavaScript para lo siguiente:

• Registros: La política MessageLogging es más adecuada para el registro con plataformas de registro de terceros, como Splunk, Sumo y Loggly. Esta política también mejora el rendimiento del proxy de API, ya que se ejecuta en el PostClientFlow después de que la respuesta se muestra al cliente.
• Reemplazo de políticas de Apigee. La política de JavaScript no reemplaza las capacidades de las políticas de Apigee. Si las capacidades que necesitas están disponibles en una política de Apigee, usa esa política en lugar de implementar una solución personalizada de JavaScript. Es posible que el código de JavaScript personalizado no coincida con el rendimiento y la optimización de las políticas de Apigee.

Los archivos fuente de JavaScript deben tener una extensión .js.

Apigee admite JavaScript que se ejecuta en el motor JavaScript Rhino 1.7.13.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Muestras

Reescribe la URL de destino

Un caso de uso común implica extraer datos del cuerpo de una solicitud, almacenarlos en una variable de flujo y, luego, usar esa variable de flujo en otra parte del flujo del proxy. Por ejemplo, supongamos que un usuario ingresa su nombre en un formulario HTML y lo envía. Para extraer los datos del formulario y agregarlos de forma dinámica a la URL del servicio de backend, usa una política de JavaScript.

Nota: Para probar este ejemplo, crea un proxy nuevo en el editor de proxy. Cuando crees el proxy, proporciona una URL del servicio de backend, por ejemplo, http://www.example.com. En este ejemplo, se reescribe de forma dinámica la URL de backend. Si necesitas crear un proxy nuevo, consulta el instructivo de introducción.

1. En la IU de Apigee, abre el proxy que creaste en el editor de proxy.
2. Selecciona la pestaña Desarrollar.
3. En el menú Nueva, seleccione Nueva secuencia de comandos.
4. En el cuadro de diálogo, selecciona JavaScript y asígnale el nombre js-example a la secuencia de comandos.
5. Pega el siguiente código en el editor de código y guarda el proxy. El objeto context está disponible para el código JavaScript en cualquier parte del flujo del proxy. Obtiene constantes específicas del flujo, llama a métodos get/set útiles y realiza otras operaciones. Este objeto forma parte del modelo de objetos de JavaScript de Apigee. La variable de flujo target.url es una variable integrada de lectura y escritura a la que se puede acceder en el flujo de solicitud de destino. Cuando estableces esa variable con la URL de la API, Apigee llama a esa URL de backend. Esto reescribe la URL de destino original, que era la URL que especificaste cuando creaste el proxy (por ejemplo, http://www.example.com).

   if (context.flow=="PROXY_REQ_FLOW") {
        var username = context.getVariable("request.formparam.user");
        context.setVariable("info.username", username);
   }
   
   
   if (context.flow=="TARGET_REQ_FLOW") {
        context.setVariable("request.verb", "GET");
        var name = context.getVariable("info.username");
        var url = "http://mocktarget.apigee.net/"
        context.setVariable("target.url", url + "?user=" + name);
   }

6. En el menú Nueva política, selecciona JavaScript.
7. Asigna a la política el nombre target-rewrite. Acepta los valores predeterminados y guarda la política.
8. Después de seleccionar Proxy Endpoint Preflow en el Navigator, la política se agrega a ese flujo.
9. En el Navigator, selecciona Target Endpoint PreFlow.
10. En el navegador, arrastra la política de JavaScript al lado de la solicitud del extremo de destino en el editor de flujo.
11. Guardar.
12. Sustituye el nombre de tu organización y el nombre del proxy cuando llames a la API:

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

Examina la definición de XML para la política de JavaScript que se usa en este ejemplo. El elemento <ResourceURL> especifica el archivo fuente de JavaScript que se ejecutará. Este patrón se aplica a cualquier archivo de origen de JavaScript: jsc://filename.js. Si tu código de JavaScript requiere inclusiones, usa uno o más elementos de <IncludeURL>, como se describe más adelante en este documento.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

Recupera el valor de la propiedad de JavaScript

Puedes agregar un elemento <Property> en la configuración y, luego, recuperar su valor con JavaScript en el entorno de ejecución.

Usa el atributo name del elemento para especificar el nombre con el que se accederá a la propiedad desde el código JavaScript. El valor del elemento <Property> (el valor entre las etiquetas de apertura y cierre) es el valor literal que recibe JavaScript.

En JavaScript, para recuperar el valor de la propiedad de la política, debes acceder a ella como una propiedad del objeto Properties, como se muestra a continuación:

• Configura la propiedad. El valor de la propiedad es el nombre de variable response.status.code.

  <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite">
      <DisplayName>JavascriptURLRewrite</DisplayName>
      <Properties>
          <Property name="source">response.status.code</Property>
      </Properties>
      <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL>
  </Javascript>

• Recupera la propiedad con JavaScript. Luego, la función getVariable usa el nombre de la variable recuperada para recuperar el valor de la variable.

  var responseCode = properties.source; // Returns "response.status.code"
  var value = context.getVariable(responseCode); // Get the value of response.status.code
  context.setVariable("response.header.x-target-response-code", value);

Maneja los errores

Para ver ejemplos y un análisis de las técnicas de manejo de errores que puedes usar en un texto destacado de JavaScript, consulta Cómo visualizar correctamente los errores de la política de JavaScript. Las sugerencias de la Comunidad de Apigee son solo para fines informativos y no representan necesariamente las prácticas recomendadas de Google.

En una política de JavaScript, el acceso a request.content.asJSON en modo de solo lectura convierte los números enteros grandes en notación exponencial en el cuerpo del mensaje. Esto reemplaza el mensaje con los valores convertidos.

Referencia del elemento

En la referencia del elemento, se describen los elementos y atributos de la política JavaScript.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false"
        continueOnError="false" enabled="true" timeLimit="200"
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>
</Javascript>

Atributos de <JavaScript>

< languageVersion="VERSION_1_3" Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

Atributo	Descripción	Predeterminado	Presencia
languageVersion	Especifica la versión del lenguaje JavaScript en la que se escribió el código. Los valores incluyen VERSION_DEFAULT, VERSION_1_0, VERSION_1_1, VERSION_1_2, VERSION_1_3, VERSION_1_4, VERSION_1_5, VERSION_1_6, VERSION_1_7, VERSION_1_8 y VERSION_ES6.	VERSION_DEFAULT	Opcional
timeLimit	Especifica el tiempo máximo (en milisegundos) que una secuencia de comandos puede ejecutarse. Por ejemplo, si se excede un límite de 200 ms, la política muestra este error: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms. Nota: Para las cuentas de prueba gratuita, el tiempo de ejecución está limitado a 200 ms.	N/A	Obligatorio

En la siguiente tabla, se describen los atributos que son comunes a todos los elementos principales de las políticas:

Atributo	Descripción	Configuración predeterminada	Presence
name	El nombre interno de la política. El valor del atributo name puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.	N/A	Obligatorio
continueOnError	Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas. Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente: Las reglas de fallas se activan SOLAMENTE en un estado de error (sobre el continueOnError) Controla fallas dentro del flujo actual	false	Opcional
enabled	Configúralo como true para aplicar la política. Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.	true	Opcional
async	Este atributo dejó de estar disponible.	false	Obsoleto

Elemento <DisplayName>

Se usan además del atributo name para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Configuración predeterminada	N/A Si omites este elemento, se usa el valor del atributo name de la política.
Presence	Opcional
Tipo	String

Elemento <IncludeURL>

Especifica un archivo de biblioteca de JavaScript que se cargará como dependencia del archivo principal de JavaScript especificado con el elemento <ResourceURL> o <Source>. La política evalúa las secuencias de comandos en el orden en que se incluyen en ella. Tu código puede usar los objetos, los métodos y las propiedades del modelo de objetos de JavaScript.

Incluye más de un recurso de dependencia de JavaScript con elementos <IncludeURL> adicionales.

Advertencia: Si tus archivos de JavaScript se almacenan a nivel del proxy o del entorno, asegúrate de subirlos correctamente con cURL usando la opción -F o como un archivo adjunto a través de un cliente REST. El Content-Type es multipart/form-data. Para obtener más información, consulta Administra recursos.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

Predeterminado:	Ninguno
Presencia:	Opcional
Tipo:	String

Elemento <Property>

Especifica una propiedad a la que puedes acceder desde el código JavaScript en el entorno de ejecución.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Predeterminado:	Ninguno
Presencia:	Opcional
Tipo:	String

Atributos

Atributo	Descripción	Predeterminado	Presencia
name	Especifica el nombre de la propiedad.	N/A	Obligatorio

Ejemplo

Consulta el ejemplo básico en la sección Muestras.

Elemento <ResourceURL>

Especifica el archivo JavaScript principal que se ejecuta en el flujo de la API. Puedes almacenar este archivo en el permiso del proxy de API (en /apiproxy/resources/jsc en el paquete del proxy de API o en la sección Secuencias de comandos del panel Navegador del editor de proxy de API). Como alternativa, puedes almacenarlo en los permisos de la organización o del entorno para volver a utilizarse en múltiples proxies de API, como se describe en Administra recursos. Tu código puede usar los objetos, los métodos y las propiedades del modelo de objetos de JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

Predeterminado:	Ninguno
Presencia:	Se requiere <ResourceURL> o <Source>. Si están presentes <ResourceURL> y <Source>, la política ignora <ResourceURL>.
Tipo:	String

Ejemplo

Consulta el ejemplo básico en la sección Muestras.

Elemento <Source>

Puedes insertar JavaScript directamente en la configuración XML de la política. El código de JavaScript insertado se ejecuta cuando la política se ejecuta en el flujo de API.

Predeterminado:	Ninguno
Presencia:	Se requiere <ResourceURL> o <Source>. Si están presentes <ResourceURL> y <Source>, la política ignora <ResourceURL>.
Tipo:	String

Ejemplo

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

Elemento <SSLInfo>

Especifica las propiedades que se usan a fin de configurar TLS para todas las instancias HTTP de cliente que creó la política de JavaScript.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

Predeterminado:	Ninguno
Presencia:	Opcional
Tipo:	String

El proceso de configuración de TLS para un cliente HTTP es el mismo que se usa para configurar TLS para un TargetEndpoint o TargetServer. Si deseas obtener más información, consulta Opciones para configurar TLS.

Notas de uso

Advertencia:El modelo de seguridad no permite las llamadas al sistema. Por ejemplo, no se permiten las operaciones de lectura o escritura internas del sistema de archivos, la información del usuario actual, las listas de procesos ni el uso de CPU o memoria. Si bien algunas llamadas pueden ser funcionales, no son compatibles y están sujetas a la inhabilitación activa en cualquier momento. Para garantizar la compatibilidad con versiones futuras, evita realizar este tipo de llamadas en tu código.

Depura el código de política de JavaScript

Usa la función print() para enviar información de depuración al panel de resultados de la transacción en la herramienta Trace. Para obtener detalles y ejemplos, consulta Cómo depurar JavaScript con declaraciones de print().

Para ver las instrucciones de impresión en la herramienta de Debug, haz lo siguiente:

1. Abre la herramienta de depuración y, luego, inicia una sesión de seguimiento para un proxy que contenga tu política de JavaScript.
2. Llama al proxy.
3. En la herramienta Debug, haz clic en Resultado de todas las transacciones para abrir el panel de resultados.

   

4. Tus declaraciones print aparecerán en este panel.

Variables de flujo

Esta política no propaga ninguna variable de forma predeterminada. Sin embargo, puedes establecer y obtener variables de flujo en tu código JavaScript llamando a métodos en el objeto context. Por ejemplo:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

El objeto context forma parte del modelo de objetos de JavaScript de Apigee.

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee cuando esta política activa un error. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Lo que necesitas saber sobre errores de políticas y Controla fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Corregir para obtener información detallada sobre la solución de problemas.

Código de falla	Estado de HTTP	Causa	Corregir
steps.javascript.ScriptExecutionFailed	500	La política JavaScript puede generar muchos tipos de errores ScriptExecutionFailed. Los tipos de errores más comunes que aparecen son RangeError, ReferenceError, SyntaxError, TypeError y URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	Se produjo un error en el código JavaScript. Consulta la string con error para obtener más detalles.	N/A
steps.javascript.ScriptSecurityError	500	Se produjo un error de seguridad cuando se ejecutó JavaScript. Consulta la string con error para obtener más detalles.	N/A

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Sugerencia: ¿Necesitas ayuda para resolver un error? Haz clic en junto a la descripción de la causa del error para ver la página de solución de problemas.

Nombre del error	Causa	Corregir
InvalidResourceUrlFormat	Si el formato de la URL del recurso especificado en elemento <ResourceURL> o <IncludeURL> de la política de JavaScript no es válido, la implementación del proxy de la API falla.
InvalidResourceUrlReference	Si los elementos <ResourceURL> o <IncludeURL> hacen referencia a un archivo de JavaScript que no existe, la implementación del proxy de API falla. El archivo de origen al que se hace referencia debe existir a nivel de proxy de API, entorno u organización.
WrongResourceType	Este error ocurre durante la implementación si los elementos <ResourceURL> o <IncludeURL> de la política JavaScript hacen referencia a cualquier tipo de recurso que no sea jsc (archivo JavaScript).
NoResourceURLOrSource	La implementación de la política de JavaScript puede fallar con este error si no se declara el elemento <ResourceURL> o si la URL del recurso no se define dentro de este elemento. El elemento <ResourceURL> es obligatorio. El elemento <IncludeURL> se declara, pero la URL del recurso no se define dentro de este elemento. El elemento <IncludeURL> es opcional, pero si se declara, la URL del recurso se debe especificar dentro del elemento <IncludeURL>.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables	Donde	Ejemplo
fault.name="fault_name"	fault_name es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed	policy_name es el nombre especificado por el usuario de la política que generó la falla.	javascript.JavaScript-1.failed = true

Ejemplo de respuesta de error

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Ejemplo de regla de falla

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

Esquema

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Temas relacionados

• Modelo de objetos de JavaScript

Artículos de la comunidad de Apigee

Puedes encontrar estos artículos relacionados en la Comunidad de Apigee:

• Cómo controlar encabezados de valores múltiples en JavaScript