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 clase Execution. implementació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

En esta sección, se describen los códigos y mensajes de error que se muestran, y las variables de falla que establece Edge 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 arroja una excepción o muestra un resultado nulo durante la ejecución de una política JavaCallout.

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. Consulta también Funciones admitidas y versiones compatibles.
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

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