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.

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.

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.
• Realizar llamadas al sistema El modelo de seguridad no permite llamadas al sistema desde la política de JavaScript. 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 estas llamadas en tu código.

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 de 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 el nombre target-rewrite a la política. 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);

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 <ResourceURL> y <Source> están presentes, 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 <ResourceURL> y <Source> están presentes, 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.

Usa JavaScript para controlar errores

Puedes usar la política de JavaScript para controlar y devolver errores. Para obtener un análisis sobre este tema, consulta Cómo visualizar correctamente los errores de una política de JavaScript en la comunidad de Apigee. Ten en cuenta que las publicaciones y los comentarios de la comunidad no necesariamente representan las prácticas recomendadas por Apigee.

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 de Debug, haz clic en la política de JavaScript y, luego, en la pestaña Propiedades para ver la propiedad "stepExecution-stdout" que muestra el resultado de la instrucción print.

   

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Tip: Need help resolving an error? Click in the Fix column for detailed troubleshooting information.

Fault code	HTTP status	Cause	Fix
steps.javascript.ScriptExecutionFailed	500	The JavaScript policy can throw many different types of ScriptExecutionFailed errors. Commonly seen types of errors include RangeError, ReferenceError, SyntaxError, TypeError, and URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	An error occurred in the JavaScript code. See the fault string for details.	N/A
steps.javascript.ScriptSecurityError	500	A security error occurred when the JavaScript executed. See the fault string for details.	N/A

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Tip: Need help resolving an error? Click next to the error's cause description to visit the troubleshooting page.

Error name	Cause	Fix
InvalidResourceUrlFormat	If the format of the resource URL specified within the <ResourceURL> or the <IncludeURL> element of the JavaScript policy is invalid, then the deployment of the API proxy fails.
InvalidResourceUrlReference	If the <ResourceURL> or the <IncludeURL> elements refer to a JavaScript file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level.
WrongResourceType	This error occurs during deployment if the <ResourceURL> or the <IncludeURL> elements of the JavaScript policy refer to any resource type other than jsc (JavaScript file).
NoResourceURLOrSource	The deployment of the JavaScript policy can fail with this error if the <ResourceURL> element is not declared or if the resource URL is not defined within this element. <ResourceURL> element is a mandatory element. Or, The <IncludeURL> element is declared but the resource URL is not defined within this element. The <IncludeURL> element is optional but if declared, the resource URL must be specified within the <IncludeURL> element.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	javascript.JavaScript-1.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

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

Example fault rule

<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