Norme sui callout Java

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 Java

Recupera 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 name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

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

 N/A Obbligatorie
continueOnError

Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio.

 false Facoltativo
enabled

Imposta il criterio su true per applicare il criterio.

Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.

 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 name del criterio.
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.

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 o com.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