Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Cosa
Consente di utilizzare Java per implementare un comportamento personalizzato non incluso immediatamente nei criteri di Apigee. Nel codice Java, puoi accedere alle proprietà dei messaggi (intestazioni, parametri di query, contenuti) e alle variabili di flusso nel flusso proxy. Se hai appena iniziato a utilizzare questo criterio, consulta Come creare un callout Java.
Per le versioni supportate di Java, vedi Software e versioni supportate.
Quando
Per le linee guida, consulta la sezione "Quando devo utilizzare un callout Java?" in Come creare un callout Java.
Informazioni
Il criterio dei callout Java ti consente di ottenere e impostare variabili di flusso, eseguire logiche personalizzate ed eseguire la gestione degli errori, estrarre dati da richieste o risposte e altro ancora. Questo criterio consente di implementare un comportamento personalizzato che non è coperto da altri criteri Edge standard.
Puoi pacchettizzare la tua applicazione Java con qualsiasi file JAR di pacchetto di cui hai bisogno. Tieni presente che le operazioni che puoi eseguire con i callout Java sono soggette ad alcune limitazioni. Queste restrizioni sono elencate di seguito in Restrizioni.Samples
Esempio semplice
Come creare un callout JavaRecupera le proprietà nel tuo codice Java
L'elemento <Property>
del criterio consente di specificare una coppia nome/valore che puoi recuperare in fase di runtime nel tuo codice Java. Per un esempio funzionante che utilizza
le proprietà, consulta Come utilizzare le proprietà
in un callout Java.
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 il tag di apertura e quello di 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 ottenerlo.
- Configura la proprietà. Qui, 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 di esecuzione 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 chiara descrizione 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 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 della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorie |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
false | Deprecata |
Elemento <DisplayName>
Utilizzalo 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/A Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
Elemento <ClassName>
Specifica il nome della classe Java che viene eseguita quando viene eseguito il criterio Callout Java. 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/A |
Presenza: | Obbligatorie |
Tipo: | Stringa |
Elemento <Property>
Specifica una proprietà a cui puoi accedere dal codice Java in fase di runtime. Devi specificare un valore stringa letterale per ogni proprietà; non puoi fare riferimento a variabili di flusso in questo elemento. Per un esempio funzionante che utilizza le proprietà, consulta Come utilizzare le proprietà in un callout Java.
<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/A | Obbligatorio. |
Elemento<ResourceURL>
Questo elemento specifica il file JAR Java che verrà eseguito quando viene eseguito il criterio di callout Java.
Puoi archiviare questo file nell'ambito del proxy API (in /apiproxy/resources/java
nel pacchetto del proxy API o nella sezione Script del riquadro di navigazione dell'editor proxy API) oppure nell'ambito 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: | Obbligatorie |
Tipo: | Stringa |
Messaggi di errore
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
Codice di errore | 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 criterio JavaCallout. | build |
Errori di deployment
Questi errori possono verificarsi quando viene eseguito il deployment del proxy che contiene il criterio.
Nome errore | Stringa di errore | Stato HTTP | Si verifica quando |
---|---|---|---|
ResourceDoesNotExist |
Resource with name
[name] and type [type] does not exist |
N/A | Il file specificato nell'elemento <ResourceURL> non esiste. |
JavaCalloutInstantiationFailed |
Failed to instantiate the JavaCallout Class [classname] |
N/A | Il file della classe specificato nell'elemento <ClassName> non è nel file jar. |
IncompatibleJavaVersion |
Failed to load java class [classname] definition due to - [reason] |
N/A | Vedi stringa di errore. Vedi anche Software supportato e versioni supportate. |
JavaClassNotFoundInJavaResource |
Failed to find the ClassName in java resource [jar_name] -
[class_name] |
N/A | Vedi stringa di errore. |
JavaClassDefinitionNotFound |
Failed to load java class [class_name] definition due to - [reason] |
N/A | Vedi stringa di errore. |
NoAppropriateConstructor |
No appropriate constructor found in JavaCallout class [class_name] |
N/A | Vedi stringa di errore. |
NoResourceForURL |
Could not locate a resource with URL [string] |
N/A | Vedi stringa di errore. |
Variabili di errore
Queste variabili vengono impostate quando questo criterio attiva un errore. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori relativi ai criteri.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di 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 ed eseguirne il deployment con un proxy, vedi Come creare un callout Java.
Restrizioni
Di seguito sono riportate alcune limitazioni che è necessario tenere presenti quando si scrivono callout Java:
- La maggior parte delle chiamate di sistema non è consentita. Ad esempio, non puoi eseguire letture o scritture nel file system interno.
- Accesso alla rete tramite socket. Apigee limita l'accesso a indirizzi sitelocal, anylocal, loopback e linklocal.
- Il callout non può ottenere informazioni sul processo attuale, sull'elenco dei processi o sull'utilizzo di CPU/memoria nella macchina. Sebbene alcune di queste chiamate possano funzionare, non sono supportate e potrebbero essere attivamente disattivate in qualsiasi momento. Per compatibilità con le deviazioni, dovresti evitare di effettuare chiamate di questo tipo nel tuo codice.
- L'utilizzo delle librerie Java incluse in Apigee Edge non è supportato. Queste librerie sono destinate solo alla funzionalità del prodotto Edge e non vi è alcuna garanzia che una libreria sarà disponibile da una release all'altra.
- Non utilizzare
io.apigee
ocom.apigee
come nomi dei pacchetti nei callout Java. Questi nomi sono riservati e utilizzati da altri moduli Apigee.
Presentazione
Inserisci il JAR in un proxy API nel campo /resources/java
. 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 utilizzi l'interfaccia utente di gestione per creare o modificare il proxy, aggiungi una nuova risorsa e specifica un altro file JAR dipendente. 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 inserirle in /resources/java
.
Per informazioni sul caricamento di JAR Java, consulta File di risorse.
Per un esempio dettagliato che mostra come pacchettizzare ed eseguire il deployment di un callout Java utilizzando Maven o javac, consulta Come creare un callout Java.
Javadoc
Javadoc per la scrittura di codice callout Java è incluso qui su GitHub. Dovrai clonare o scaricare l'HTML sul tuo sistema, quindi aprire il file index.html in un browser.
Note sull'utilizzo
- I criteri relativi ai callout Java non contengono codice. Invece, un criterio di callout Java fa riferimento a una "risorsa" Java e definisce lo step nel flusso dell'API in cui viene eseguito il codice Java. 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. - Per le operazioni leggere, come le chiamate API ai servizi remoti, consigliamo di utilizzare il 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, Apigee consiglia di utilizzare un criterio JavaScript.
Argomenti correlati
- Per gli esempi correlati, consulta il repository java-cookbook.