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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

Deployment errors

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

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.

Example error response

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