Criterio JavaCallout

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

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 query, contenuti) e alle variabili di flusso nel flusso proxy. Se hai appena iniziato a utilizzare queste norme, consulta Come creare un callout Java.

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

Quando

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

Informazioni

Il criterio Java Callout 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. Queste norme ti consentono di implementare un comportamento personalizzato non coperto da altre norme standard di Edge.

Puoi creare il pacchetto della tua applicazione Java con i file JAR del pacchetto che ti servono. Tieni presente che esistono alcune limitazioni su ciò che puoi fare con un callout Java. Questi sono elencati di seguito nella sezione 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à 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 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 del criterio:

Attributo Descrizione Predefinito Presenza
name

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

Se vuoi, puoi utilizzare l'elemento <DisplayName> per etichettare il criterio in l'editor proxy della UI di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta il valore su false per restituire un errore quando un criterio non viene eseguito. Si tratta di un comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche dopo un criterio non riesce.

 falso Facoltativo
enabled

Imposta il valore su true per applicare il criterio.

Imposta false per disattivare il criterio. Il criterio non verrà applicata anche se rimane collegata a un flusso.

 true Facoltativo
async

Questo attributo è obsoleto.

 falso Deprecato

&lt;DisplayName&gt; elemento

Da utilizzare in aggiunta all'attributo name per etichettare il criterio in editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/D

Se ometti questo elemento, il valore dell'attributo name del criterio è in uso.
Presenza Facoltativo
Tipo Stringa

Elemento <ClassName>

Specifica il nome della classe Java che viene eseguita quando viene eseguita la norma 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/D
Presenza: Obbligatorio
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 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/D Obbligatorio.

Elemento <ResourceURL>

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

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 e i messaggi di errore restituiti, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per per gestire gli errori. Per saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.

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 un valore nullo durante l'esecuzione di un criterio JavaCallout.

Errori di deployment

Questi errori possono verificarsi quando viene eseguito il deployment del proxy contenente il criterio.

Nome errore Stringa 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 è in barattolo.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/D Vedi stringa errore. Vedi anche Contenuti supportati software e le versioni supportate.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/D Vedi stringa errore.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/D Vedi stringa errore.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/D Vedi stringa errore.
NoResourceForURL Could not locate a resource with URL [string] N/D Vedi stringa errore.

Variabili di errore

Queste variabili vengono impostate quando il criterio attiva un errore. Per ulteriori informazioni, vedi Cosa devi sapere sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come elencato nella precedente tabella Errori di runtime. Il nome dell'errore è 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 e implementarlo con un proxy, consulta Come creare un callout Java.

Restrizioni

Di seguito sono riportate le limitazioni da considerare quando scrivi 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 Edge non è supportato. Queste librerie sono destinate solo alla funzionalità del prodotto Edge e non è garantito che una libreria sarà disponibile da una release all'altra.
  • Non utilizzare io.apigee o com.apigee come nomi dei 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 tuo callout Java 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 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 un callout Java utilizzando Maven o javac, vedi 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

  • Un criterio callout Java non contiene codice effettivo. Un criterio Java Callout 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 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 policy JavaScript.

Argomenti correlati