Criterio JavaScript

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

Cosa

Questo criterio consente di aggiungere codice JavaScript personalizzato che viene eseguito nel contesto di un flusso proxy API. Nel codice JavaScript personalizzato puoi utilizzare gli oggetti, i metodi e le proprietà del modello a oggetti JavaScript di Apigee Edge. Il modello a oggetti consente di recuperare, impostare e rimuovere le variabili nel contesto del flusso proxy. Puoi anche utilizzare le funzioni crittografiche di base fornite con il modello a oggetti.

Informazioni

Il criterio JavaScript può essere utilizzato in molti casi d'uso. Ad esempio, puoi ottenere e impostare variabili di flusso, eseguire logiche personalizzate ed eseguire la gestione degli errori, estrarre dati da richieste o risposte, modificare dinamicamente l'URL di destinazione del backend e molto altro ancora. Questo criterio consente di implementare un comportamento personalizzato che non è coperto da altri criteri Edge standard. Infatti, è possibile utilizzare un criterio JavaScript per ottenere molti degli stessi comportamenti implementati da altri criteri, come AssegnaMessage ed ExtractVariable.

Un caso d'uso che non consigliamo per il criterio JavaScript è il logging. Il criterio di logging dei messaggi è molto più adatto per il logging su piattaforme di logging di terze parti come Splunk, Sumo e Loggly e consente di migliorare le prestazioni del proxy API eseguendo il criterio di logging dei messaggi in PostClientFlow, che viene eseguito dopo che la risposta è stata inviata al client.

Il criterio JavaScript consente di specificare un file di origine JavaScript da eseguire oppure di includere il codice JavaScript direttamente nella configurazione del criterio con l'elemento <Source>. In ogni caso, il codice JavaScript viene eseguito quando viene eseguito il passaggio a cui è associato il criterio. Per l'opzione del file di origine, il codice sorgente viene sempre archiviato in una posizione standard all'interno del bundle proxy: apiproxy/resources/jsc. In alternativa, puoi anche archiviare il codice sorgente in un file di risorse a livello di ambiente o di organizzazione. Per le istruzioni, consulta File di risorse. Puoi anche caricare il tuo codice JavaScript tramite l'editor proxy UI Apigee.

I file di origine JavaScript devono avere sempre un'estensione .js.

Consulta la pagina Software e versioni supportate per la versione attualmente supportata di JavaScript.

Video

Guarda un breve video per scoprire come creare un'estensione del criterio personalizzata utilizzando il criterio JavaScript.

Samples

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="target-rewrite">
    <DisplayName>target-rewrite</DisplayName>
    <Properties/>
    <ResourceURL>jsc://js-example.js</ResourceURL>
</Javascript>

Riferimento elemento

Il riferimento all'elemento descrive gli elementi e gli attributi del criterio JavaScript.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" 
        continueOnError="false" enabled="true" timeLimit="200" 
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>

</Javascript>

Attributi <Javascript>

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

I seguenti attributi sono specifici di questa norma.

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

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>

Elemento <IncludeURL>

Specifica un file della libreria JavaScript da caricare come dipendenza dal file JavaScript principale specificato con l'elemento <ResourceURL> o <Source>. Gli script verranno valutati nell'ordine in cui sono elencati nel criterio. Il codice può utilizzare gli oggetti, i metodi e le proprietà del modello a oggetti JavaScript.

Includi più di una risorsa di dipendenza JavaScript con elementi <IncludeURL> aggiuntivi.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

Esempio

Consulta l'esempio di base nella sezione Samples (Campioni).

Elemento <Property>

Specifica una proprietà a cui puoi accedere dal codice JavaScript in fase di runtime.

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

Attributi

Esempio

Guarda l'esempio nella sezione Samples.

Elemento <ResourceURL>

Specifica il file JavaScript principale che verrà eseguito nel flusso API. Puoi archiviare questo file nell'ambito del proxy API (in /apiproxy/resources/jsc nel pacchetto del proxy API o nella sezione Script del riquadro di navigazione dell'editor del proxy API) oppure nell'ambito dell'organizzazione o dell'ambiente per il riutilizzo in più proxy API, come descritto in File di risorse. Il codice può utilizzare gli oggetti, i metodi e le proprietà del modello a oggetti JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>

Esempio

Consulta l'esempio di base nella sezione Samples (Campioni).

Elemento <Source>

Consente di inserire JavaScript direttamente nella configurazione XML del criterio. Il codice JavaScript inserito viene eseguito quando il criterio viene eseguito nel flusso API.

Esempio

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

Elemento <SSLInfo>

Specifica le proprietà utilizzate per configurare TLS per tutte le istanze client HTTP create dal criterio JavaScript.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>

Il processo di configurazione di TLS per un client HTTP è lo stesso utilizzato per configurare TLS per un endpoint/TargetServer. Per ulteriori informazioni, consulta Configurazione di TLS da Edge al backend.

Note sull'utilizzo

Un criterio JavaScript non contiene codice effettivo. Invece, un criterio JavaScript fa riferimento a una "risorsa" JavaScript e definisce il passaggio nel flusso API in cui viene eseguito JavaScript. Puoi caricare lo script tramite l'editor proxy dell'interfaccia utente di gestione oppure includerlo nella directory /resources/jsc nei proxy API che sviluppi localmente.

Debug del codice del criterio JavaScript

Utilizza la funzione print() per inviare le informazioni di debug nel riquadro di output della transazione nello strumento di traccia. Per maggiori dettagli ed esempi, vedi Eseguire il debug con le istruzioni print() JavaScript.

Per visualizzare le istruzioni di stampa in Trace:

1. Apri lo strumento di traccia e avvia una sessione di traccia per un proxy contenente il criterio JavaScript.
2. Chiama il proxy.
3. Nello strumento di traccia, fai clic su Output da tutte le transazioni per aprire il riquadro di output.

   

4. Le dichiarazioni di stampa verranno visualizzate in questo riquadro.

Puoi utilizzare la funzione print() per generare informazioni di debug nello strumento Traccia. Questa funzione è disponibile direttamente tramite il modello a oggetti JavaScript. Per maggiori dettagli, consulta "Eseguire il debug di JavaScript con le istruzioni print()".

Variabili di flusso

Questo criterio non compila alcuna variabile per impostazione predefinita; tuttavia, puoi impostare (e ottenere) variabili di flusso nel codice JavaScript chiamando i metodi nell'oggetto di contesto. Uno schema tipico ha il seguente aspetto:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))

L'oggetto di contesto fa parte del modello a oggetti JavaScript di Apigee Edge.

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 stai sviluppando regole di errore per la gestione degli 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.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore in fase di runtime. Per maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori dei criteri.

Esempio di risposta di errore

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Esempio di regola di errore

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

Schema

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

Argomenti correlati

• Modello a oggetti JavaScript
• Per istruzioni, esempi di criteri ed esempi di JavaScript, consulta Utilizzare i proxy API di programmazione con JavaScript.

Articoli della community Apigee

Puoi trovare questi articoli correlati nella community di Apigee:

• Come gestire le intestazioni multivalore in JavaScript?