Norme per i callout Java

Stai visualizzando la documentazione di Apigee X.
Visualizza la documentazione di Apigee Edge.

icona delle norme

Cosa

Consente di utilizzare Java per implementare comportamenti personalizzati non inclusi immediatamente per i criteri Apigee. Nel tuo codice Java, puoi accedere alle proprietà del messaggio (intestazioni, parametri di ricerca, contenuti) e alle variabili di flusso nel flusso proxy. Se hai appena iniziato a utilizzare questo criterio, consulta l'articolo su come creare un callout Java.

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

Quando

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

Informazioni

Il criterio Callout Java ti consente di ottenere e impostare variabili di flusso, eseguire logiche personalizzate ed eseguire la gestione degli errori, estrarre i dati dalle richieste o dalle risposte e altro ancora. Questo criterio consente di implementare un comportamento personalizzato che non è coperto da altri criteri Apigee standard.

Puoi pacchettizzare l'applicazione Java con qualsiasi file JAR di cui hai bisogno. Tieni presente che esistono alcune limitazioni relative alle operazioni che puoi eseguire con un callout Java. Di seguito è riportata la sezione Restrizioni.

Esempi

Esempio semplice

Come creare un callout Java

Recuperare le proprietà nel tuo codice Java

L'elemento <Property> del criterio consente di specificare una coppia nome/valore che puoi recuperare in fase di esecuzione nel tuo codice Java. Per un esempio pratico che utilizza le proprietà, consulta la sezione Come utilizzare le proprietà in un callout Java.

Utilizza l'attributo name <Proprietà> elemento's per specificare il nome con il quale 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 di Apigee.

Riferimento elemento

Il riferimento elemento descrive gli elementi e gli attributi del criterio Java callout.

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

<JavaCallout> attributi

<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 Obbligatorio
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. Vedi anche:

 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

<ClassName> elemento

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>. Consulta anche l'articolo 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>

Specifica una proprietà a cui puoi accedere dal codice Java in fase di esecuzione. Devi specificare un valore stringa letterale per ogni proprietà. Non puoi fare riferimento a variabili di flusso in questo elemento. Per un esempio pratico che utilizza le proprietà, consulta la sezione Come utilizzare le proprietà in un callout Java.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
Predefinito: Nessuna
Presenza: Facoltativo
Tipo: Stringa

Attributi

Attributo Descrizione Predefinito Presenza
name

Specifica il nome della proprietà.

 N/A Obbligatorio.

<ResourceURL> elemento

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

Puoi archiviare questo file nell'ambito del proxy API (sotto /apiproxy/resources/java nel bundle proxy dell'API o nella sezione Script del riquadro Navigator dell'editor proxy API) o nell'ambito dell'organizzazione o dell'ambiente per riutilizzarlo in più proxy API, come descritto nella sezione File delle risorse.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
Predefinito: Nessuna
Presenza: Obbligatorie
Tipo: Stringa

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore che vengono restituiti e le variabili di errore impostate da Apigee 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 JavaCallout policy.

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. 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/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 tuo codice Java personalizzato ed eseguirne il deployment con un proxy, consulta l'articolo Come creare un callout Java.

Restrizioni

Di seguito sono riportate le limitazioni da tenere in considerazione durante la scrittura dei callout Java:

  • La maggior parte delle chiamate di sistema non è consentita. Ad esempio, non puoi eseguire operazioni di lettura o scrittura sul file system interno.
  • Accesso alla rete tramite socket. Apigee limita l'accesso agli indirizzi sitelocal, anylocal, di loopback e di linklocal.
  • Il callout non può ricevere informazioni sul processo corrente, sull'elenco dei processi o sull'utilizzo di CPU e memoria sul computer. Alcune chiamate di questo tipo potrebbero essere funzionali, ma non sono supportate e potrebbero essere disattivate attivamente in qualsiasi momento. Per una maggiore compatibilità, devi evitare di effettuare chiamate di questo tipo nel tuo codice.
  • La dipendenza dalle librerie Java incluse in Apigee non è supportata. Queste librerie sono solo per la funzionalità del prodotto Apigee e non vi è alcuna garanzia che sia disponibile una libreria da release a release.
  • Non utilizzare io.apigee o com.apigee come nomi di pacchetti nei callout Java. Questi nomi sono riservati e utilizzati da altri moduli Apigee.

Confezionamento

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

Se utilizzi l'interfaccia utente di gestione per creare o modificare il proxy, aggiungi una nuova risorsa e specifica un file JAR dipendente aggiuntivo. Se sono presenti più JAR, aggiungile 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 dei file JAR di Java, consulta la sezione File delle risorse.

Per un esempio dettagliato che mostra come pacchettizzare ed eseguire il deployment di un callout Java utilizzando Maven o javac, consulta la sezione Come creare un callout Java.

Documento Java

Javadoc per la scrittura del codice callout Java è incluso qui su GitHub. Dovrai clonare o scaricare l'HTML nel sistema e quindi aprire il file index.html in un browser.

Note sull'utilizzo e best practice

  • Quando lavori con più callout Java, valuta la possibilità di caricare i JAR comuni come risorse con ambito ambientale. Questa pratica è più efficiente rispetto al pacchettizzazione degli stessi JAR con più proxy proxy quando si esegue il deployment nello stesso ambiente.
  • Evita il pacchettizzazione e il deployment di più copie o versioni dello stesso file JAR in un ambiente. Ad esempio, Apigee consiglia di evitare di:
    • Deployment della stessa JAR come parte di un bundle proxy e come risorsa di ambiente.
    • Deployment di una versione di un file JAR come risorsa di ambiente e di un'altra come parte di un bundle proxy.

    Avere più copie dello stesso JAR di cui è stato eseguito il deployment può causare un comportamento non deterministico in fase di runtime a causa di potenziali conflitti di ClassLoad.

  • Un criterio di callout Java non contiene alcun codice effettivo. Invece, un criterio di callout Java fa riferimento a un Java & resource33; e definisce il passaggio nel flusso API in cui viene eseguito il codice Java. Puoi caricare la tua JAR Java tramite l'editor proxy dell'interfaccia utente di gestione o puoi includerla nella directory /resources/java nei proxy API che sviluppi localmente.
  • Per operazioni leggere, come le chiamate API ai servizi remoti, consigliamo di utilizzare il criterio callout callout. Consulta le norme sui callout di servizio.
  • Per interazioni relativamente semplici con i contenuti dei messaggi, ad esempio la modifica o l'estrazione di intestazioni, parametri o contenuti dei messaggi HTTP, Apigee consiglia di utilizzare un criterio JavaScript.