Questa pagina è stata tradotta dall'API Cloud Translation.

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 offre una gamma di criteri che soddisfano i requisiti più comuni di gestione delle API, come sicurezza, trasformazione dei dati, gestione del traffico e altro ancora.

Tuttavia, in alcuni casi la tua 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 è implementare il comportamento desiderato in Java.

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

Come posso utilizzare il codice Java in un proxy?

Un criterio di callout Java consente di chiamare codice Java dall'interno di un flusso proxy in esecuzione. Il tuo codice Java deve implementare alcune 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à 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 è necessario prendere in considerazione altri approcci.

Innanzitutto, considera approcci alternativi

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

Per operazioni semplici, 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 HTTP, parametri o contenuti dei messaggi, puoi utilizzare i criteri JavaScript o PythonScript.

Cosa puoi fare nel codice Java

Un callout Java supporta le seguenti operazioni di base:

Esame o manipolazione dei messaggi di richiesta o risposta
Recupero e impostazione delle variabili di flusso. Puoi utilizzare metodi Java per accedere alle variabili di flusso Apigee. Per 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
Aumento degli 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 è possibile:

Effettua letture o scritture sul file system interno. Ciò significa che non puoi utilizzare nessuno dei pacchetti Java per leggere/scrivere nei file system interni, ma puoi effettuare chiamate remote esterne.
Ottieni informazioni sul processo attuale, sull'elenco di 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 disattivate attivamente in qualsiasi momento. Evita di effettuare queste chiamate nel codice.

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

Ciao callout Java

Esaminiamo un esempio di callout Java di base 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 soltanto:
```
"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 nel tuo sistema. Se hai già api-platform-samples sul sistema, esegui un pull per assicurarti di avere la versione più recente.
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 principale di Java che implementeremo. I pacchetti importati sono obbligatori per il codice callout Java di Apigee. 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 relativo ai callout Java. Supponiamo che il criterio relativo ai callout Java sia associato al flusso Risposta dell'endpoint proxy. Il codice elencato sopra ottiene l'oggetto Message HTTP per quel contesto del flusso. L'oggetto Message, a sua volta, ti consente di accedere a intestazioni, parametri di ricerca, contenuto del corpo e variabili di flusso.
Salva il file.

Compila il codice con Maven

Assicurati di aver installato Maven:
```
mvn -version
```

Installa le dipendenze JAR richieste nel repository Maven locale utilizzando uno dei seguenti metodi:

Aggiungi il seguente snippet al file pom.xml per eseguire il download delle 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.

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 richiesta per i file JAR che vuoi implementare con un proxy.

Esegui il deployment del proxy e chiamalo

Per eseguire il deployment e testare il proxy API, segui questi passaggi:

Passa alla directory java-hello.

Comprimi il bundle proxy API:

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

Il modo più semplice per eseguire il deployment del proxy è raggrupparlo in un file ZIP e caricarlo in un ambiente nella tua organizzazione Apigee. Vedi Creazione di un proxy API. Assicurati di utilizzare l'opzione Carica bundle proxy. Consulta anche i suggerimenti utili per il caricamento di proxy API in un bundle proxy nella community di Apigee.
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 i criteri utilizzati in questo proxy. Fai attenzione a dove sono posizionati i criteri nel flusso proxy e perché.

Il criterio Assegna messaggi

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

Gli aspetti importanti da notare sull'implementazione di un callout Java sono i seguenti:

Importa classi dai pacchetti com.apigee.flow.execution e com.apigee.flow.message. Questi pacchetti devono essere inclusi nel file JAR di cui si esegue il pacchetto e il deployment. Puoi caricare il tuo JAR Java tramite l'editor proxy dell'interfaccia utente di gestione oppure includerlo nella directory /resources/java nei proxy API che sviluppi in locale.
Implementa l'interfaccia di esecuzione. 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 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, aggiungili semplicemente come risorse aggiuntive. Non è necessario modificare la configurazione dei criteri per fare riferimento a file JAR aggiuntivi. Inseriscili in /resources/java è sufficiente.
Per ulteriori informazioni sul caricamento di JAR Java, consulta File di risorse.