Come creare un callout Java

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Che cos'è un callout Java?

Apigee fornisce una gamma di criteri che soddisfano i requisiti comuni di gestione delle API, come sicurezza, trasformazione dei dati, gestione del traffico e altri.

Tuttavia, in alcuni casi la tua API richiede un comportamento personalizzato che non è implementato in una norma standard. In questi casi, Apigee offre diverse opzioni che ti consentono di creare script o codificare un comportamento personalizzato dell'API. Un approccio consiste nell'implementare il comportamento desiderato in Java.

Le versioni Java supportate includono: Oracle JDK 11 e OpenJDK 11.

Come faccio a utilizzare il codice Java in un proxy?

Il criterio JavaCallout consente di chiamare codice Java dall'interno di un flusso proxy in esecuzione. Il codice Java deve implementare determinate interfacce Java specifiche di Apigee che consentono al codice di interagire con il proxy in esecuzione. Ad esempio, esistono metodi Java per ottenere e impostare intestazioni, parametri di query, variabili di flusso e altre entità all'interno del contesto di flusso corrente del proxy.

Quando devo utilizzare il criterio JavaCallout?

Vediamo le situazioni in cui la norma JavaCallout è utile e quelle in cui dovresti valutare altri approcci.

Innanzitutto, prendi in considerazione approcci alternativi

Prima di utilizzare il criterio JavaCallout, tieni presente che potrebbero esistere approcci alternativi che puoi utilizzare invece. Ad esempio:

  • Per operazioni leggere, come le chiamate API HTTP a servizi remoti, valuta la possibilità di utilizzare il criterio ServiceCallout. Consulta le Norme relative ai callout di servizio.
  • Per interazioni relativamente semplici con i contenuti dei messaggi, come la modifica o l'estrazione di intestazioni HTTP, parametri o contenuti dei messaggi, puoi utilizzare i criteri JavaScript o PythonScript.

Cosa puoi fare nel codice Java

Il criterio JavaCallout supporta queste operazioni di base:

  • Esaminare o manipolare i messaggi di richiesta o risposta
  • Recupero e impostazione delle variabili di flusso. Puoi utilizzare i metodi Java per accedere alle variabili di flusso Apigee. Se vuoi accedere alle informazioni della mappa chiave/valore (KVM), utilizza una policy KVM, assegna i valori KVM alle variabili di flusso, quindi puoi accedere alle variabili di flusso da all'interno della policy JavaCallout.
  • Chiamata a servizi esterni
  • Segnalazione di errori
  • Manipolazione dei messaggi di errore e dei codici di stato

Cosa non puoi fare nel codice Java

La maggior parte delle chiamate di sistema non è consentita. Non puoi:

  • Eseguire letture o scritture del file system interno. Ciò significa che non puoi utilizzare nessuno dei pacchetti Java per leggere/scrivere nei file system interni; tuttavia, puoi effettuare chiamate remote esterne.
  • Visualizza informazioni sul processo corrente, sull'elenco dei processi o sull'utilizzo di CPU/memoria sulla macchina.
  • Accedi al codice sorgente in expressions-1.0.0.jar e message-flow-1.0.0.jar.

Anche se alcune di queste chiamate potrebbero funzionare, non sono supportate e potrebbero essere disattivate attivamente in qualsiasi momento. Evita di effettuare queste chiamate nel tuo codice.

Non utilizzare o fare affidamento sulle librerie Java incluse in Apigee. Queste librerie sono solo per la funzionalità del prodotto Apigee e non è garantito che una libreria sia disponibile da una release all'altra. Se utilizzi queste librerie, utilizzale solo in dimostrazioni non di produzione.

Hello JavaCallout

Vediamo un esempio di criterio JavaCallout di base per Hello World. In questo esempio, creiamo un semplice proxy con JavaCallout che restituisce una risposta "Hello World". Il proxy può restituire una delle due risposte possibili:

  • Se trasmetti un'intestazione "username" con un valore "name", il proxy restituisce:

    Hello, <name>!
  • Se ometti l'intestazione, il proxy restituisce solo:

    "Hello, Guest!"

Scaricare il progetto iniziale

Per semplificare le operazioni, abbiamo preparato un progetto di base per te su GitHub nel repository Apigee api-platform-samples.

  1. Scarica o clona api-platform-samples sul tuo sistema. Se hai già api-platform-samples sul sistema, esegui un pull per assicurarti di avere l'ultima versione.
  2. In un terminale o in un editor di codice a tua scelta, vai al progetto api-platform-samples/doc-samples/java-hello.

Scrivi il codice Java

  1. Apri il file sorgente Java: java-hello/callout/src/main/java/HelloJava.java. Questo file è una versione scheletrica della classe Java principale che implementeremo. I pacchetti importati sono necessari per il codice JavaCallout di Apigee. Queste classi forniscono metodi che ti consentono di accedere al contesto di esecuzione del proxy. A breve esamineremo i passaggi per compilare e implementare questo codice.
    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;
                }
        }

}
  2. Sostituisci la riga commentata // Your code here con il seguente codice:

    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!");
}
  3. Salva il file.


Compila il codice con Maven

  1. Assicurati di aver installato Maven:

    mvn -version
  2. Installa le dipendenze JAR richieste nel repository Maven locale utilizzando uno dei seguenti metodi:
    • Aggiungi il seguente snippet al file pom.xml per scaricare le dipendenze JAR richieste da 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>
    • Utilizza le seguenti chiamate curl per scaricare le dipendenze JAR richieste da 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
    • Esegui lo script java-hello/buildsetup.sh. Questo script scarica le dipendenze JAR richieste dal repository GitHub di Apigee.
  3. Vai alla directory java-hello/callout.
  4. Esegui Maven:

    mvn clean package
  5. Se vuoi, verifica che il file JAR edge-custom-policy-java-hello.jar sia stato copiato in java-hello/apiproxy/resources/java. Questa è la posizione richiesta per i file JAR che vuoi eseguire il deployment con un proxy.

Esegui il deployment e chiama il proxy

Segui questi passaggi per eseguire il deployment e testare il proxy API:

  1. Passa alla directory java-hello.
  2. Comprimi il bundle del proxy API: 
    zip apiproxy-bundle.zip -r apiproxy -x \*.\*~
  3. Il modo più semplice per eseguire il deployment del proxy è raggrupparlo in un file ZIP e caricare il bundle di proxy in un ambiente dell'organizzazione Apigee. Consulta Creazione di un proxy API. Assicurati di utilizzare l'opzione Carica pacchetto proxy. Vedi anche Suggerimenti per caricare il proxy API in un bundle proxy nella community Apigee.
  4. Una volta eseguito il deployment del proxy, prova a chiamarlo:
    curl  https://$HOSTNAME/java-hello -H "username:Will"

    che restituisce "Hello, Will!

Informazioni sul proxy

Esaminiamo rapidamente le policy utilizzate in questo proxy. Presta attenzione alla posizione delle norme nel flusso del proxy e al motivo.

Norme relative all'assegnazione dei messaggi

Un criterio Assign Message è collegato al flusso di richiesta ProxyEndpoint. Copia l'intestazione del nome utente dalla richiesta e la assegna alla risposta. Questa operazione consente alla policy JavaCallout, collegata al flusso di risposta, di accedere all'intestazione del nome utente e creare un corpo della risposta personalizzato utilizzando il valore di questa intestazione.

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

Norme JavaCallout

Il criterio JavaCallout è collegato al flusso di risposta. Questo perché il codice Java personalizzato apporta modifiche alle intestazioni della risposta e al messaggio. L'elemento ClassName della norma specifica la classe principale eseguita dalla norma. L'elemento ResourceURL è il nome del file JAR che hai creato e aggiunto alla directory resources/java del proxy.

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

Informazioni importanti sul criterio JavaCallout

Aspetti importanti da tenere presenti in merito all'implementazione del criterio JavaCallout:

  • Importa classi dai pacchetti com.apigee.flow.execution e com.apigee.flow.message. Questi pacchetti devono essere inclusi nel file JAR che viene pacchettizzato e implementato. Puoi caricare il file JAR Java tramite l'editor proxy dell'interfaccia utente di gestione oppure puoi includerlo nella directory /resources/java nei proxy API che sviluppi localmente.
  • Implementa l'interfaccia Execution. Qualsiasi codice Java eseguito all'interno di un proxy API deve implementare Execution.
  • Il criterio JavaCallout non contiene codice effettivo. Il criterio fa invece riferimento a una "risorsa" Java, che devi inserire in un file JAR.
  • Nomi dei pacchetti da evitare: non utilizzare io.apigee o com.apigee come nomi dei pacchetti nelle norme JavaCallout. Questi sono riservati e utilizzati da altri moduli Apigee.
  • Se il criterio JavaCallout si basa su librerie di terze parti aggiuntive pacchettizzate come file JAR indipendenti, inserisci questi file JAR anche nella directory /resources/java per assicurarti che vengano caricati correttamente in fase di runtime.
  • Se sono presenti più file JAR, aggiungili come risorse aggiuntive. Non è necessario modificare la configurazione dei criteri per fare riferimento a file JAR aggiuntivi. Inserirli in /resources/java è sufficiente.
  • Per ulteriori informazioni sul caricamento di file JAR Java, consulta File di risorse.