Criterio JavaCallout

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Ti consente di utilizzare Java per implementare un comportamento personalizzato non incluso predefinito dai criteri di Apigee. Nel codice Java, puoi accedere alle proprietà dei messaggi (intestazioni, parametri di ricerca, contenuti) e alle variabili di flusso nel flusso proxy. Se hai appena iniziato a utilizzare queste norme, consulta Come creare un callout Java.

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

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

Nota: importante:se stai sviluppando i criteri di callout Java, devi sapere quali criteri di autorizzazione sono in vigore nella JVM di Apigee e in che modo influiscono sul tuo codice. Consulta il riferimento alle autorizzazioni Java. Consulta anche Limitazioni.

Quando

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

Informazioni

Il criterio di callout Java ti consente di ottenere e impostare le variabili di flusso, eseguire logica personalizzata ed eseguire gestione degli errori, estrarre dati da richieste o risposte e altro ancora. Questo criterio ti consente di implementare un comportamento personalizzato non coperto da altri criteri Apigee standard.

Nota: Apigee consiglia di prendere in considerazione l'utilizzo del criterio JavaScript se hai intenzione di utilizzare JavaScript. In alternativa, valuta la possibilità di utilizzare le norme relative ai callout di servizio se devi effettuare chiamate HTTP a servizi remoti. Tuttavia, se vuoi scrivere codice Java personalizzato, hai questa opzione. Vedi anche Quando devo utilizzare un callout Java.

Puoi pacchettizzare l'applicazione Java con i file JAR del pacchetto di cui hai bisogno. Tieni presente che esistono alcune limitazioni per le operazioni che puoi eseguire con un callout Java. Queste sono elencate di seguito in Limitazioni.

Esempi

Esempio semplice

Come creare un callout Java

Recuperare le proprietà nel codice Java

L'elemento <Property> del criterio consente di specificare una coppia nome/valore che puoi recuperare in fase di esecuzione 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 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 del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/D	Obbligatorio
continueOnError	Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri. Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche: Le regole di errore vengono attivate SOLO in uno stato di errore (informazioni su continueOnError) Gestione degli errori all'interno del flusso corrente Suggerimento: se il codice Java genera un'eccezione, il flusso del proxy Apigee passa allo stato di errore anche se l'attributo continueOnError è impostato su true. Se non vuoi che un'eccezione lanciata generi uno stato di errore nel proxy, progetta il callout Java in modo che non generi errori. Cattura invece le eccezioni e imposta una variabile di contesto per acquisire le informazioni sulle eccezioni. Per ulteriori informazioni, consulta questo post della community di Apigee.	falso	Facoltativo
enabled	Imposta su true per applicare il criterio. Imposta false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.	true	Facoltativo
async	Questo attributo è stato ritirato.	falso	Ritirato

Elemento <DisplayName>

Da utilizzare insieme 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/D 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 di callout Java. La classe deve essere inclusa nel file JAR specificato da <ResourceURL>. Consulta anche Come creare un callout Java.

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

Valore predefinito:	N/D
Presenza:	Obbligatorio
Tipo:	Stringa

Elemento <Properties>

Aggiunge nuove proprietà a cui puoi accedere dal codice Java in fase di esecuzione.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

Valore predefinito:	Nessuno
Presenza:	Facoltativo
Tipo:	Stringa

Elemento <Property>

Specifica una proprietà a cui puoi accedere dal codice Java in fase di esecuzione. Devi specificare un valore di stringa literal 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>

Valore predefinito:	Nessuno
Presenza:	Facoltativo
Tipo:	Stringa

Attributi

Attributo	Descrizione	Predefinito	Presenza
nome	Specifica il nome della proprietà.	N/D	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 bundle del proxy API o nella sezione Script del riquadro di navigazione dell'editor del 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>

Valore predefinito:	Nessuno
Presenza:	Obbligatorio
Tipo:	Stringa

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto	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 durante il deployment del proxy contenente il criterio.

Nome dell'errore	Stringa di 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 è nel jar.
IncompatibleJavaVersion	Failed to load java class [classname] definition due to - [reason]	N/D	Vedi la 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/D	Vedi la stringa di errore.
JavaClassDefinitionNotFound	Failed to load java class [class_name] definition due to - [reason]	N/D	Vedi la stringa di errore.
NoAppropriateConstructor	No appropriate constructor found in JavaCallout class [class_name]	N/D	Vedi la stringa di errore.
NoResourceForURL	Could not locate a resource with URL [string]	N/D	Vedi la stringa di errore.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili	Dove	Esempio
fault.name="fault_name"	fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'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

Esempio: ogni tipo di criterio è definito da uno schema XML (.xsd). Come riferimento, gli schemi dei criteri sono disponibili su GitHub.

Compilazione e deployment

Per informazioni dettagliate su come compilare il codice Java personalizzato e implementarlo con un proxy, consulta Come creare un callout Java.

Limitazioni

Nota: per motivi di sicurezza, Apigee applica le norme relative alle autorizzazioni Java al codice callout Java. Le norme si applicano al codice che scrivi e al codice dei pacchetti importati. Qualsiasi codice (proprio o importato) non andrà a buon fine se viola un criterio di autorizzazione. Per maggiori dettagli, consulta il riferimento alle autorizzazioni Java.

Di seguito sono riportate le limitazioni da considerare quando scrivi 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 agli indirizzi sitelocal, anylocal, loopback e linklocal.
• Il callout non può ottenere informazioni sul processo corrente, sull'elenco dei processi o sull'utilizzo della CPU/memoria sulla macchina. Sebbene alcune di queste chiamate possano essere funzionali, non sono supportate e potrebbero essere disattivate attivamente in qualsiasi momento. Per la compatibilità futura, dovresti evitare di effettuare queste chiamate nel codice.
• Il ricorso alle librerie Java incluse in Apigee non è supportato. Queste librerie sono destinate esclusivamente alla funzionalità del prodotto Apigee e non è garantito che una libreria sarà disponibile 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 pacchettizzate come file JAR indipendenti, posiziona 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 aggiuntivo dipendente. Se sono presenti più JAR, aggiungili semplicemente 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 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

La documentazione Javadoc per scrivere codice di callout Java è inclusa qui su GitHub. Dovrai clonare o scaricare il codice HTML sul tuo sistema, quindi aprire il file index.html in un browser.

Note e best practice sull'utilizzo

• Quando utilizzi più callout Java, valuta la possibilità di caricare i JAR comuni come risorse basate sull'ambiente. Questa pratica è più efficiente rispetto al pacchettizzare gli stessi JAR con più bundle proxy durante il deployment nello stesso ambiente.
• Evita di eseguire il packaging e il deployment di più copie o versioni dello stesso file JAR in un ambiente. Ad esempio, Apigee consiglia di evitare:
  • Esegui il deployment dello stesso file JAR all'interno di un bundle di proxy e come risorsa dell'ambiente.
  • Esegui il deployment di una versione di un file JAR come risorsa dell'ambiente e di un'altra come parte di un bundle proxy.

  Il deployment di più copie dello stesso file JAR può causare un comportamento non deterministico in fase di esecuzione a causa di potenziali conflitti di ClassLoader.

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