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 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 JavaRecupera 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 De forma opcional, usa el elemento |
N/A | Obligatorio |
continueOnError |
Configúralo como Configúralo como |
falso | Opcional |
enabled |
Configúralo como Configúralo como |
verdadero | 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>
Default |
N/A Si omites este elemento, se usa el valor del atributo |
---|---|
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 <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: | None |
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: | 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 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 . |
build |
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 | Estos son los parámetros: | 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.
- 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
nicom.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 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.