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

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.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Fault variables

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

Example error response

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

Example fault rule

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