Política JavaScript

Estás viendo la documentación de Apigee X.
Consulta la documentación de Apigee Edge.

ícono de política

Qué

Esta política te permite agregar 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, métodos y propiedades del modelo de objeto de JavaScript de Apigee. El modelo de objetos te permite obtener, configurar y quitar variables en el contexto de flujo del proxy. También puedes usar funciones criptográficas básicas que se proporcionan con el modelo de objeto.

Información

La política de JavaScript tiene muchos casos prácticos. Por ejemplo, puedes obtener y configurar variables de flujo, ejecutar lógica personalizada y controlar errores, extraer datos de solicitudes o respuestas, editar dinámicamente la URL de destino del backend y mucho más. Esta política te permite implementar un comportamiento personalizado que ninguna otra política estándar de Apigee cubre. De hecho, puedes usar una política de JavaScript para lograr muchos de los mismos comportamientos implementados por otras políticas, como AssignMessage y ExtractVariable.

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

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

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

Apigee es compatible con JavaScript que se ejecuta en el motor JavaScript Rhino 1.7.7.1.

Video

Mira un breve video para obtener información sobre cómo crear una extensión de política personalizada con la política JavaScript.

Ejemplos

Reescribe la URL de destino

Este es un caso práctico común: extraer datos de un cuerpo de solicitud, almacenarlos en una variable de flujo y usar esa variable de flujo en otro lugar del flujo del proxy. Supongamos que tienes una app en la que el usuario ingresa su nombre en un formulario HTML y lo envía. Deseas que el proxy de la API extraiga los datos del formulario y lo agregue de manera dinámica a la URL utilizada para llamar al servicio de backend. ¿Cómo lo haría en una política de JavaScript?

  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 un nombre a la secuencia de comandos, como js-example.
  5. Pegue el siguiente código en el editor de código y guarde el proxy. Lo importante a tener en cuenta es 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 obtener más operaciones. Esta parte del objeto es el modelo del objeto JavaScript de Apigee. Además, ten en cuenta que la variable de flujo target.url es una variable incorporada de lectura y escritura a la que se puede acceder en el flujo de solicitud de destino. Cuando configuramos esa variable con la URL de la API, Apigee realiza la llamada de backend a esa URL. Hemos reescrito la URL de destino original, que es lo que especificaste cuando creaste el proxy (p.ej., 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 un nombre a la política, como target-rewrite. Acepta los valores predeterminados y guarda la política.
  8. Si seleccionas el flujo previo de extremos del proxy de navegador en el navegador, verás que la política se agregó a ese flujo.
  9. En el navegador, selecciona el ícono Target Endpoint PreFlow.
  10. Desde el navegador, arrastra la política de JavaScript al lado de la solicitud del extremo de destino en el editor de flujo.
  11. haz clic en Guardar.
  12. Llama a la API de esta manera, y sustituye el nombre de la organización y el nombre del proxy correctos según corresponda:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

Por último, veamos la definición de XML para la política de JavaScript que se usa en este ejemplo. Lo importante a tener en cuenta es que el elemento <ResourceURL> se usa para especificar el archivo fuente de JavaScript que se ejecutará. Se usa este mismo patrón para cualquier archivo fuente JavaScript: jsc://filename.js. Si el código JavaScript que requiere se incluye, puedes usar uno o más 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>

Recupera el valor de la propiedad de JavaScript

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

Usa el atributo name del elemento para especificar el nombre con el que deseas 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 recuperar el valor de la propiedad de la política si accedes a él como una propiedad del objeto Properties, como se muestra a continuación:

  • Configura la propiedad. Aquí, 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. Aquí, el valor recuperado, un nombre de variable, se usa luego en la función getVariable 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 una solicitud de texto de JavaScript, consulta cómo corregir errores de políticas de JavaScript. Las sugerencias que se ofrecen en la comunidad de Apigee son solo para información y no representan necesariamente las prácticas recomendadas por Google.


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>

<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 Predeterminada Presencia
timeLimit

Especifica el tiempo máximo (en milisegundos) que la secuencia de comandos puede ejecutar.

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 Predeterminada 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.

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.

falso 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.

falso Obsoleta

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

N/A

Si omites este elemento, se usa el valor del atributo name de la política.

Presencia Opcional
Tipo String

Elemento <IncludeURL>

Especifica un archivo de biblioteca de JavaScript que se cargará como dependencia al archivo JavaScript principal especificado con el elemento <ResourceURL> o <Source>. Las secuencias de comandos se evaluarán en el orden en que se incluyan en la política. Tu código puede usar los objetos, métodos y propiedades del modelo de objeto de JavaScript.

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

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Predeterminado: None
Presencia: Opcional
Tipo: String

Ejemplo

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

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: None
Presencia: Opcional
Tipo: String

Atributos

Atributo Descripción Predeterminada 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 ejecutará en el flujo de 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 de secuencias de comandos del panel de navegación del editor de proxy de API), o en los permisos de la organización o del entorno para volver a utilizarse. en múltiples proxies de API, como se describe en Archivos de recursos. Tu código puede usar los objetos, métodos y propiedades del modelo de objeto de JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>
Predeterminado: None
Presencia: Se requiere <ResourceURL> o <Source>. Si <ResourceURL> y <Source> están presentes, se ignora <ResourceURL>.
Tipo: String

Ejemplo

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

Elemento <Source>

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.

Predeterminado: None
Presencia: Se requiere <ResourceURL> o <Source>. Si <ResourceURL> y <Source> están presentes, se 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 utilizadas 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>
Predeterminado: None
Presencia: Opcional
Tipo: String

El proceso de configuración de TLS para un cliente HTTP es el mismo proceso que usas a fin de configurar TLS para un TargetEndpoint/TargetServer. Para obtener más información, consulta Opciones para configurar TLS.

Notas de uso

Una política de JavaScript no contiene código real. En cambio, una política de JavaScript hace referencia a un “recurso” de JavaScript y define el paso en el flujo de la API en el que se ejecuta JavaScript. Puedes subir tu secuencia de comandos mediante el editor de proxy de IU de Apigee o incluirla en el directorio /resources/jsc en proxies de API que desarrollas de manera local.

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 Depuración con declaraciones print() de JavaScript.

Para ver las declaraciones de impresión en Trace, haz lo siguiente:

  1. Abre la herramienta Trace 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 Trace, haz clic en Resultado de todas las transacciones para abrir el panel de resultados.

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

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

Variables de flujo

Esta política no propaga variables de forma predeterminada. Sin embargo, puedes configurar (y obtener) variables de flujo en el código JavaScript; para ello, llama a los métodos en el objeto contextual. Un patrón típico se ve así:

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

El objeto context forma parte del modelo de objeto 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.

Código de falla Estado de HTTP Causa Corregir
steps.javascript.ScriptExecutionFailed 500 La política JavaScript puede generar muchos tipos diferentes de errores ScriptExecutionFailed. Entre los tipos de errores que se muestran comúnmente, se incluyen RangeError, ReferenceError, SyntaxError, TypeError y URIError.
steps.javascript.ScriptExecutionFailedLineNumber 500 Se produjo un error en el código JavaScript. Para obtener más información, consulta la string de errores. N/A
steps.javascript.ScriptSecurityError 500 Se produjo un error de seguridad cuando se ejecutó la JavaScript. Para obtener más información, consulta la string de fallas. N/A

Errores en la implementación

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

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 JavaScript puede generar este error si no se declara el elemento <ResourceURL> o si la URL del recurso no está definida dentro de este elemento. El elemento <ResourceURL> es un elemento obligatorio. O bien, el elemento <IncludeURL> se declara, pero la URL del recurso no está definida dentro de este elemento. El elemento <IncludeURL> es opcional, pero si se declara, debe especificarse la URL del recurso 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

{
  "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

Artículos de la comunidad de Apigee

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