Criterio JavaCallout

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Consente di utilizzare Java per implementare un comportamento personalizzato non incluso per impostazione predefinita nei criteri Apigee. Nel codice Java, puoi accedere alle proprietà del messaggio (intestazioni, parametri di ricerca, contenuto) e alle variabili di flusso nel flusso proxy. Se hai appena iniziato a utilizzare queste norme, consulta Come creare un callout Java.

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

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Quando

Per le linee guida, vedi "Quando devo utilizzare JavaCallout?" in Come creare un callout Java.

Informazioni

Il criterio JavaCallout consente di ottenere e impostare variabili di flusso, eseguire logica personalizzata ed eseguire la gestione degli errori, estrarre dati da richieste o risposte e altro ancora. Questa policy ti consente di implementare un comportamento personalizzato non coperto da altre policy Apigee standard.

Puoi creare il pacchetto della tua applicazione Java con i file JAR del pacchetto che ti servono. Nota che esistono alcune limitazioni su ciò che puoi fare con JavaCallout. Questi sono elencati di seguito in Limitazioni.

Esempi

Esempio semplice

Come creare un callout Java

Recuperare le proprietà nel codice Java

L'elemento <Property> del criterio ti consente di specificare una coppia nome/valore che puoi recuperare in fase di runtime nel codice Java. Per un esempio pratico che utilizza le proprietà, consulta Come utilizzare le proprietà nelle norme JavaCallout.

Utilizza l'attributo name dell'elemento <Property> per specificare il nome con cui accedere alla proprietà dal codice Java. Il valore dell'elemento <Property> (il valore tra i tag di apertura e chiusura) è il valore che verrà ricevuto dal codice Java. Il valore deve essere una stringa; non puoi fare riferimento a una variabile di flusso per ottenere il valore.

  • Configura la proprietà. In questo caso, il valore della proprietà è il nome della variabile response.status.code. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • Nel codice Java, implementa il seguente costruttore nell'implementazione della classe Execution come segue:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Impostare le variabili di flusso nel codice Java

Per una descrizione chiara di come impostare le variabili nel contesto del messaggio (variabili di flusso) nel codice Java, consulta questo post della community Apigee.

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio JavaCallout.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

Attributi <JavaCallout>

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presenza
name

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta questo valore su false per restituire un errore quando un criterio non viene rispettato. Questo è il comportamento previsto per la maggior parte delle norme.

Imposta su true per continuare l'esecuzione del flusso anche dopo l'esito negativo di un criterio. Vedi anche:

 falso Facoltativo
enabled

Imposta true per applicare la policy.

Imposta false su Off per disattivare il criterio. La norma non verrà applicata anche se rimane allegata a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Ritirato

Elemento <DisplayName>

Utilizza questo attributo in aggiunta all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/D

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza Facoltativo
Tipo Stringa

Elemento <ClassName>

Specifica il nome della classe Java che viene eseguita quando viene eseguita la policy JavaCallout. La classe deve essere inclusa nel file JAR specificato da <ResourceURL>. Vedi anche Come creare un callout Java.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Predefinito: N/D
Presenza: Obbligatorio
Tipo: Stringa

Elemento <Properties>

Aggiunge nuove proprietà a cui puoi accedere dal codice Java in fase di runtime.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Predefinito: Nessuno
Presenza: Facoltativo
Tipo: Stringa

Elemento <Property>

Specifica una proprietà a cui puoi accedere dal codice Java in fase di runtime. Devi specificare un valore letterale della stringa per ogni proprietà; non puoi fare riferimento alle variabili di flusso in questo elemento. Per un esempio funzionante che utilizza le proprietà, consulta Come utilizzare le proprietà in un criterio JavaCallout.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Predefinito: Nessuno
Presenza: Facoltativo
Tipo: Stringa

Attributi

Attributo Descrizione Predefinito Presenza
nome

Specifica il nome della proprietà.

 N/D Obbligatorio.

Elemento<ResourceURL>

Questo elemento specifica il file JAR Java che verrà eseguito quando viene eseguita la policy JavaCallout.

Puoi archiviare questo file nell'ambito del proxy API (in /apiproxy/resources/java nel bundle del proxy API o nella sezione Script del riquadro di navigazione dell'editor del proxy API) oppure negli ambiti dell'organizzazione o dell'ambiente per il riutilizzo in più proxy API, come descritto in File di risorse.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Predefinito: Nessuno
Presenza: Obbligatorio
Tipo: Stringa

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Causa Correggi
steps.javacallout.ExecutionError 500 Si verifica quando il codice Java genera un'eccezione o restituisce null durante l'esecuzione di un JavaCallout policy.

Errori di deployment

Questi errori possono verificarsi durante il deployment del proxy contenente il criterio.

Nome dell'errore Stringa di errore Stato HTTP Si verifica quando
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/D Il file specificato nell'elemento <ResourceURL> non esiste.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/D Il file della classe specificato nell'elemento <ClassName> non è nel jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/D Vedi la stringa di errore. Le versioni Java supportate includono: Oracle JDK 7/8 e OpenJDK 7/8
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/D Vedi la stringa di errore.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/D Vedi la stringa di errore.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/D Vedi la stringa di errore.
NoResourceForURL Could not locate a resource with URL [string] N/D Vedi la stringa di errore.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. javacallout.JC-GetUserData.failed = true

Esempio di risposta di errore

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Esempio di regola di errore

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

Schemi

Compilazione e deployment

Per informazioni dettagliate su come compilare il codice Java personalizzato e implementarlo con un proxy, consulta Come creare un callout Java.

Limitazioni

Di seguito sono riportate le limitazioni da considerare quando scrivi il codice di callout Java:

  • La maggior parte delle chiamate di sistema non è consentita. Ad esempio, non puoi eseguire letture o scritture del file system interno.
  • Accesso alla rete tramite socket. Apigee limita l'accesso agli indirizzi sitelocal, anylocal, loopback e linklocal.
  • Il callout non può ottenere informazioni sul processo corrente, sull'elenco dei processi o sull'utilizzo di CPU/memoria sulla macchina. Sebbene alcune di queste chiamate possano essere funzionali, non sono supportate e possono essere disattivate attivamente in qualsiasi momento. Per la compatibilità futura, ti consigliamo di evitare di effettuare queste chiamate nel tuo codice.
  • L'utilizzo di librerie Java incluse in Apigee non è supportato. Queste librerie sono destinate esclusivamente alla funzionalità del prodotto Apigee e non è garantito che una libreria sia disponibile da una release all'altra.
  • Non utilizzare io.apigee o com.apigee come nomi di pacchetti nei callout Java. Questi nomi sono riservati e utilizzati da altri moduli Apigee.

Imballaggio

Inserisci il file JAR in un proxy API in /resources/java. Se il codice JavaCallout si basa su librerie di terze parti aggiuntive incluse in pacchetti come file JAR indipendenti, inserisci questi file JAR anche nella directory /resources/java per assicurarti che vengano caricati correttamente in fase di runtime.

Se utilizzi la UI di gestione per creare o modificare il proxy, aggiungi una nuova risorsa e specifica un file JAR dipendente aggiuntivo. Se ci sono più file JAR, aggiungili come risorse aggiuntive. Non è necessario modificare la configurazione dei criteri per fare riferimento a file JAR aggiuntivi. È sufficiente inserirli in /resources/java.

Per informazioni sul caricamento di file JAR Java, consulta File di risorse.

Per un esempio dettagliato che mostra come creare pacchetti ed eseguire il deployment di criteri JavaCallout utilizzando Maven o javac, consulta Come creare un callout Java.

Javadoc

La documentazione Javadoc per la scrittura del codice di callout Java è inclusa qui su GitHub. Dovrai clonare o scaricare l'HTML sul tuo sistema e poi aprire il file index.html in un browser.

Note sull'utilizzo e best practice

  • Quando lavori con più criteri JavaCallout, valuta la possibilità di caricare i file JAR comuni come risorse con ambito ambiente. Questa pratica è più efficiente rispetto al packaging degli stessi file JAR con più bundle proxy durante il deployment nello stesso ambiente.
  • Evita di creare pacchetti e di eseguire il deployment di più copie o versioni dello stesso file JAR in un ambiente. Ad esempio, Apigee consiglia di evitare:
    • Deployment dello stesso JAR come parte di un bundle di proxy e come risorsa di ambiente.
    • Deployment di una versione di un file JAR come risorsa di ambiente e di un'altra come parte di un bundle proxy.

    La presenza di più copie dello stesso file JAR distribuito può causare un comportamento non deterministico in fase di runtime a causa di potenziali conflitti di ClassLoader.

  • Un criterio JavaCallout non contiene codice effettivo. Il criterio fa invece riferimento a una "risorsa" Java e definisce il passaggio nel flusso API in cui viene eseguito il codice Java. 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.
  • Per operazioni leggere, come chiamate API 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 intestazioni HTTP, parametri o contenuti dei messaggi, Apigee consiglia di utilizzare una policy JavaScript.