Política JavaCallout

Estás viendo la documentación de Apigee Edge.
Ve a la Documentación de Apigee X. información

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.

Para conocer las versiones compatibles de Java, consulta Compatibilidad y versiones compatibles.

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 hacer lo siguiente: implementar un comportamiento personalizado que no esté cubierto por ninguna otra política estándar de Edge.

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

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.

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

 falso Obsoleta

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

N/A

Si omites este elemento, se usa el valor del atributo name de la política.
Presencia 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 <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: None
Presencia: Opcional
Tipo: String

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

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. See also Supported software and supported versions.
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.
  • No se admite la dependencia de las bibliotecas Java que se incluyen en Apigee Edge. Los que las bibliotecas son solo para la funcionalidad del producto Edge y no hay garantía de que una biblioteca estar disponible de un lanzamiento a otro.
  • 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.

Empaqueta

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

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

Temas relacionados