Norme JavaScript

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

La policy JavaScript consente di aggiungere codice JavaScript personalizzato che viene eseguito nel contesto del flusso del proxy API. Questa policy ti consente di implementare un comportamento personalizzato non coperto in altro modo dalle policy Apigee.

Nel codice JavaScript personalizzato, puoi utilizzare gli oggetti, i metodi e le proprietà del modello oggetto JavaScript di Apigee. Puoi ottenere, impostare e rimuovere variabili nel contesto del flusso proxy, eseguire logica personalizzata, gestire gli errori, estrarre dati da richieste o risposte e modificare dinamicamente l'URL di destinazione del backend. Puoi anche utilizzare le funzioni di crittografia di base disponibili nel modello a oggetti.

Il criterio JavaScript consente di specificare un file di origine JavaScript da eseguire oppure puoi includere il codice JavaScript direttamente nella configurazione del criterio utilizzando l'elemento <Source>. In entrambi i casi, il codice JavaScript viene eseguito quando viene eseguito il passaggio a cui è collegata la policy.

Per l'opzione del file sorgente, il codice sorgente viene sempre archiviato in una posizione standard nel bundle proxy: apiproxy/resources/jsc. In alternativa, puoi memorizzare il codice sorgente in un file di risorse a livello di ambiente o organizzazione. Per istruzioni, vedi File di risorse. Puoi anche caricare JavaScript utilizzando l'editor proxy dell'interfaccia utente Apigee.

Apigee non consiglia di utilizzare la norma JavaScript per quanto segue:

  • Logging. Il criterio MessageLogging è più adatto per la registrazione con piattaforme di logging di terze parti come Splunk, Sumo e Loggly. Questa norma migliora anche il rendimento del proxy API eseguendo PostClientFlow dopo che la risposta viene restituita al client.
  • Sostituzione delle norme Apigee. Le norme JavaScript non sostituiscono le funzionalità delle norme Apigee. Se le funzionalità che ti servono sono disponibili in un criterio Apigee, utilizza questo criterio anziché implementare una soluzione JavaScript personalizzata. Il codice JavaScript personalizzato potrebbe non corrispondere al rendimento e all'ottimizzazione delle policy Apigee.

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

Apigee supporta JavaScript in esecuzione sul motore JavaScript Rhino 1.7.13.

Queste norme sono estensibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o di utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di policy e sulle implicazioni di utilizzo, consulta Tipi di policy.

Esempi

Riscrivere l'URL di destinazione

Un caso d'uso comune prevede l'estrazione dei dati da un corpo della richiesta, l'archiviazione in una variabile di flusso e l'utilizzo di questa variabile di flusso altrove nel flusso proxy. Ad esempio, supponiamo che un utente inserisca il proprio nome in un modulo HTML e lo invii. Per estrarre i dati del modulo e aggiungerli dinamicamente all'URL del servizio di backend, utilizza un criterio JavaScript.

  1. Nell'interfaccia utente di Apigee, apri il proxy che hai creato nell'editor proxy.
  2. Seleziona la scheda Sviluppa.
  3. Nel menu Nuovo, seleziona Nuovo script.
  4. Nella finestra di dialogo, seleziona JavaScript e assegna allo script il nome js-example.
  5. Incolla il seguente codice nell'editor di codice e salva il proxy. L'oggetto context è disponibile per il codice JavaScript in qualsiasi punto del flusso del proxy. Ottiene costanti specifiche del flusso, chiama metodi get/set utili ed esegue altre operazioni. Questo oggetto fa parte del modello oggetto JavaScript di Apigee. La variabile di flusso target.url è una variabile integrata di lettura/scrittura accessibile nel flusso Richiesta target. Quando imposti questa variabile con l'URL API, Apigee chiama l'URL di backend. In questo modo viene riscritto l'URL di destinazione originale, ovvero l'URL specificato durante la creazione del proxy (ad esempio, http://www.example.com). 
    if (context.flow=="PROXY_REQ_FLOW") {
     var username = context.getVariable("request.formparam.user");
     context.setVariable("info.username", username);
}


if (context.flow=="TARGET_REQ_FLOW") {
     context.setVariable("request.verb", "GET");
     var name = context.getVariable("info.username");
     var url = "http://mocktarget.apigee.net/"
     context.setVariable("target.url", url + "?user=" + name);
}
  6. Nel menu Nuova norma, seleziona JavaScript.
  7. Assegna al criterio il nome target-rewrite. Accetta i valori predefiniti e salva il criterio.
  8. Dopo aver selezionato Proxy Endpoint Preflow in Navigator, il criterio viene aggiunto al flusso.
  9. In Navigator, seleziona Target Endpoint PreFlow.
  10. Nel Navigator, trascina il criterio JavaScript sul lato Request dell'endpoint di destinazione nell'editor di flusso.
  11. Salva.
  12. Sostituisci il nome dell'organizzazione e il nome del proxy quando chiami l'API: 
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

Esamina la definizione XML per il criterio JavaScript utilizzato in questo esempio. L'elemento <ResourceURL> specifica il file sorgente JavaScript da eseguire. Questo pattern si applica a qualsiasi file di origine JavaScript: jsc://filename.js. Se il tuo codice JavaScript richiede inclusioni, utilizza uno o più elementi <IncludeURL>, come descritto più avanti in questo documento.

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

Recuperare il valore della proprietà da JavaScript

Puoi aggiungere un elemento <Property> nella configurazione e poi recuperarne il valore con JavaScript in fase di runtime.

Utilizza l'attributo name dell'elemento per specificare il nome per accedere alla proprietà dal codice JavaScript. Il valore dell'elemento <Property> (il valore tra i tag di apertura e chiusura) è il valore letterale ricevuto da JavaScript.

In JavaScript, recuperi il valore della proprietà della norma accedendovi come proprietà dell'oggetto Properties, come segue:

  • Configura la proprietà. Il valore della proprietà è il nome della variabile response.status.code. 
    <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite">
    <DisplayName>JavascriptURLRewrite</DisplayName>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
    <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL>
</Javascript>
  • Recupera la proprietà utilizzando JavaScript. La funzione getVariable utilizza quindi il nome della variabile recuperata per recuperare il valore della variabile. 
    var responseCode = properties.source; // Returns "response.status.code"
var value = context.getVariable(responseCode); // Get the value of response.status.code
context.setVariable("response.header.x-target-response-code", value);

Gestione degli errori

Per esempi e una discussione sulle tecniche di gestione degli errori che puoi utilizzare in un callout JavaScript, consulta Modo corretto per restituire un errore da una policy JavaScript. I suggerimenti nella community Apigee sono forniti solo a scopo informativo e non rappresentano necessariamente le best practice consigliate da Google.

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>

< languageVersion="VERSION_1_3" Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Attributo Descrizione Predefinito Presenza
languageVersion

Specifica la versione del linguaggio JavaScript in cui è scritto il codice. I valori includono VERSION_DEFAULT, VERSION_1_0, VERSION_1_1, VERSION_1_2, VERSION_1_3, VERSION_1_4, VERSION_1_5, VERSION_1_6, VERSION_1_7, VERSION_1_8 e VERSION_ES6.

 VERSION_DEFAULT Facoltativo
timeLimit

Specifica il tempo massimo (in millisecondi) durante il quale uno script può essere eseguito. Ad esempio, se viene superato un limite di 200 ms, il criterio genera questo errore: Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms.

 N/D Obbligatorio

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

Attributo Descrizione Predefinito Presence
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:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

Imposta su 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 Deprecato

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.
Presence Facoltativo
Tipo Stringa

Elemento <IncludeURL>

Specifica un file di libreria JavaScript da caricare come dipendenza per il file JavaScript principale specificato con l'elemento <ResourceURL> o <Source>. Il criterio valuta gli script 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 utilizzando elementi <IncludeURL> aggiuntivi.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Predefinito: Nessuno
Presenza: Facoltativo
Tipo: Stringa

Elemento <Property>

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

<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

Esempio

Vedi l'esempio nella sezione Esempi.

Elemento <ResourceURL>

Specifica il file JavaScript principale che viene 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 Navigatore dell'editor del proxy API). In alternativa, archivialo negli ambiti dell'organizzazione o dell'ambiente per riutilizzarlo in più proxy API, come descritto in Gestione delle risorse. Il codice può utilizzare gli oggetti, i metodi e le proprietà del modello oggetto JavaScript.

<ResourceURL>jsc://my-javascript.js</ResourceURL>
Predefinito: Nessuno
Presenza: È obbligatorio specificare <ResourceURL> o <Source>. Se sono presenti sia <ResourceURL> che <Source>, la norma ignora <ResourceURL>.
Tipo: Stringa

Esempio

Vedi l'esempio nella sezione Esempi.

Elemento <Source>

Puoi inserire JavaScript direttamente nella configurazione XML della policy. Il codice JavaScript inserito viene eseguito quando il criterio viene eseguito nel flusso API.

Predefinito: Nessuno
Presenza: È obbligatorio specificare <ResourceURL> o <Source>. Se sono presenti sia <ResourceURL> che <Source>, la norma ignora <ResourceURL>.
Tipo: Stringa

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>
Predefinito: Nessuno
Presenza: Facoltativo
Tipo: Stringa

La procedura di configurazione di TLS per un client HTTP è la stessa utilizzata per configurare TLS per un TargetEndpoint/TargetServer. Per ulteriori informazioni, consulta Opzioni per la configurazione di TLS.

Note sull'utilizzo

Eseguire il debug del codice del criterio JavaScript

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

Per visualizzare le istruzioni di stampa nello strumento di debug:

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

    Output di tutti i riquadri Transazioni nello strumento Apigee Trace, che mostra le istruzioni di stampa.

  4. In questo riquadro vengono visualizzati i tuoi estratti conto.

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 dell'oggetto context. Ad esempio:

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

L'oggetto context fa parte del modello oggetto JavaScript di Apigee.

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.javascript.ScriptExecutionFailed 500 Le norme relative a JavaScript possono generare molti tipi diversi di errori ScriptExecutionFailed. I tipi di errori più comuni includono RangeError, ReferenceError, SyntaxError, TypeError e URIError.
steps.javascript.ScriptExecutionFailedLineNumber 500 Si è verificato un errore nel codice JavaScript. Per i dettagli, consulta la stringa di errore. N/D
steps.javascript.ScriptSecurityError 500 Si è verificato un errore di sicurezza durante l'esecuzione di JavaScript. Per i dettagli, consulta la stringa di errore. N/D

Errori di deployment

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

Nome dell'errore Causa Correggi
InvalidResourceUrlFormat Se il formato dell'URL della risorsa specificato all'interno dell'elemento <ResourceURL> o <IncludeURL> del criterio JavaScript non è valido, il deployment del proxy API non va a buon fine.
InvalidResourceUrlReference Se gli elementi <ResourceURL> o <IncludeURL> fanno riferimento a un file JavaScript non esistente, il deployment del proxy API non va a buon fine. Il file di origine a cui si fa riferimento deve esistere a livello di proxy API, ambiente o organizzazione.
WrongResourceType Questo errore si verifica durante il deployment se gli elementi <ResourceURL> o <IncludeURL> del criterio JavaScript fanno riferimento a un tipo di risorsa diverso da jsc (file JavaScript).
NoResourceURLOrSource Il deployment del criterio JavaScript può non riuscire con questo errore se l'elemento <ResourceURL> non è dichiarato o se l'URL della risorsa non è definito all'interno di questo elemento. L'elemento <ResourceURL> è obbligatorio. In alternativa, l'elemento <IncludeURL> è dichiarato, ma l'URL della risorsa non è definito all'interno di questo elemento. L'elemento <IncludeURL> è facoltativo, ma se viene dichiarato, l'URL della risorsa deve essere specificato all'interno dell'elemento <IncludeURL>.

Variabili di errore

Queste variabili vengono impostate quando questo criterio attiva un errore in fase di esecuzione. 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 "ScriptExecutionFailed"
javascript.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. javascript.JavaScript-1.failed = true

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). Come riferimento, gli schemi delle policy sono disponibili su GitHub.

Argomenti correlati

Articoli della community Apigee

Puoi trovare questi articoli correlati nella community Apigee: