Norme sui callout Java

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Consente di utilizzare Java per implementare un comportamento personalizzato che non è pronto all'uso criteri di Apigee. Nel codice Java, puoi accedere alle proprietà dei messaggi (intestazioni, parametri di query, contenuti) e variabili di flusso nel flusso proxy. Se hai iniziato da poco a usare queste norme, consulta l'articolo Come creare un'applicazione callout.

Per le versioni supportate di Java, consulta la sezione Supportato software e le versioni supportate.

Quando

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

Informazioni

Le norme relative ai callout Java consentono di recuperare e impostare variabili di flusso, eseguire logica personalizzata gestione degli errori, estrarre dati da richieste o risposte e altro ancora. Questo criterio consente di implementare un comportamento personalizzato che non sia coperto da altri criteri Edge standard.

Puoi pacchettizzare la tua applicazione Java con qualsiasi file JAR di pacchetto di cui hai bisogno. Nota su ciò che puoi fare con un callout Java. Questi sono elencati di seguito in Restrizioni.

Esempi

Esempio semplice

Come creare una finestra di dialogo Java callout

Recupera le proprietà nel codice Java

L'elemento <Property> del criterio consente di specificare un nome/valore recuperabile in fase di runtime nel codice Java. Per un esempio funzionante che utilizza proprietà, consulta Come utilizzare le proprietà in un callout Java.

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

  • 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 nella classe Execution implementazione nel seguente modo:
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

Imposta variabili di flusso nel codice Java

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

Riferimento elemento

Il riferimento agli elementi descrive gli elementi e gli attributi del criterio JavaCallout.

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

&lt;JavaCallout&gt; attributi

<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

&lt;ClassName&gt; elemento

Specifica il nome della classe Java che viene eseguita quando viene eseguito il criterio callout Java. La deve essere inclusa nel file JAR specificato dall'<ResourceURL>. Consulta anche come creare un'applicazione callout.

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

&lt;Property&gt; elemento

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

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

Attributi

Attributo Descrizione Predefinito Presenza
nome

Specifica il nome della proprietà.

 N/D Obbligatorio.

&lt;ResourceURL&gt; elemento

Questo elemento specifica il file JAR Java che verrà eseguito quando viene applicato il criterio di callout Java viene eseguito.

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

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Predefinita: 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 maggiori dettagli su come compilare il tuo codice Java personalizzato ed eseguirne il deployment con un proxy, consulta Come creare un callout.

Restrizioni

Di seguito sono riportate le limitazioni che devi prendere in considerazione quando scrivi callout Java:

  • La maggior parte delle chiamate di sistema non è consentita. Ad esempio, non puoi eseguire letture del file system interno o scrive.
  • Accesso alla rete tramite socket. Apigee limita l'accesso a sitelocal, anylocal, loopback e indirizzi linklocal.
  • Il callout non può ottenere informazioni sul processo corrente, sull'elenco dei processi o Utilizzo di CPU/memoria sulla macchina. Sebbene alcune di queste chiamate possano essere funzionali, non sono supportati e potrebbero essere disattivati attivamente in qualsiasi momento. Per la compatibilità con le versioni future, non effettuare chiamate di questo tipo nel codice.
  • L'utilizzo delle librerie Java incluse in Apigee Edge non è supportato. Quelli librerie sono solo per le funzionalità del prodotto Edge e non esiste alcuna garanzia che una libreria siano disponibili da una release all'altra.
  • Non utilizzare io.apigee o com.apigee come nomi dei pacchetti in Java Callout. Questi nomi sono riservati e utilizzati da altri moduli Apigee.

Imballaggio

Inserisci il JAR in un proxy API in /resources/java. Se il callout Java si basa su librerie di terze parti aggiuntive pacchettizzate come file JAR indipendenti, quindi inserisci questi file JAR anche nella directory /resources/java per verificare che vengano caricati correttamente all' runtime.

Se utilizzi l'interfaccia utente di gestione per creare o modificare il proxy, aggiungi una nuova risorsa e per specificare un file JAR dipendente aggiuntivo. Se ci sono più JAR, basta aggiungerli come risorse aggiuntive. Non è necessario modificare la configurazione dei criteri per fare riferimento ad altri JAR. È sufficiente inserirli in /resources/java.

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

Per un esempio dettagliato che dimostra come pacchettizzare e distribuire un callout Java utilizzando Maven o javac, consulta la sezione Come creare un callout Java.

Javadoc

Javadoc per la scrittura del codice callout Java è incluso qui GitHub. Dovrai clonare o scaricare il codice HTML sul tuo sistema, quindi aprire semplicemente il index.html in un browser.

Note sull'utilizzo

  • Un criterio callout Java non contiene codice effettivo. Un criterio callout Java fa invece riferimento a un "resource" Java e definisce il passaggio nel flusso API in cui viene eseguito il codice Java. Puoi caricare il JAR Java tramite l'editor proxy dell'interfaccia utente di gestione oppure includerlo nella Directory /resources/java nei proxy API che sviluppi localmente.
  • Per operazioni leggere, come le chiamate API ai servizi remoti, consigliamo di utilizzare ServiceCallout. Consulta le norme relative ai callout di servizio.
  • Per interazioni relativamente semplici con il contenuto dei messaggi, come la modifica o l'estrazione Intestazioni, parametri o contenuti dei messaggi HTTP, Apigee consiglia di utilizzare un criterio JavaScript.

Argomenti correlati