Questa pagina è stata tradotta dall'API Cloud Translation.

Come creare un callout Java

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Che cos'è un callout Java?

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

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

Per le versioni supportate di Java, vedi Software e versioni supportate.

Come faccio a utilizzare il codice Java in un proxy?

Un criterio di callout Java consente di chiamare codice Java da un flusso proxy in esecuzione. Il tuo codice Java deve implementare alcune interfacce Java specifiche per Edge 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à nell'attuale contesto di flusso del proxy.

Quando devo utilizzare un callout Java?

Vediamo le situazioni in cui i callout Java sono utili e quelle in cui devi prendere in considerazione altri approcci.

Per prima cosa, valuta approcci alternativi

Prima di utilizzare un callout Java, tieni presente che potrebbero essere disponibili approcci alternativi. Ad esempio:

Per le operazioni leggere, come le chiamate API HTTP ai servizi remoti, valuta l'utilizzo del criterio ServiceCallout. Consulta le norme sui callout di servizio.
Per interazioni relativamente semplici con i contenuti dei messaggi, come la modifica o l'estrazione di intestazioni, parametri o contenuti dei messaggi HTTP, puoi utilizzare linguaggi JavaScript o Python.

Cosa puoi fare nel codice Java

Un callout Java supporta queste operazioni di base:

Esame o manipolazione dei messaggi di richiesta o risposta
Recupero e impostazione delle variabili di flusso. Puoi utilizzare i metodi Java per accedere alle variabili di flusso Edge. Se vuoi accedere alle informazioni della mappa KVM, utilizza un criterio KVM, assegna valori KVM alle variabili di flusso, quindi puoi accedere alle variabili di flusso dall'interno del callout Java.
Chiamata a servizi esterni
Falsa sollevazione
Modifica 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 è possibile:

Esegui operazioni di lettura o scrittura sul file system interno. Ciò significa che non puoi utilizzare alcun pacchetto Java per la lettura/scrittura nei file system interni, ma puoi effettuare chiamate remote esterne.
Ottieni informazioni sul processo attuale, sull'elenco dei processi o sull'utilizzo di CPU/memoria nella 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 attivamente disattivate in qualsiasi momento. Evita di effettuare chiamate di questo tipo nel codice.

Non utilizzare o non fare affidamento sulle librerie Java incluse in Apigee Edge. Queste librerie sono destinate esclusivamente alla funzionalità del prodotto Edge e non vi è alcuna garanzia che una libreria sarà disponibile da una release all'altra. Se utilizzi queste librerie, usale solo in dimostrazioni non di produzione.

Ciao callout Java

Esaminiamo un esempio di base di callout Java hello world. In questo esempio, viene creato 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:
```
"Hello, Guest!"
```

Scarica il progetto di partenza

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

Scarica o clona api-platform-samples sul tuo sistema.
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

Apri il file di origine Java: java-hello/callout/src/main/java/HelloJava.java. Questo file è una versione bozza della classe Java principale che implementeremo. I pacchetti importati sono necessari per il codice callout Java Edge. Queste classi forniscono metodi che consentono di accedere al contesto di esecuzione proxy. A breve esamineremo la procedura per la compilazione e il deployment di 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;
                }
        }

}

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!");
}
```
Nota: Nota: l'oggetto MessageContext consente di accedere alle entità all'interno del flusso in cui viene eseguito il criterio callout Java. Supponiamo che il criterio callout Java sia collegato al flusso Risposta endpoint proxy. Il codice elencato sopra ottiene l'oggetto HTTP Message per quel contesto del flusso. L'oggetto Messaggio, a sua volta, consente di accedere a intestazioni, parametri di query, contenuti del corpo e variabili di flusso.
Salva il file.

Compila il codice con Maven

Il progetto è configurato in modo da poter eseguire la compilazione con Maven. Se vuoi utilizzare javac, includeremo un esempio che segue quello di Maven.

Assicurati di avere installato Maven:
```
mvn -version
```
Esegui lo script java-hello/buildsetup.sh. Questo script installa le dipendenze JAR necessarie nel repository Maven locale.
cd nella directory java-hello/callout.
Esegui Maven:
```
mvn clean package
```
Nota: se ricevi un errore Maven, assicurati di essere nella directory java-hello/callout.
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 obbligatoria per i file JAR di cui vuoi eseguire il deployment con un proxy.

Compilazione con javac (facoltativo)

Nella sezione precedente, potrai generare automaticamente il file Java JAR richiesto con un comando Maven. In alternativa, se vuoi utilizzare javac per compilare il codice, puoi eseguire una procedura simile a quella riportata di seguito (dalla directory java-hello). I file JAR richiesti sono forniti nella directory java-hello/lib.

CD su api-platform-samples/doc-samples/java-hello.
Assicurati che nel percorso sia presente javac.
```
javac -version
```

Esegui questo comando javac:

javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/HelloJava.java

Viene creato il comando com/apigeesample/HelloJava.class.

Crea un file JAR contenente la classe compilata nella directory apiproxy/resources/java. Questa è la posizione obbligatoria per i file JAR di cui vuoi eseguire il deployment con un proxy. Per farlo, esegui il comando seguente nella directory java-hello (non dimenticare il punto alla fine).
```
jar cvf apiproxy/resources/java/edge-custom-policy-java-hello.jar -C com .
```

Esegui il deployment e chiama il proxy

Nella directory ./java-hello è presente uno script di deployment. Ma prima di eseguirlo, devi eseguire una configurazione rapida.

CD a api-platform-samples/doc-samples/java-hello
Se non l'hai ancora fatto, apri il file ../../setup/setenv.sh e modificalo come indicato con i dati del tuo account Apigee: il tuo nome utente (l'indirizzo email associato al tuo account), il nome della tua organizzazione e il dominio che utilizzi per effettuare chiamate di gestione delle API. Ad esempio, per il cloud perimetrale, il dominio è https://api.enterprise.apigee.com; tuttavia, il dominio potrebbe essere diverso se utilizzi Edge Private Cloud.
Salva il file setenv.sh.
Esegui lo script di deployment:
```
./deploy.sh
```
Se il deployment ha esito positivo, esegui lo script di chiamata:
```
./invoke.sh
```
Lo script di chiamata chiama un comando cURL simile al seguente:
```
curl  http://$org-$env.$api_domain/java-hello -H "username:Will"
```
che restituisce "Hello, Will!

Puoi modificare lo script invoke.sh per cambiare il nome oppure, se modifichi la chiamata cURL per rimuovere l'intestazione, il comando restituisce "Hello, Guest!".

Informazioni sul proxy

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

Il criterio Assegna messaggio

Un criterio di assegnazione dei messaggi è allegato al flusso di richiesta di ProxyEndpoint. Copia l'intestazione del nome utente dalla richiesta e la assegna alla risposta. Questa operazione consente al criterio callout Java, associato al flusso di risposta, di accedere all'intestazione del nome utente e creare un corpo della risposta personalizzata utilizzando il valore dell'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 sui callout Java

Il criterio di callout Java è collegato al flusso di risposta. Questo perché il codice Java personalizzato apporta modifiche alle intestazioni e al messaggio della 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>

Cosa devi sapere sul callout Java

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

Importa le classi dai pacchetti com.apigee.flow.execution e com.apigee.flow.message. Questi pacchetti devono essere inclusi nel file JAR pacchettizzato e di cui è stato eseguito il deployment. Puoi caricare Java JAR tramite l'editor proxy dell'interfaccia utente di gestione oppure includerlo nella directory /resources/java nei proxy API che sviluppi localmente.
Implementa l'interfaccia di esecuzione. Qualsiasi codice Java eseguito all'interno di un proxy API deve implementare l'esecuzione.
I criteri relativi ai callout Java non contengono codice. Un criterio di callout Java fa invece riferimento a una "risorsa" Java, che devi pacchettizzare in un JAR.
Nomi dei pacchetti da evitare: non utilizzare io.apigee o com.apigee come nomi di pacchetto 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, inserisci anche questi file JAR nella directory /resources/java per assicurarti che vengano caricati correttamente in fase di runtime.
Se ci sono più JAR, puoi semplicemente aggiungerli come risorse aggiuntive. Non è necessario modificare la configurazione del criterio per fare riferimento a file JAR aggiuntivi. È sufficiente inserirli in /resources/java.
Per ulteriori informazioni sul caricamento dei JAR Java, consulta File di risorse.