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

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javacallout.ExecutionError 500 Occurs when Java code throws an exception or returns null during the execution of a JavaCallout policy.

Deployment errors

These errors can occur when the proxy containing the policy is deployed.

Error name Fault string HTTP status Occurs when
ResourceDoesNotExist Resource with name [name] and type [type] does not exist N/A The file specified in the <ResourceURL> element does not exist.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] N/A The class file specified in the <ClassName> element is not in the jar.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] N/A See fault string. See also Supported software and supported versions.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] N/A See fault string.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] N/A See fault string.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] N/A See fault string.
NoResourceForURL Could not locate a resource with URL [string] N/A See fault string.

Fault variables

These variables are set when this policy triggers an error. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ExecutionError"
javacallout.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javacallout.JC-GetUserData.failed = true

Example error response

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

Example fault rule

<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