Criterio JavaCallout

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

La norma JavaCallout consente di utilizzare Java per implementare un comportamento personalizzato non incluso per impostazione predefinita nelle norme Apigee. Nel codice Java puoi accedere alle proprietà dei messaggi (intestazioni, parametri di ricerca, contenuti), ottenere e impostare le variabili di flusso, eseguire logica personalizzata ed eseguire la gestione degli errori, estrarre dati da richieste o risposte e altro ancora. Se hai appena iniziato a utilizzare queste norme, consulta Come creare un callout Java.

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

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

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

Esempi

Esempi generali

Per un esempio semplice che utilizza un callout Java, vedi Come creare un callout Java.

Per scoprire come impostare le variabili di flusso nel codice Java, consulta questo post della community Apigee sul debug dei callout Java.

Recuperare le proprietà nel codice Java

Questo esempio mostra come utilizzare 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.

La configurazione richiede due elementi:

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>
</JavaCallout>

Nel codice Java, implementa il seguente costruttore nella classe Execution:

public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){

            // Extract property values from map.
    }
    ...
}

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 delle policy:

Attributo	Descrizione	Predefinito	Presenza
`name`	Il nome interno della policy. 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'UI di gestione con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
`continueOnError`	Imposta `false` per restituire un errore quando un criterio non viene rispettato. Questo è il comportamento previsto per la maggior parte delle norme. Imposta `true` per continuare l'esecuzione del flusso anche dopo l'errore di un criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori nel flusso corrente Suggerimento : nei casi in cui il codice Java genera un'eccezione, il flusso del proxy Apigee passa allo stato di errore anche se l'attributo `continueOnError` è impostato su true. Se non vuoi che un'eccezione generata comporti uno stato di errore nel proxy, progetta il codice di callout Java in modo che non generi errori. Al contrario, intercetta le eccezioni e imposta una variabile di contesto per acquisire le informazioni sull'eccezione. Per maggiori informazioni, consulta questo post della community Apigee.	falso	Facoltativo
`enabled`	Imposta su `true` per applicare la policy. Imposta su `false` per disattivare il criterio. La norma non verrà applicata anche se rimane collegata a un flusso.	true	Facoltativo
`async`	Questo attributo è stato ritirato.	falso	Deprecato

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Predefinito

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

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>

Valore 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>

Valore 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 stringa letterale 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>

Valore 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>

Valore 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

Esempio:ogni tipo di criterio è definito da uno schema XML (.xsd). Per riferimento, gli schemi dei criteri sono disponibili su GitHub.

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 callout Java:

La maggior parte delle chiamate di sistema non sono consentite. 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 solo 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 pacchettizzate 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, vedi File di risorse.

Per un esempio dettagliato che mostra come creare pacchetti e implementare le norme 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. Devi clonare o scaricare l'HTML sul tuo sistema, quindi 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 quando viene eseguito 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 file JAR come parte di un bundle di proxy e come risorsa di ambiente.
- Deployment di una versione di un file JAR come risorsa dell'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 le chiamate API a servizi remoti, ti 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 HTTP, parametri o contenuti dei messaggi, Apigee consiglia di utilizzare una norma JavaScript.