Esta página se ha traducido con Cloud Translation API.

Cómo crear una llamada de código Java

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

Consulta la documentación de Apigee Edge.

¿Qué es una llamada de código Java?

Apigee ofrece una serie de políticas que responden a los requisitos habituales de gestión de APIs, como seguridad, transformación de datos, gestión del tráfico y otros.

Sin embargo, en algunos casos, tu API requiere un comportamiento personalizado que no se implementa en una política estándar. En estos casos, Apigee ofrece varias opciones que te permiten crear secuencias de comandos o código para personalizar el comportamiento de las APIs. Una opción es implementar el comportamiento deseado en Java.

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

¿Cómo puedo usar código Java en un proxy?

La política JavaCallout te permite llamar a código Java desde un flujo de proxy en ejecución. El código Java debe implementar determinadas interfaces Java específicas de Apigee que permitan que el código interactúe con el proxy en ejecución. Por ejemplo, existen métodos de Java para obtener y definir encabezados, parámetros de consulta, variables de flujo y otras entidades en el contexto de flujo actual del proxy.

¿Cuándo debo usar la política JavaCallout?

Veamos en qué situaciones es útil la política JavaCallout y en cuáles deberías considerar otras opciones.

Primero, considera enfoques alternativos

Antes de usar la política JavaCallout, ten en cuenta que puede haber enfoques alternativos que puedas usar en su lugar. Por ejemplo:

Para operaciones ligeras, como las llamadas a la API HTTP a servicios remotos, considera la posibilidad de usar 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, puedes usar las políticas JavaScript o PythonScript.

Qué puedes hacer en el código Java

La política JavaCallout admite estas operaciones básicas:

Examinar o manipular mensajes de solicitud o respuesta
Obtener y definir variables de flujo. Puedes usar métodos de Java para acceder a las variables de flujo de Apigee. Si quieres acceder a la información de un mapa de clave-valor (KVM), usa una política de KVM, asigna valores de KVM a variables de flujo y, a continuación, podrás acceder a las variables de flujo desde la política JavaCallout.
Llamar a servicios externos
Informar de fallos
Manipular mensajes de error y códigos de estado

Qué no puedes hacer en el código Java

La mayoría de las llamadas al sistema no están permitidas. No puedes:

Realizar lecturas o escrituras en el sistema de archivos interno. Esto significa que no puedes usar ninguno de los paquetes de Java para leer o escribir en sistemas de archivos internos, pero sí puedes hacer llamadas remotas externas.
Obtener información sobre el proceso actual, la lista de procesos o el uso de CPU o memoria en la máquina.
Accede al código fuente en expressions-1.0.0.jar y message-flow-1.0.0.jar.

Aunque algunas de estas llamadas pueden funcionar, no se admiten y pueden inhabilitarse en cualquier momento. Evita hacer este tipo de llamadas en tu código.

No uses ni dependas de las bibliotecas Java que se incluyen con Apigee. Estas bibliotecas solo se usan para las funciones del producto Apigee y no se garantiza que una biblioteca esté disponible de una versión a otra. Si usas estas bibliotecas, hazlo solo en demostraciones que no sean de producción.

Hola JavaCallout

Vamos a ver un ejemplo básico de una política JavaCallout de Hello World. En este ejemplo, creamos un proxy sencillo con JavaCallout que devuelve una respuesta "hello world". El proxy puede devolver una de las dos respuestas posibles:

Si envías un encabezado "username" con el valor "name", el proxy devuelve lo siguiente:
```
Hello, <name>!
```
Si omites el encabezado, el proxy solo devuelve:
```
"Hello, Guest!"
```

Descarga el proyecto inicial

Para simplificar las cosas, hemos preparado un proyecto básico en GitHub en el repositorio api-platform-samples de Apigee.

Descarga o clona api-platform-samples en tu sistema. Si ya tienes api-platform-samples en tu sistema, haz un pull para asegurarte de que tienes la versión más reciente.
En el terminal o editor de código que prefieras, ve al proyecto api-platform-samples/doc-samples/java-hello.

Escribir el código Java

Abre el archivo de origen de Java: java-hello/callout/src/main/java/HelloJava.java. Este archivo es una versión básica de la clase principal de Java que vamos a implementar. Los paquetes importados son necesarios para el código JavaCallout de Apigee. Estas clases proporcionan métodos que te permiten acceder al contexto de ejecución del proxy. En breve, veremos los pasos para compilar e implementar este código.

package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;


public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {

                try {

                        // Your code here.

            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}

Sustituye la línea comentada // Your code here por el siguiente código:
```
String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
```
Nota: Nota: El objeto MessageContext te permite acceder a las entidades del flujo en el que se ejecuta la política JavaCallout. Supongamos que la política JavaCallout está asociada al flujo de respuesta del endpoint proxy. El código indicado arriba obtiene el objeto de mensaje HTTP de ese contexto de flujo. El objeto Message , a su vez, te da acceso a los encabezados, los parámetros de consulta, el contenido del cuerpo y las variables de flujo.
Guarda el archivo.

Compila el código con Maven

Asegúrate de que tienes instalado Maven:
```
mvn -version
```

Instala las dependencias JAR necesarias en tu repositorio Maven local mediante uno de los siguientes métodos:

Añade el siguiente fragmento al archivo pom.xml para descargar las dependencias JAR necesarias de Artifact Registry:

<repositories>
  <repository>
    <id>artifact-registry</id>
    <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.apigee.gateway.libraries</groupId>
    <artifactId>message-flow</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.apigee.infra.libraries</groupId>
    <artifactId>expressions</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
</dependencies>

Usa las siguientes llamadas curl para descargar las dependencias JAR necesarias de Artifact Registry:

curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar

curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar

Ejecuta la secuencia de comandos java-hello/buildsetup.sh. Esta secuencia de comandos descarga las dependencias JAR necesarias del repositorio de GitHub de Apigee.

Ve al directorio java-hello/callout.
Ejecutar Maven:
```
mvn clean package
```
Nota: Si aparece un error de Maven, asegúrate de que estás en el directorio java-hello/callout.
Si quieres, comprueba que el archivo JAR edge-custom-policy-java-hello.jar se haya copiado en java-hello/apiproxy/resources/java. Esta es la ubicación obligatoria de los archivos JAR que quieras implementar con un proxy.

Implementar y llamar al proxy

Sigue estos pasos para implementar y probar el proxy de API:

Cambia al directorio java-hello.

Comprime el paquete del proxy de API:

zip apiproxy-bundle.zip -r apiproxy -x \*.\*~

La forma más sencilla de desplegar el proxy es empaquetarlo en un archivo ZIP y subirlo a un entorno de tu organización de Apigee. Consulta Crear un proxy de APIs. Asegúrate de usar la opción Subir paquete proxy. Consulta también Consejos y trucos para subir un proxy de API en un paquete de proxy en la comunidad de Apigee.
Cuando se haya implementado el proxy, prueba a llamarlo:
```
curl  https://$HOSTNAME/java-hello -H "username:Will"
```
Devuelve "Hola, Will!

Información sobre el proxy

Vamos a examinar rápidamente las políticas que se usan en este proxy. Presta atención a la ubicación de las políticas en el flujo del proxy y al motivo.

Política de mensajes asignados

Se adjunta una política de mensaje Assign al flujo de solicitud de ProxyEndpoint. Copia el encabezado de nombre de usuario de la solicitud y lo asigna a la respuesta. Esta operación permite que la política JavaCallout, que está asociada al flujo de respuesta, acceda al encabezado del nombre de usuario y cree un cuerpo de respuesta personalizado con el valor de ese encabezado.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">
    <DisplayName>CopyHeader</DisplayName>
    <Copy source="request">
        <Headers>
          <Header name="username"/>
        </Headers>
    </Copy>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Política JavaCallout

La política JavaCallout se adjunta al flujo de respuesta. Esto se debe a que el código Java personalizado hace cambios en los encabezados de respuesta y en el mensaje. El elemento ClassName de la política especifica la clase principal que ejecuta la política. El elemento ResourceURL es el nombre del archivo JAR que has creado y añadido al directorio resources/java del proxy.

<JavaCallout name="hello-java">
    <ClassName>com.apigeesample.HelloJava</ClassName>
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL>
</JavaCallout>

Qué debes saber sobre la política JavaCallout

Aspectos importantes que debes tener en cuenta al implementar la política JavaCallout:

Importa clases de los paquetes com.apigee.flow.execution y com.apigee.flow.message. Estos paquetes deben incluirse en el archivo JAR que se empaqueta y se implementa. Puedes subir tu 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 de forma local.
Implementa la interfaz Execution. Todo el código Java que se ejecute en un proxy de API debe implementar Execution.
La política JavaCallout no contiene código. En su lugar, la política hace referencia a un "recurso" de Java, que debes empaquetar en un archivo JAR.
Nombres de paquetes que debes evitar: no uses io.apigee ni com.apigee como nombres de paquetes en las políticas JavaCallout. Están reservadas y las usan otros módulos de Apigee.
Si tu política JavaCallout se basa en bibliotecas de terceros adicionales empaquetadas como archivos JAR independientes, coloca esos archivos JAR en el directorio /resources/java para asegurarte de que se cargan correctamente en el tiempo de ejecución.
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 más información sobre cómo subir archivos JAR de Java, consulta Archivos de recursos.