Esta página se ha traducido con Cloud Translation API.

Política de JavaScript

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

Consulta la documentación de Apigee Edge.

La política de JavaScript le permite añadir 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 no esté cubierto por las políticas de Apigee.

En tu código JavaScript personalizado, puedes usar los objetos, los métodos y las propiedades del modelo de objetos de JavaScript de Apigee. Puede obtener, definir y eliminar variables en el contexto del flujo de proxy, ejecutar lógica personalizada, gestionar errores, extraer datos de solicitudes o respuestas y editar dinámicamente 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 de origen de JavaScript para ejecutarlo o incluir código JavaScript directamente en la configuración de la política mediante el elemento <Source>. De cualquier forma, el código JavaScript se ejecuta cuando se ejecuta el paso en el que se 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 del paquete proxy: apiproxy/resources/jsc. También puedes almacenar el código fuente en un archivo de recursos a nivel de entorno u organización. Para obtener instrucciones, consulta Archivos de recursos. También puedes subir JavaScript mediante el editor de proxy de la interfaz de usuario de Apigee.

Apigee no recomienda usar la política de JavaScript en los siguientes casos:

Registro. La política MessageLogging es más adecuada para registrar datos 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 PostClientFlow después de que la respuesta se devuelva al cliente.
Sustituir políticas de Apigee. La política de JavaScript no sustituye a las capacidades de las políticas de Apigee. Si las funciones que necesitas están disponibles en una política de Apigee, usa esa política en lugar de implementar una solución de JavaScript personalizada. Es posible que el código JavaScript personalizado no coincida con el rendimiento y la optimización de las políticas de Apigee.

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

Apigee admite JavaScript en el motor JavaScript Rhino 1.7.13.

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.

Ejemplos

Reescribir la URL de destino

Un caso de uso habitual consiste en extraer datos del cuerpo de una solicitud, almacenarlos en una variable de flujo y, a continuación, usar esa variable de flujo en otra parte del flujo del proxy. Por ejemplo, supongamos que un usuario introduce su nombre en un formulario HTML y lo envía. Para extraer los datos del formulario y añadirlos dinámicamente a la URL del servicio backend, usa una política de JavaScript.

Nota: Para probar este ejemplo, crea un nuevo proxy en el editor de proxies. Cuando crees el proxy, proporciona una URL de servicio de backend, por ejemplo, http://www.example.com. En este ejemplo, se reescribe dinámicamente la URL de backend. Si necesitas crear un proxy, consulta el tutorial de introducción.

En la interfaz de usuario de Apigee, abra el proxy que ha creado en el editor de proxies.
Selecciona la pestaña Desarrollar.
En el menú Nuevo, selecciona Nuevo script.
En el cuadro de diálogo, selecciona JavaScript y asigna el nombre js-example a la secuencia de comandos.
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 se define esa variable con la URL de la API, Apigee llama a esa URL de backend. De esta forma, se reescribe la URL de destino original, que era la que especificó 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);
}
```
En el menú Nueva política, selecciona JavaScript.
Asigna un nombre a la política target-rewrite. Acepta los valores predeterminados y guarda la política.
Después de seleccionar Proxy Endpoint Preflow (Preflow de endpoint de proxy) en Navigator (Navegador), la política se añade a ese flujo.
En Navigator (Navegador), selecciona Target Endpoint PreFlow (Preflujo de endpoint de destino).
En el navegador, arrastra la política de JavaScript al lado de la solicitud del endpoint de destino en el editor de flujo.
Guardar.
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 XML de la política de JavaScript que se usa en este ejemplo. El elemento <ResourceURL> especifica el archivo de origen de JavaScript que se va a ejecutar. Este patrón se aplica a cualquier archivo de origen de JavaScript: jsc://filename.js. Si tu código JavaScript requiere includes, usa uno o varios elementos <IncludeURL>, tal 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>

Obtener el valor de una propiedad de JavaScript

Puede añadir un elemento <Property> a la configuración y, a continuación, recuperar su valor 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 recibe JavaScript.

En JavaScript, puedes obtener el valor de la propiedad de la política accediendo a ella como propiedad del objeto Properties, de la siguiente manera:

Configura la propiedad. 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. La función getVariable usa el nombre de la variable obtenida para recuperar su valor.

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 puedes usar en una llamada de JavaScript, consulta Forma correcta de devolver un error desde una política de JavaScript. Las sugerencias de la comunidad de Apigee se ofrecen únicamente con fines informativos y no representan necesariamente las prácticas recomendadas por Google.

En una política de JavaScript, si se accede a request.content.asJSON en modo de solo lectura, los números enteros grandes se convierten en notación exponencial en el cuerpo del mensaje. De esta forma, se sobrescribe el mensaje 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>

< 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 ha escrito el código. Entre los valores se 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 puede ejecutarse una 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

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

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>. La política evalúa las secuencias de comandos en el orden en el que aparecen 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 mediante elementos <IncludeURL> adicionales.

Advertencia: Si tus archivos JavaScript están almacenados en el proxy o en el entorno, asegúrate de subirlos correctamente con cURL mediante la opción -F o como archivo adjunto a través de un cliente REST. El valor de 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

Elemento <Property>

Especifica una propiedad a la que puedes 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 ejecuta en el flujo de la API. Puedes almacenar este archivo en el ámbito del proxy de la API (en /apiproxy/resources/jsc del paquete del proxy de la API o en la sección Secuencias de comandos del panel Navegador del editor del proxy de la API). También puedes almacenarlo en los ámbitos de la organización o del entorno para reutilizarlo en varios proxies de API, tal como se describe en Gestión 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>

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

Ejemplo

Consulta el ejemplo de la sección Ejemplos.

Elemento <Source>

Puedes 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>`, la política 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

Depurar código de política de JavaScript

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

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

Abre la herramienta de depuración e inicia una sesión de seguimiento para un proxy que contenga tu política de JavaScript.
Llama al proxy.
En la herramienta de depuración, haga clic en Salida de todas las transacciones para abrir el panel de salida.
Las instrucciones de impresión aparecen en este panel.

Variables de flujo

Esta política no rellena ninguna variable de forma predeterminada. Sin embargo, puede definir y obtener variables de flujo en su 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

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.

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.

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, consulta 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 con varios valores en JavaScript

Política de JavaScript Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Ejemplos

Reescribir la URL de destino

Obtener el valor de una propiedad de JavaScript

Gestionar errores

Referencia de elemento

Atributos <Javascript>

Elemento <DisplayName>

Elemento <IncludeURL>

Elemento <Property>

Atributos

Ejemplo

Elemento <ResourceURL>

Ejemplo

Elemento <Source>

Ejemplo

Elemento <SSLInfo>

Notas de uso

Depurar código de política de JavaScript

Variables de flujo

Referencia de errores

Errores de tiempo de ejecución

Errores de implementación

Variables de error

Ejemplo de respuesta de error

Regla de error de ejemplo

Esquema

Temas relacionados

Artículos de la comunidad de Apigee

Política de JavaScript