Política JavaCallout

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

Consulta la documentación de Apigee Edge.

ícono de política

Qué

Te permite usar Java para implementar comportamientos personalizados que las políticas de Apigee no incluyen desde el primer momento. En tu código Java, puedes acceder a propiedades de mensajes (encabezados, parámetros de consulta, contenido) y variables de flujo en el flujo del proxy. Si acabas de comenzar a usar esta política, consulta Cómo crear un texto destacado de Java.

Las versiones de Java compatibles incluyen Oracle JDK 11 y OpenJDK 11.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Cuándo

Para obtener instrucciones, consulta “¿Cuándo debo usar un texto destacado de Java?” en Crea un texto destacado de Java.

Información

La política de texto destacado de Java te permite obtener y configurar variables de flujo, ejecutar lógica personalizada, controlar errores, extraer datos de solicitudes o respuestas y mucho más. Esta política te permite implementar un comportamiento personalizado que ninguna otra política estándar de Apigee cubre.

Puedes empaquetar tu aplicación de Java con los archivos JAR de paquetes que necesites. Ten en cuenta que existen algunas restricciones sobre lo que puedes hacer con un texto destacado de Java. Se enumeran a continuación en Restricciones.

Ejemplos

Ejemplo simple

Cómo crear un texto destacado de Java

Recupera propiedades en tu código Java

El elemento <Property> de la política te permite especificar un par nombre-valor que puedes recuperar en el entorno de ejecución de tu código Java. Para ver un ejemplo funcional en el que se usen propiedades, consulta Cómo usar propiedades en un texto destacado de Java.

Usa el atributo name del elemento <Property> para especificar el nombre con el que se accede a la propiedad desde el código Java. El valor del elemento <Property> (el valor entre las etiquetas de apertura y cierre) es el valor que recibirá el código Java. Debe ser una string; no puedes hacer referencia a una variable de flujo para obtener el valor.

  • Configura la propiedad. Aquí, el valor de la propiedad es el nombre de 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 de ejecución de la siguiente manera:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Configura variables de flujo en tu código Java

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

Referencia del elemento

En la referencia del elemento, 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 <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 principales de las políticas:

Atributo Descripción Predeterminado Presence
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.

De forma opcional, usa el elemento <DisplayName> para etiquetar la política en el editor de proxy de la IU de administración con un nombre de lenguaje natural diferente.

 N/A Obligatorio
continueOnError

Configúralo como false para mostrar un error cuando una política falla. Este es el comportamiento previsto para la mayoría de las políticas.

Configúralo como true para continuar con la ejecución del flujo incluso después de que una política falle. También consulta lo siguiente:

 false Opcional
enabled

Configúralo como true para aplicar la política.

Configúralo como false para desactivar la política. La política no se aplicará incluso si permanece adjunta a un flujo.

 true Opcional
async

Este atributo dejó de estar disponible.

 false Obsoleto

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

N/A

Si omites este elemento, se usa el valor del atributo name de la política.
Presence Opcional
Tipo String

Elemento <ClassName>

Especifica el nombre de la clase Java que se ejecuta cuando se ejecuta la política de texto destacado de Java. La clase debe incluirse en el archivo JAR que especifica la <ResourceURL>. Consulta también Cómo crear un texto destacado de Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Predeterminado: N/A
Presencia: Obligatorio
Tipo: String

Elemento <Properties>

Agrega propiedades nuevas a las que puedes acceder desde el código Java en el entorno de ejecución.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Predeterminado: Ninguno
Presencia: Opcional
Tipo: String

Elemento <Property>

Especifica una propiedad a la que puedes acceder desde el código Java en el entorno de ejecución. Debes especificar un valor de string literal para cada propiedad, no puedes hacer referencia a variables de flujo en este elemento. Para ver un ejemplo funcional en el que se usen propiedades, consulta Cómo usar propiedades en un texto destacado de Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Predeterminado: Ninguno
Presencia: Opcional
Tipo: String

Atributos

Atributo Descripción Predeterminado Presence
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 de texto destacado de Java.

Puedes almacenar este archivo en el permiso del proxy de API (en /apiproxy/resources/java en el paquete del proxy de API o en la sección de secuencias de comandos del panel de navegación del editor de proxy de API), o en los permisos de la organización o del entorno para volver a utilizarse. en múltiples proxies de API, como se describe en Archivos de recursos.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Predeterminado: Ninguno
Presencia: Obligatorio
Tipo: String

Referencia de errores

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

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. Supported Java versions include: Oracle JDK 7/8 and OpenJDK 7/8
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

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

Example fault rule

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

Esquemas

Compila e implementa

Para obtener detalles sobre cómo compilar tu código Java personalizado e implementarlo con un proxy, consulta Cómo crear un texto destacado de Java.

Restricciones

A continuación, se presentan las restricciones que debes tener en cuenta cuando escribas textos destacados de Java:

  • La mayoría de las llamadas al sistema no están permitidas. Por ejemplo, no puedes realizar operaciones de lectura ni escritura en el sistema de archivos internos.
  • Acceso a la red a través de sockets. Apigee restringe el acceso a las direcciones de sitio local, de bucle invertido, de enlace-local y locales.
  • El texto destacado no puede obtener información sobre el proceso actual, la lista de procesos o el uso de CPU o memoria en la máquina. Si bien algunas llamadas pueden ser funcionales, no son compatibles y están sujetas a la inhabilitación activa en cualquier momento. Para garantizar la compatibilidad con versiones futuras, debes evitar realizar este tipo de llamadas en tu código.
  • La dependencia de bibliotecas Java que se incluyen con Apigee no es compatible. Esas bibliotecas son solo para la funcionalidad de productos de Apigee y no hay garantía de que una biblioteca esté disponible entre un lanzamiento y el siguiente.
  • No uses io.apigee ni com.apigee como nombres de paquete en textos destacados de Java. Esos nombres están reservados y son usados por otros módulos de Apigee.

Empaquetado

Ubica el JAR en un proxy de API en /resources/java. Si tu texto destacado de Java depende de bibliotecas de terceros adicionales empaquetadas como archivos JAR independientes, ubica también esos archivos JAR en el directorio /resources/java para asegurarte de que se carguen de forma correcta en el entorno de ejecución.

Si usas la IU de administración para crear o modificar el proxy, agrega un recurso nuevo y especifica un archivo JAR dependiente adicional. Si hay varios JAR, solo agrégalos como recursos adicionales. No necesitas modificar la configuración de la política para hacer referencia a archivos JAR adicionales. Ubicarlos en /resources/java es suficiente.

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

Para ver un ejemplo detallado que muestre cómo empaquetar y, luego, implementar un texto destacado de Java con Maven o javac, consulta Cómo crear un texto destacado de Java.

Javadoc

Se incluye Javadoc para escribir el código de texto destacado de Java aquí en GitHub. Deberás clonar o descargar el HTML en tu sistema y, luego, solo abrir el archivo index.html en un navegador.

Notas de uso y prácticas recomendadas

  • Cuando trabajes con varios textos destacados de Java, considera subir JAR comunes como recursos con alcance de entorno. Esta práctica es más eficiente en comparación con empaquetar los mismos archivos JAR con varios paquetes de proxy cuando se implementan en el mismo entorno.
  • Evita empaquetar e implementar varias copias o versiones del mismo archivo JAR en un entorno. Por ejemplo, Apigee recomienda evitar lo siguiente:
    • Implementar el mismo JAR como parte de un paquete de proxy y como un recurso del entorno
    • Implementar una versión de un archivo JAR como recurso del entorno y otra como parte de un paquete de proxy

    Tener varias copias del mismo JAR implementado puede provocar un comportamiento no determinista en el entorno de ejecución debido a posibles conflictos de ClassLoader.

  • Una política de texto destacado de Java no contiene código real, sino que 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 JAR de Java con el editor de proxy de la IU de administración o puedes incluirlo en el directorio /resources/java en los proxies de API que desarrollas de manera local.
  • Para operaciones ligeras, como las llamadas a la API a servicios remotos, te recomendamos usar la política ServiceCallout. Consulta Política de texto destacado de servicio.
  • Para interacciones relativamente simples con el contenido de mensajes, como modificar o extraer encabezados HTTPS, parámetros o contenido de mensajes, Apigee recomienda usar una política de JavaScript.