Política de JavaScript

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

Consulta la documentación de Apigee Edge.

Qué

Esta política te permite añadir código JavaScript personalizado que se ejecuta en el contexto de un flujo de proxy de API. En tu código JavaScript personalizado, puedes usar los objetos, los métodos y las propiedades del modelo de objetos de JavaScript de Apigee. El modelo de objeto le permite obtener, definir y eliminar variables en el contexto del flujo del proxy. También puedes usar funciones criptográficas básicas que se proporcionan con el modelo de objetos.

Esta política es una política extensible y su uso puede tener implicaciones en cuanto a costes o utilización, en función de tu licencia de Apigee. Para obtener información sobre los tipos de políticas y las implicaciones de uso, consulta Tipos de políticas.

Información

La política de JavaScript se puede usar en muchos casos. Por ejemplo, puedes obtener y definir variables de flujo, ejecutar lógica personalizada y gestionar errores, extraer datos de solicitudes o respuestas, editar dinámicamente la URL de destino del backend y mucho más. Esta política le permite implementar un comportamiento personalizado que no esté cubierto por ninguna otra política estándar de Apigee. De hecho, puedes usar una política de JavaScript para conseguir muchos de los mismos comportamientos que se implementan con otras políticas, como AssignMessage y ExtractVariable.

Un caso de uso para el que no recomendamos la política de JavaScript es el registro. La política MessageLogging es mucho más adecuada para registrar datos en plataformas de registro de terceros, como Splunk, Sumo y Loggly. Además, puedes mejorar el rendimiento del proxy de API ejecutando la política MessageLogging en PostClientFlow, que se ejecuta después de que se haya enviado la respuesta al cliente.

La política de JavaScript te permite especificar un archivo de origen de JavaScript para ejecutarlo o puedes incluir código JavaScript directamente en la configuración de la política con el elemento <Source>. De cualquier forma, el código JavaScript se ejecuta cuando se ejecuta el paso al que está adjunta la política. En el caso de la opción de archivo de origen, el código fuente siempre se almacena en una ubicación estándar dentro del paquete proxy: apiproxy/resources/jsc. También puedes almacenar el código fuente en un archivo de recursos a nivel de entorno o de organización. Para obtener instrucciones, consulta Archivos de recursos. También puedes subir tu JavaScript a través del editor de proxy de la interfaz de usuario de Apigee.

Los archivos de origen de JavaScript siempre deben tener la extensión .js.

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

Vídeo

Nota: En el siguiente vídeo se muestra el editor de proxy clásico en la interfaz de usuario de Apigee. Apigee va a lanzar una nueva versión del editor de proxies, que tiene un diseño diferente al de la versión clásica que se muestra en el vídeo.

Vea un breve vídeo para aprender a crear una extensión de política personalizada con la política de JavaScript.

Ejemplos

Reescribir la URL de destino

Este es un ejemplo de uso habitual: extraer datos del cuerpo de una solicitud, almacenarlos en una variable de flujo y usar esa variable de flujo en otra parte del flujo del proxy. Supongamos que tienes una aplicación en la que el usuario introduce su nombre en un formulario HTML y lo envía. Quieres que el proxy de API extraiga los datos del formulario y los añada dinámicamente a la URL que se usa para llamar al servicio de backend. ¿Cómo lo harías en una política de JavaScript?

Nota: Si quieres probar este ejemplo, damos por hecho que has creado un nuevo proxy en el editor de proxies. Cuando lo crees, solo tienes que darle una URL de servicio de backend: http://www.example.com. En este ejemplo, vamos a reescribir la URL de backend de forma dinámica. Si no sabes cómo crear un proxy, consulta el tutorial de introducción.

1. En la interfaz de usuario de Apigee, abre el proxy que has creado en el editor de proxies.
2. Selecciona la pestaña Desarrollar.
3. En el menú Nuevo, selecciona Nuevo script.
4. En el cuadro de diálogo, selecciona JavaScript y asigna un nombre a la secuencia de comandos, como js-example.
5. Pega el siguiente código en el editor de código y guarda el proxy. Lo importante es fijarse en el objeto context. Este objeto está disponible para el código JavaScript en cualquier parte del flujo del proxy. Se usa para obtener constantes específicas del flujo, llamar a métodos get/set útiles y para más operaciones. Esta parte del objeto pertenece al modelo de objetos de JavaScript de Apigee. Tenga en cuenta también que 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 definimos esa variable con la URL de la API, Apigee hace su llamada de backend a esa URL. Básicamente, hemos reescrito la URL de destino original, que era la que especificaste al crear 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. Dale un nombre a la política, como target-rewrite. Acepta los valores predeterminados y guarda la política.
8. Si seleccionas Proxy Endpoint Preflow en el navegador, verás que la política se ha añadido a ese flujo.
9. En el navegador, selecciona el icono Target Endpoint PreFlow.
10. En el navegador, arrastra la política de JavaScript al lado de la solicitud del endpoint de destino en el editor de flujo.
11. Guardar.
12. Llama a la API de esta forma, sustituyendo el nombre de tu organización y el nombre del proxy por los correctos:

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

Por último, vamos a ver la definición XML de la política de JavaScript que se usa en este ejemplo. Lo importante es tener en cuenta que el elemento <ResourceURL> se usa para especificar el archivo de origen de JavaScript que se va a ejecutar. Este mismo patrón se usa para cualquier archivo de origen de JavaScript: jsc://filename.js. Si tu código JavaScript requiere inclusiones, puedes usar uno o varios elementos <IncludeURL> para hacerlo, como se describe más adelante en esta referencia.

<?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>

Obtener el valor de una propiedad de JavaScript

Puede añadir un elemento <Property> en la configuración y, a continuación, obtener el valor del elemento con JavaScript en el tiempo 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 recibirá JavaScript.

En JavaScript, puedes obtener el valor de la propiedad de la política accediendo a ella como propiedad del objeto Properties, como se muestra a continuación:

• Configura la propiedad. En este caso, el valor de la propiedad es el nombre de la 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. Aquí, el valor obtenido (un nombre de variable) se usa en la función getVariable para obtener 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);

Gestionar errores

Para ver ejemplos y una explicación de las técnicas de gestión de errores que puede usar en una llamada de JavaScript, consulte Forma correcta de devolver errores desde una política de JavaScript. Las sugerencias que se ofrecen en la comunidad de Apigee son meramente informativas y no representan necesariamente las prácticas recomendadas por Google.

En una política de JavaScript, acceder a request.content.asJSON en modo de solo lectura provoca que los números enteros grandes se conviertan en notación exponencial en el cuerpo del mensaje. Como resultado, el mensaje se sobrescribirá con los valores convertidos.

---

Referencia de elemento

En la referencia de elementos se describen los elementos y atributos de la política de 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 <Javascript>

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

Los siguientes atributos son específicos de esta política.

Atributo	Descripción	Predeterminado	Presencia
timeLimit	Especifica el tiempo máximo (en milisegundos) que se permite que se ejecute la secuencia de comandos. Por ejemplo, si se supera un límite de 200 ms, la política genera este error: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms. Nota: En las cuentas de prueba gratuitas, 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 superiores de la política:

Atributo	Descripción	Predeterminado	Presencia
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. Opcionalmente, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.	N/A	Obligatorio
continueOnError	Asigna el valor false para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor true para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual	falso	Opcional
enabled	Asigna el valor true para aplicar la política. Selecciona false para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.	true	Opcional
async	Este atributo está obsoleto.	falso	Obsoleto

Elemento <DisplayName>

Úsalo junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.

<DisplayName>Policy Display Name</DisplayName>

Predeterminado	N/A Si omite este elemento, se usará el valor del atributo name de la política.
Presencia	Opcional
Tipo	Cadena

Elemento <IncludeURL>

Especifica un archivo de biblioteca de JavaScript que se cargará como dependencia del archivo de JavaScript principal especificado con el elemento <ResourceURL> o <Source>. Las secuencias de comandos se evaluarán en el orden en el que aparezcan en la política. 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 JavaScript están almacenados en el proxy o en el entorno, asegúrate de que se hayan subido correctamente con cURL mediante la opción -F o como archivo adjunto a través de un cliente REST. Content-Type es multipart/form-data. Para obtener más información, consulta el artículo sobre gestión de recursos.

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

Valor predeterminado:	Ninguno
Presencia:	Opcional
Tipo:	Cadena

Ejemplo

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

Elemento <Property>

Especifica una propiedad a la que se puede acceder desde el código JavaScript en el tiempo de ejecución.

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

Valor predeterminado:	Ninguno
Presencia:	Opcional
Tipo:	Cadena

Atributos

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

Ejemplo

Consulta el ejemplo de la sección Ejemplos.

Elemento <ResourceURL>

Especifica el archivo JavaScript principal que se ejecutará en el flujo de la API. Puedes almacenar este archivo en el ámbito del proxy de API (en /apiproxy/resources/jsc del paquete del proxy de API o en la sección Scripts del panel de navegación del editor del proxy de API) o en los ámbitos de la organización o del entorno para reutilizarlo en varios proxies de API, tal como se describe en Gestionar 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>

Valor predeterminado:	Ninguno
Presencia:	Se debe especificar <ResourceURL> o <Source>. Si se incluyen <ResourceURL> y <Source>, se ignora <ResourceURL>.
Tipo:	Cadena

Ejemplo

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

Elemento <Source>

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

Valor predeterminado:	Ninguno
Presencia:	Se debe especificar <ResourceURL> o <Source>. Si se incluyen <ResourceURL> y <Source>, se ignora <ResourceURL>.
Tipo:	Cadena

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 para configurar TLS en todas las instancias de cliente HTTP creadas por la política de JavaScript.

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

Valor predeterminado:	Ninguno
Presencia:	Opcional
Tipo:	Cadena

El proceso para configurar TLS en un cliente HTTP es el mismo que se usa para configurar TLS en un TargetEndpoint o TargetServer. Para 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, lecturas o escrituras del sistema de archivos interno, o la obtención de información del usuario actual, la lista de procesos o la utilización de la CPU o la memoria. Aunque algunas de estas llamadas pueden funcionar, no se admiten y se pueden inhabilitar en cualquier momento. Para que sea compatible con versiones posteriores, debes evitar hacer esas llamadas en tu código.

Depurar código de política de JavaScript

Usa la función print() para mostrar información de depuración en el panel de salida de la transacción de la herramienta de depuración. Para obtener más información y ver ejemplos, consulta Depurar con instrucciones print() de JavaScript.

Para ver las instrucciones de impresión en Depuración, sigue estos pasos:

1. Abre la herramienta de depuración e inicia una sesión de seguimiento para un proxy que contenga tu política de JavaScript.
2. Llama al proxy.
3. En la herramienta de depuración, haga clic en Output from all Transactions (Resultados de todas las transacciones) para abrir el panel de resultados.

   

4. Las instrucciones de impresión aparecerán en este panel.

Puedes usar la función print() para enviar información de depuración a la herramienta de depuración. Esta función está disponible directamente a través del modelo de objetos de JavaScript. Para obtener más información, consulta Depurar JavaScript con instrucciones print().

Variables de flujo

Esta política no rellena ninguna variable de forma predeterminada. Sin embargo, puedes definir (y obtener) variables de flujo en tu código JavaScript llamando a métodos en el objeto de contexto. Un patrón típico tiene este aspecto:

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

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

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que se devuelven, así como las variables de error que define Apigee cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionar los errores. Para obtener más información, consulta Qué debes saber sobre los errores de políticas y Cómo gestionar los fallos.

Errores de tiempo de ejecución

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

Nota: ¿Necesitas ayuda para resolver un error? Haz clic en en la columna Solución para obtener información detallada sobre cómo solucionar el problema.

Código de fallo	Estado de HTTP	Causa	Solucionar
steps.javascript.ScriptExecutionFailed	500	La política JavaScript puede generar muchos tipos distintos de errores ScriptExecutionFailed. Entre los tipos de errores que se suelen ver se incluyen los siguientes: RangeError, ReferenceError, SyntaxError, TypeError y URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	Se ha producido un error en el código JavaScript. Consulta la cadena de errores para obtener más información.	N/A
steps.javascript.ScriptSecurityError	500	Se ha producido un error de seguridad al ejecutar JavaScript. Consulta la cadena de errores para obtener más información.	N/A

Errores de implementación

Estos errores pueden producirse al implementar un proxy que contenga esta política.

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

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

Variables de error

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

Variables	Dónde	Ejemplo
fault.name="fault_name"	fault_name es el nombre del fallo, tal como se indica en la tabla Errores de tiempo de ejecución de arriba. El nombre del error es la última parte del código de error.	fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed	policy_name es el nombre de la política especificado por el usuario que ha provocado el error.	javascript.JavaScript-1.failed = true

Ejemplo de respuesta de error

Nota: Para gestionar los errores, la práctica recomendada es detectar la parte errorcode de la respuesta de error. No te fíes del texto de 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"
    }
  }
}

Regla de error de ejemplo

<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

Cada tipo de política se define mediante un esquema XML (.xsd). Para obtener más información, consulte los esquemas de políticas 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 gestionar encabezados de varios valores en JavaScript?