Política JavaCallout

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

Consulta la documentación de Apigee Edge.

La política JavaCallout te permite usar Java para implementar un comportamiento personalizado que no se incluye de forma predeterminada en las políticas de Apigee. En tu código Java, puedes acceder a las propiedades de los mensajes (encabezados, parámetros de consulta y contenido), obtener y definir variables de flujo, ejecutar lógica personalizada, gestionar errores y extraer datos de solicitudes o respuestas, entre otras cosas. Si acabas de empezar a usar esta política, consulta Cómo crear una llamada de código Java.

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. Se indican en la sección Restricciones.

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

Nota: Apigee recomienda usar la política JavaScript en lugar de JavaCallout. También puedes usar la política Service Callout si necesitas hacer llamadas HTTP a servicios remotos. Consulta también ¿Cuándo debo usar un JavaCallout?

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.

Ejemplos

Ejemplos generales

Para ver un ejemplo sencillo de cómo usar una llamada de código Java, consulta Cómo crear una llamada de código Java.

Para saber cómo definir variables de flujo en tu código Java, consulta esta publicación de la comunidad de Apigee sobre la depuración de llamadas Java.

Recuperar propiedades en el código Java

En este ejemplo se muestra cómo usar 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.

Nota: Para ver un ejemplo práctico que usa propiedades, consulta Cómo usar propiedades en políticas JavaCallout

.

La configuración requiere dos elementos:

• 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>
  </JavaCallout>

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

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

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. 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 en 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 fallo SOLO se activan en un estado de 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 usuario 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 aplica 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 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 Qué debes saber sobre los errores de políticas y Cómo solucionar 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.javacallout.ExecutionError	500	Ocurre cuando el código Java muestra una excepción o un valor nulo durante la ejecución de un JavaCallout policy.

Errores en la implementación

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

Nombre del error	String de error	Estado de HTTP	Ocurre cuando
ResourceDoesNotExist	Resource with name [name] and type [type] does not exist	N/A	No existe el archivo especificado en el elemento <ResourceURL>.
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 incluyen 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 con fallas

Estas variables se establecen cuando esta política activa un error. 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 "ExecutionError"
javacallout.policy_name.failed	policy_name es el nombre especificado por el usuario de la política que generó la falla.	javacallout.JC-GetUserData.failed = true

Ejemplo de respuesta de error

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

Ejemplo de regla de falla

<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). A modo de referencia, los esquemas de políticas están disponibles 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 llamada de Java. Las políticas se aplican al código que escribes, así como al código de 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 pueden inhabilitarse 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. Esas 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 paquete en Java. Textos destacados. 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 los 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.