Norme JavaScript

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

Cosa

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

Informazioni

Esistono molti casi d'uso per il criterio JavaScript. Ad esempio, puoi ottenere e impostare variabili di flusso, eseguire logica personalizzata ed eseguire la gestione degli errori, estrarre dati da richieste o risposte, modificare dinamicamente l'URL di destinazione backend e molto altro ancora. Queste norme ti consentono di implementare un comportamento personalizzato non coperto da altre norme standard di Edge. Infatti, puoi utilizzare un criterio JavaScript per ottenere molti degli stessi comportamenti implementati da altri criteri, come AssignMessage ed ExtractVariable.

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

Il criterio JavaScript consente di specificare un file sorgente JavaScript da eseguire oppure puoi includere il codice JavaScript direttamente nella configurazione del criterio con l'elemento <Source>. In entrambi i casi, il codice JavaScript viene eseguito quando viene eseguito il passaggio a cui è collegato il criterio. Per l'opzione del file sorgente, il codice sorgente viene sempre archiviato in una posizione standard all'interno del bundle proxy: apiproxy/resources/jsc. In alternativa, puoi anche memorizzare il codice sorgente in un file di risorse a livello di ambiente o organizzazione. Per istruzioni, vedi File di risorse. Puoi anche caricare il codice JavaScript tramite l'editor proxy dell'interfaccia utente Apigee.

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

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

Video

Guarda un breve video per scoprire come creare un'estensione delle norme personalizzata utilizzando le norme JavaScript.

Esempi

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 queste norme.

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali del criterio:

&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>

Elemento <IncludeURL>

Specifica un file di libreria JavaScript da caricare come dipendenza del 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 oggetto 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 Esempi.

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

Vedi l'esempio nella sezione Esempi.

Elemento <ResourceURL>

Specifica il file JavaScript principale che verrà eseguito nel flusso dell'API. Puoi archiviare questo file nell'ambito del proxy API (in /apiproxy/resources/jsc nel bundle del proxy API o nella sezione Script del riquadro di navigazione dell'editor del proxy API) oppure negli ambiti 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 oggetto JavaScript.

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

Esempio

Consulta l'esempio di base nella sezione Esempi.

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>

La procedura di configurazione di TLS per un client HTTP è la stessa che utilizzi per configurare TLS per un TargetEndpoint/TargetServer. Per ulteriori informazioni, consulta Configurazione di TLS da Edge al backend.

Note sull'utilizzo

Una policy JavaScript non contiene codice effettivo. Un criterio JavaScript fa invece 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 puoi includerlo nella directory /resources/jsc nei proxy API che sviluppi localmente.

Debug del codice del criterio JavaScript

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

Per visualizzare le istruzioni di stampa in Trace:

1. Apri lo strumento di tracciamento e avvia una sessione di tracciamento per un proxy che contiene la tua policy JavaScript.
2. Chiama il proxy.
3. Nello strumento di tracciamento, fai clic su Output di tutte le transazioni per aprire il riquadro dell'output.

   

4. I tuoi estratti conto stampati verranno visualizzati in questo riquadro.

Puoi utilizzare la funzione print() per inviare informazioni di debug allo strumento Trace. Questa funzione è disponibile direttamente tramite il modello a oggetti JavaScript. Per maggiori dettagli, vedi 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) le variabili di flusso nel codice JavaScript chiamando i metodi sull'oggetto contesto. Un pattern tipico è simile a questo:

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

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

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 conoscere queste informazioni se stai sviluppando regole di errore 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.

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 il criterio attiva un errore in fase di runtime. Per ulteriori informazioni, consulta Cosa che devi conoscere sugli errori relativi alle norme.

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 policy è definito da uno schema XML (.xsd). Per riferimento, gli schemi delle policy sono disponibili su GitHub.

Argomenti correlati

• Modello oggetto JavaScript
• Per istruzioni, esempi di criteri ed esempi JavaScript, consulta Programmazione di proxy API con JavaScript.

Articoli della community Apigee

Puoi trovare questi articoli correlati nella community Apigee:

• Come gestire le intestazioni con più valori in JavaScript?