Criterio JavaCallout

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

Cosa

Ti consente di utilizzare Java per implementare un comportamento personalizzato non incluso nelle policy di Apigee. Nel codice Java, puoi accedere alle proprietà dei messaggi (intestazioni, parametri di query, contenuti) e alle variabili di flusso nel flusso del proxy. Se hai appena iniziato a utilizzare questa policy, consulta Come creare un callout Java.

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

Quando

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

Informazioni

La policy Java Callout ti consente di recuperare e impostare le variabili di flusso, eseguire la logica personalizzata, gestire gli errori , estrarre i dati dalle richieste o dalle risposte e altro ancora. Questa policy ti consente di implementare un comportamento personalizzato non coperto da altre policy Edge standard.

Puoi creare un pacchetto della tua applicazione Java con tutti i file JAR di pacchetti di cui hai bisogno. Tieni presente che esistono alcune limitazioni su ciò che puoi fare con un callout Java. Queste sono elencate di seguito in Restrizioni.

Esempi

Semplice esempio

Come creare un callout Java

Recuperare le proprietà nel codice Java

L'elemento <Property> della policy 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 della policy 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 policy Java Callout. La classe deve essere inclusa nel file JAR specificato dal <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 pratico 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.

<ResourceURL> elemento

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

Puoi archiviare questo file nell'ambito del proxy API (in /apiproxy/resources/java nel bundle del proxy API o nella sezione Script di il riquadro di navigazione dell'editor del proxy API), o 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 ed eseguirne il deployment con un proxy, consulta Come creare un callout Java.

Restrizioni

Di seguito sono riportate le restrizioni da considerare quando scrivi callout Java:

  • La maggior parte delle chiamate di sistema non è consentita. Ad esempio, non puoi effettuare 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à con le versioni successive, devi evitare di effettuare queste chiamate nel codice.
  • L'utilizzo delle librerie Java incluse in Apigee Edge non è supportato. Queste librerie sono destinate esclusivamente alla funzionalità del prodotto Edge e non è garantita la disponibilità di una libreria 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 callout Java si basa su librerie di terze parti aggiuntive confezionate 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 file JAR dipendente aggiuntivo. Se sono presenti più file JAR, aggiungili semplicemente come risorse aggiuntive. Non è necessario modificare la configurazione della policy per fare riferimento a file JAR aggiuntivi. È sufficiente inserirli in /resources/java.

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

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

Javadoc

La documentazione Javadoc per la scrittura del codice Java Callout è inclusa qui su GitHub. Dovrai clonare o scaricare il codice HTML sul tuo sistema e poi aprire il index.html file in un browser.

Note sull'utilizzo

  • Una policy Java Callout non contiene codice effettivo. Al contrario, una policy Java Callout fa 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 del proxy dell'interfaccia utente di gestione oppure puoi includerlo nella /resources/java directory nei proxy API che sviluppi localmente.
  • Per operazioni leggere, come le chiamate API a servizi remoti, consigliamo di utilizzare la policy ServiceCallout. Consulta la policy Service Callout.
  • Per interazioni relativamente semplici con i contenuti dei messaggi, come la modifica o l'estrazione intestazioni HTTP, parametri o contenuti dei messaggi, Apigee consiglia di utilizzare una policy JavaScript.

Argomenti correlati