Política JavaCallout

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

Consulta la documentación de Apigee Edge.

Qué

Te permite usar Java para implementar comportamientos personalizados que no se incluyen de forma predeterminada en las políticas de Apigee. En el código Java, puede acceder a las propiedades de los mensajes (encabezados, parámetros de consulta y contenido) y a las variables de flujo en el flujo del proxy. Si acabas de empezar a usar esta política, consulta el artículo Cómo crear una llamada de código Java.

Entre las versiones de Java compatibles se incluyen Oracle JDK 11 y OpenJDK 11.

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.

Nota: Importante: Si desarrollas políticas de JavaCallout, debes saber qué políticas de permisos están vigentes en la JVM de Apigee y cómo afectarán a tu código. Consulta la referencia de permisos de Java. Consulta también la sección Restricciones.

Cuándo

Para consultar las directrices, ve a "¿Cuándo debo usar JavaCallout?" en Cómo crear una llamada de código Java.

Información

La política JavaCallout te permite obtener y definir variables de flujo, ejecutar lógica personalizada y gestionar errores, extraer datos de solicitudes o respuestas, y más. Esta política le permite implementar un comportamiento personalizado que no esté cubierto por ninguna otra política estándar de Apigee.

Nota: Apigee recomienda que uses la política de JavaScript si quieres usar JavaScript. También puedes usar la política Service Callout si necesitas hacer llamadas HTTP a servicios remotos. Sin embargo, si quieres escribir código Java personalizado, puedes hacerlo. Consulta también ¿Cuándo debo usar un JavaCallout?

Puedes empaquetar tu aplicación Java con los archivos JAR de paquetes que necesites. Nota: Hay algunas restricciones sobre lo que puedes hacer con JavaCallout. Estas restricciones se indican a continuación en la sección Restricciones.

Ejemplos

Ejemplo sencillo

Cómo crear una llamada de código Java

Recuperar propiedades en el código Java

El elemento <Property> de la política te permite especificar un par nombre/valor que puedes obtener en tiempo de ejecución en tu código Java. Para ver un ejemplo práctico que usa propiedades, consulta Cómo usar propiedades en políticas JavaCallout.

Use el atributo name del elemento <Property> para especificar el nombre con el que se accederá a la propiedad desde el código Java. El valor del elemento <Property> (el valor que figura entre las etiquetas de apertura y cierre) es el valor que recibirá el código Java. El valor debe ser una cadena. No puede hacer referencia a una variable de flujo para obtener el valor.

• Configura la propiedad. En este caso, el valor de la propiedad es el nombre de la variable response.status.code.

  <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
      <DisplayName>JavaCallout</DisplayName>
      <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
      <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
      <Properties>
          <Property name="source">response.status.code</Property>
      </Properties>
  </Javascript>

• En tu código Java, implementa el siguiente constructor en la implementación de la clase Execution de la siguiente manera:
  

  public class MyJavaCallout implements Execution{
      public MyJavaCallout(Map<string, string> props){
          
              // Extract property values from map.
      }
      ...
  }

Definir variables de flujo en el código Java

Para obtener una descripción clara de cómo definir variables en el contexto del mensaje (variables de flujo) en tu código Java, consulta esta publicación de la comunidad de Apigee.

---

Referencia de elemento

En la referencia de elementos se describen los elementos y atributos de la política JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

Atributos de <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

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. También puedes usar 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 Nota: En los casos en los que tu código Java genere una excepción, el flujo del proxy de Apigee pasará al estado de error aunque el atributo continueOnError esté definido como true. Si no quiere que una excepción devuelva un estado de error en el proxy, diseñe el código de llamada de Java de forma que no genere errores. En su lugar, detecta las excepciones y define una variable de contexto para capturar la información de la excepción. Para obtener más información, consulta esta publicación de la comunidad de Apigee.	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>

Se usa 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	N/A Si omite este elemento, se usará el valor del atributo name de la política.
Presencia	Opcional
Tipo	Cadena

Elemento <ClassName>

Especifica el nombre de la clase de Java que se ejecuta cuando se ejecuta la política JavaCallout. La clase debe incluirse en el archivo JAR especificado por <ResourceURL>. Consulta también Cómo crear una llamada de código Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>

Valor predeterminado:	N/A
Presencia:	Obligatorio
Tipo:	Cadena

Elemento <Properties>

Añade nuevas propiedades a las que puedes acceder desde el código Java en el tiempo de ejecución.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Valor predeterminado:	Ninguno
Presencia:	Opcional
Tipo:	Cadena

Elemento <Property>

Especifica una propiedad a la que puedes acceder desde el código Java en el tiempo de ejecución. Debe especificar un valor de cadena literal para cada propiedad. No puede hacer referencia a variables de flujo en este elemento. Para ver un ejemplo práctico que usa propiedades, consulta Cómo usar las propiedades en una política JavaCallout.

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

Elemento<ResourceURL>

Este elemento especifica el archivo JAR de Java que se ejecutará cuando se ejecute la política JavaCallout.

Puedes almacenar este archivo en el ámbito del proxy de API (en /apiproxy/resources/java del paquete del proxy de API o en la sección Scripts del panel de navegación del editor del proxy de API) o en los ámbitos de la organización o del entorno para reutilizarlo en varios proxies de API, tal como se describe en Archivos de recursos.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>

Valor predeterminado:	Ninguno
Presencia:	Obligatorio
Tipo:	Cadena

Referencia de errores

En esta sección se describen los códigos de error y los mensajes de error que devuelve Apigee, así como las variables de error que define, cuando esta política activa un error. Es importante que conozcas esta información si vas a desarrollar reglas de errores para gestionarlos. 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.javacallout.ExecutionError	500	Se produce cuando el código Java genera una excepción o devuelve un valor nulo durante la ejecución de un JavaCallout policy.

Errores de implementación

Estos errores pueden producirse cuando se implementa el proxy que contiene la política.

Nombre del error	Cadena de error	Estado de HTTP	Se produce cuando
ResourceDoesNotExist	Resource with name [name] and type [type] does not exist	N/A	El archivo especificado en el elemento <ResourceURL> no existe.
JavaCalloutInstantiationFailed	Failed to instantiate the JavaCallout Class [classname]	N/A	El archivo de clase especificado en el elemento <ClassName> no está en el archivo jar.
IncompatibleJavaVersion	Failed to load java class [classname] definition due to - [reason]	N/A	Consulta la cadena de errores. Las versiones de Java compatibles son Oracle JDK 7/8 y OpenJDK 7/8.
JavaClassNotFoundInJavaResource	Failed to find the ClassName in java resource [jar_name] - [class_name]	N/A	Consulta la cadena de errores.
JavaClassDefinitionNotFound	Failed to load java class [class_name] definition due to - [reason]	N/A	Consulta la cadena de errores.
NoAppropriateConstructor	No appropriate constructor found in JavaCallout class [class_name]	N/A	Consulta la cadena de errores.
NoResourceForURL	Could not locate a resource with URL [string]	N/A	Consulta la cadena de errores.

Variables de error

Estas variables se definen cuando esta política activa un error. Para obtener más información, consulta el artículo Información 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 "ExecutionError"
javacallout.policy_name.failed	policy_name es el nombre de la política especificado por el usuario que ha provocado el error.	javacallout.JC-GetUserData.failed = true

Ejemplo de respuesta de error

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Regla de error de ejemplo

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Esquemas

Ejemplo: Cada tipo de política se define mediante un esquema XML (.xsd). Puedes consultar los esquemas de políticas en GitHub.

Compilación e implementación

Para obtener información sobre cómo compilar tu código Java personalizado e implementarlo con un proxy, consulta Cómo crear una llamada de código Java.

Restricciones

Nota: Por motivos de seguridad, Apigee aplica políticas de permisos de Java al código de llamadas de Java. Las políticas se aplican al código que escribes, así como al código de los paquetes importados. Cualquier código (ya sea tuyo o importado) dará error si infringe una política de permisos. Para obtener más información, consulta la referencia de permisos de Java.

A continuación, se indican las restricciones que debe tener en cuenta al escribir código de llamada Java:

• La mayoría de las llamadas al sistema no están permitidas. Por ejemplo, no puedes hacer lecturas ni escrituras del sistema de archivos interno.
• Acceso a la red a través de sockets. Apigee restringe el acceso a las direcciones sitelocal, anylocal, loopback y linklocal.
• La llamada no puede obtener información sobre el proceso actual, la lista de procesos ni el uso de la CPU o la memoria de la máquina. Aunque algunas de estas llamadas pueden funcionar, no se admiten y se pueden inhabilitar en cualquier momento. Para que sea compatible con versiones posteriores, debes evitar hacer esas llamadas en tu código.
• No se admite el uso de bibliotecas de Java incluidas en Apigee. Estas bibliotecas solo se usan para las funciones del producto Apigee y no hay ninguna garantía de que una biblioteca esté disponible de una versión a otra.
• No uses io.apigee ni com.apigee como nombres de paquetes en Java Callouts. Esos nombres están reservados y los usan otros módulos de Apigee.

Embalaje

Coloca el archivo JAR en un proxy de APIs en /resources/java. Si tu código JavaCallout depende de bibliotecas de terceros adicionales empaquetadas como archivos JAR independientes, coloca esos archivos JAR en el directorio /resources/java para asegurarte de que se carguen correctamente en el tiempo de ejecución.

Si usas la interfaz de gestión para crear o modificar el proxy, añade un nuevo recurso y especifica un archivo JAR dependiente adicional. Si hay varios archivos JAR, solo tienes que añadirlos como recursos adicionales. No es necesario que modifiques la configuración de la política para hacer referencia a archivos JAR adicionales. Basta con ponerlos en /resources/java.

Para obtener información sobre cómo subir archivos JAR de Java, consulta Archivos de recursos.

Para ver un ejemplo detallado de cómo empaquetar y desplegar políticas JavaCallout con Maven o javac, consulta Cómo crear una llamada de código Java.

Javadoc

La documentación de Javadoc para escribir código de llamadas de Java se incluye aquí en GitHub. Deberás clonar o descargar el archivo HTML en tu sistema y, a continuación, abrir el archivo index.html en un navegador.

Notas de uso y prácticas recomendadas

• Cuando trabajes con varias políticas JavaCallout, considera la posibilidad de subir archivos JAR comunes como recursos con ámbito de entorno. Esta práctica es más eficiente que empaquetar los mismos archivos JAR con varios paquetes proxy al implementar en el mismo entorno.
• No empaquetes ni implementes varias copias o versiones del mismo archivo JAR en un entorno. Por ejemplo, Apigee recomienda que evites lo siguiente:
  • Desplegar el mismo archivo JAR como parte de un paquete de proxy y como recurso de entorno.
  • Desplegar una versión de un archivo JAR como recurso de entorno y otra como parte de un paquete de proxy.

  Si se implementan varias copias del mismo archivo JAR, se puede producir un comportamiento no determinista en el tiempo de ejecución debido a posibles conflictos de ClassLoader.

• Una política JavaCallout no contiene código. En su lugar, la política hace referencia a un "recurso" de Java y define el paso del flujo de la API en el que se ejecuta el código Java. Puedes subir tu archivo JAR de Java a través del editor de proxy de la interfaz de gestión o incluirlo en el directorio /resources/java de los proxies de API que desarrolles localmente.
• Para operaciones ligeras, como llamadas a APIs de servicios remotos, te recomendamos que uses la política ServiceCallout. Consulta la política de texto destacado de servicio.
• Para interacciones relativamente sencillas con el contenido de los mensajes, como modificar o extraer encabezados HTTP, parámetros o contenido de mensajes, Apigee recomienda usar una política de JavaScript.