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 serie 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 l'API richiede un comportamento personalizzato non implementato in un criterio standard. In questi casi, Apigee offre diverse opzioni che ti consentono di eseguire script o di codificare il comportamento dell'API personalizzato. Un approccio è 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?

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

Quando devo utilizzare un callout Java?

Vediamo le situazioni in cui i callout Java sono utili e quelle in cui dovresti considerare altri approcci.

Innanzitutto, valuta approcci alternativi

Prima di utilizzare un callout Java, tieni presente che potresti avere a disposizione approcci alternativi. Ad esempio:

  • Per operazioni leggere, come le chiamate API HTTP a servizi remoti, ti consigliamo 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 parametri, intestazioni HTTP o contenuti dei messaggi, puoi utilizzare i criteri JavaScript o PythonScript.

Cosa puoi fare nel codice Java

Un callout Java supporta queste operazioni di base:

  • Esaminare o manipolare i messaggi di richiesta o risposta
  • Ottenere e impostare le variabili di flusso. Puoi utilizzare i metodi Java per accedere alle variabili del flusso Apigee. Se vuoi accedere alle informazioni della mappa chiave/valore (KVM), utilizza un criterio KVM, assegna i valori KVM alle variabili di flusso e poi potrai accedere alle variabili di flusso da all'interno del callout Java.
  • Chiamate a servizi esterni
  • Segnalazione di errori
  • Manipolare i messaggi di errore e i codici di stato

Cosa non puoi fare nel codice Java

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

  • Esegui 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 della CPU/memoria sulla macchina.
  • Accedi al codice sorgente in expressions-1.0.0.jar e message-flow-1.0.0.jar.

Sebbene alcune di queste chiamate possano funzionare, non sono supportate e potrebbero essere disattivate attivamente in qualsiasi momento. Evita di effettuare chiamate di questo tipo nel codice.

Non utilizzare né fare affidamento sulle librerie Java incluse in Apigee. Queste librerie sono unicamente per la funzionalità dei prodotti Apigee e non è garantito che una libreria sarà disponibile da una release all'altra. Se utilizzi queste librerie, utilizzale solo per dimostrazioni non in produzione.

Callout Java di Hello

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

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

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

    "Hello, Guest!"

Scarica il progetto iniziale

Per semplificare, 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 tuo sistema, esegui pull per assicurarti di avere la versione più recente.
  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 scheletro della classe Java principale che implementeremo. I pacchetti importati sono obbligatori per il codice di callout Java di Apigee. Queste classi forniscono metodi che ti consentono di accedere al contesto di esecuzione del proxy. A breve illustreremo 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 avere installato Maven:

    mvn -version
  2. Installa le dipendenze JAR richieste nel tuo 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 necessarie 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

Per eseguire il deployment e il test del 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 del proxy in un ambiente della tua organizzazione Apigee. Consulta la sezione Creare un proxy API. Assicurati di utilizzare l'opzione Carica pacchetto proxy. Consulta anche Suggerimenti e trucchi per il caricamento del proxy API in un bundle di proxy nella community Apigee.
  4. Dopo aver eseguito il deployment del proxy, prova a chiamarlo:
    curl  https://$HOSTNAME/java-hello -H "username:Will"

    che restituisce "Ciao, Will!

Informazioni sul proxy

Esaminiamo rapidamente i criteri utilizzati in questo proxy. Presta attenzione a dove sono posizionati i criteri nel flusso del proxy e perché.

Criterio Assegna messaggio

Un criterio di assegnazione dei messaggi è associato al flusso di richieste ProxyEndpoint. Copia l'intestazione del nome utente dalla richiesta e la assegna alla risposta. Questa operazione consente al criterio di callout Java, associato al flusso di risposta, di accedere all'intestazione del nome utente e di 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 relative ai callout Java

Il criterio callout Java è associato al flusso di risposta. Questo accade perché il codice Java personalizzato apporta modifiche alle intestazioni e al messaggio di risposta. L'elemento ClassName del criterio specifica la classe principale eseguita dal criterio. 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 callout Java

Di seguito sono riportati alcuni aspetti importanti da ricordare sull'implementazione di un callout Java:

  • Importa i corsi dai pacchetti com.apigee.flow.execution e com.apigee.flow.message. Questi pacchetti devono essere inclusi nel file JAR che viene pacchettizzato e di cui viene eseguito il deployment. Puoi caricare il file JAR Java tramite l'editor del proxy dell'interfaccia utente di gestione o 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 l'esecuzione.
  • Un criterio callout Java non contiene codice effettivo. Un criterio callout Java fa invece riferimento a una "risorsa" Java, che devi pacchettizzare in un file JAR.
  • Nomi di pacchetti da evitare: non utilizzare io.apigee o com.apigee come nomi di pacchetti nei callout Java. Questi sono riservati e utilizzati da altri moduli Apigee.
  • Se il callout Java si basa su librerie di terze parti aggiuntive pacchettizzate come file JAR indipendenti, posiziona anche questi file JAR nella directory /resources/java per assicurarti che vengano caricati correttamente in fase di esecuzione.
  • Se sono presenti più JAR, aggiungili semplicemente 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 dei file JAR Java, consulta File di risorse.