Política JavaScript

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

Qué

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

Acerca de

Existen muchos casos de uso para la política de JavaScript. Por ejemplo, puedes obtener y configurar variables de flujo, ejecutar lógica personalizada y realizar un control de fallas, extraer datos de solicitudes o respuestas, editar de forma dinámica la URL de destino del backend y mucho más. Esta política te permite implementar un comportamiento personalizado que no está cubierto por ninguna otra política de Edge estándar. De hecho, puedes usar una política de JavaScript para lograr muchos de los mismos comportamientos que implementan 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 de registro de mensajes 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 de registro de mensajes 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 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 tu JavaScript a través del editor de proxy de la IU de Apigee.

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

Consulta la página sobre el software compatible y las versiones compatibles para conocer la versión actual compatible de JavaScript.

Video

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

Ejemplos

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

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

Referencia de elementos

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.

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

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>

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

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

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>

Atributos

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 la API. Puedes almacenar este archivo en el alcance del proxy de la API (en /apiproxy/resources/jsc, en el paquete del proxy de la API o en la sección de secuencias de comandos del panel Navigator del editor de proxy de API), o en los permisos de la organización o del entorno para volver a utilizarlos en varios proxies de API, como se describe en Archivos de 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>

Ejemplo

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

Elemento <Source>

Te permite 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.

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>

El proceso de configuración de TLS para un cliente HTTP es el mismo que se usa con el fin de configurar TLS para TargetEndpoint/TargetServer. Consulta Configura TLS desde Edge al backend para obtener más información.

Notas de uso

Una política de JavaScript no contiene código real. Hace referencia a un "recurso" de JavaScript y define el paso en el flujo de API en el que se ejecuta el JavaScript. Puedes subir tu secuencia de comandos a través del editor de proxy de la IU de administración o puedes incluirla en el directorio /resources/jsc de los proxies de API que desarrollas de forma 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 de seguimiento. Para obtener detalles y ejemplos, consulta Cómo depurar con declaraciones print() de JavaScript.

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

1. Abre la herramienta Trace 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 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 en la herramienta de seguimiento. Esta función está disponible directamente a través del modelo de objetos de JavaScript. Para obtener más información, consulta "Cómo depurar JavaScript con sentencias print()".

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 mediante llamadas a los métodos en el objeto context. Un patrón típico se ve así:

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

Referencia de errores

En esta sección, se describen los códigos y mensajes de error que se muestran, así como las variables de fallas que establece Edge 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.

Errores en la implementación

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

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.

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

• Modelo de objetos de JavaScript
• Para obtener instrucciones, ejemplos de políticas y muestras de JavaScript, consulta Cómo programar proxies de API con 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