Norme JavaScript

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Questo criterio ti 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 oggetto JavaScript di Apigee. Il modello di oggetti consente di recuperare, impostare e rimuovere le variabili nel contesto del flusso del proxy. Puoi anche utilizzare le funzioni di crittografia di base fornite con il modello di oggetti.

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.

Informazioni

Esistono molti casi d'uso per il criterio JavaScript. Ad esempio, puoi recuperare e impostare le variabili del flusso, eseguire logica personalizzata ed eseguire la gestione degli errori, estrarre i dati dalle richieste o dalle risposte, modificare dinamicamente l'URL di destinazione del backend e molto altro ancora. Questo criterio ti consente di implementare un comportamento personalizzato non coperto da altri criteri Apigee standard. 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 il criterio JavaScript è il logging. Il criterio di registrazione dei messaggi è molto più adatto per la registrazione su piattaforme di registrazione di terze parti come Splunk, Sumo e Loggly e consente di migliorare il rendimento 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 ti consente di specificare un file sorgente JavaScript da eseguire o 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 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 le istruzioni, vedi File di risorse. Puoi anche caricare il codice JavaScript tramite l'editor proxy dell'interfaccia utente di Apigee.

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

Apigee supporta JavaScript che viene eseguito sul motore JavaScript Rhino 1.7.13.

Video

Nota:il video seguente mostra l'editor proxy classico nell'interfaccia utente di Apigee. Apigee sta introducendo una nuova versione di Proxy Editor, che ha un design diverso dalla versione classica mostrata nel video.

Guarda un breve video per scoprire come creare un'estensione di criteri personalizzati utilizzando i criteri JavaScript.

Esempi

Riscrivere l'URL di destinazione

Ecco un caso d'uso comune: estrazione di dati dal corpo di una richiesta, archiviazione in una variabile di flusso e utilizzo di questa variabile di flusso altrove nel flusso del proxy. Supponiamo che tu abbia un'app in cui l'utente inserisce il proprio nome in un modulo HTML e lo invia. Vuoi che il proxy API estragga i dati del modulo e li aggiunga dinamicamente all'URL utilizzato per chiamare il servizio di backend. Come faresti in un criterio JavaScript?

Nota: se vuoi provare questo esempio, presupponiamo che tu abbia creato un nuovo proxy nell'editor dei proxy. Quando lo crei, specifica un URL del servizio di backend: http://www.example.com. Per questo esempio, riscrivi l'URL del backend in modo dinamico. Se non sai come creare un nuovo proxy, consulta il tutorial introduttivo.

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 un nome, ad esempio js-example.
5. Incolla il seguente codice nell'editor di codice e salva il proxy. L'elemento importante da notare è l'oggetto context. Questo oggetto è disponibile per il codice JavaScript in qualsiasi punto del flusso del proxy. Viene utilizzato per ottenere costanti specifiche del flusso, per chiamare metodi get/set utili e per altre operazioni. Questa parte dell'oggetto fa parte del modello oggetto JavaScript di Apigee. Tieni inoltre presente che la variabile di flusso target.url è una variabile di lettura/scrittura integrata accessibile nel flusso della richiesta target. Quando impostiamo la variabile con l'URL dell'API, Apigee effettua la chiamata di backend a quell'URL. Abbiamo sostanzialmente riscritto l'URL target originale, ovvero quello che hai specificato quando hai creato il proxy (ad es. 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 un nome al criterio, ad esempio target-rewrite. Accetta i valori predefiniti e salva il criterio.
8. Se selezioni il Preflow dell'endpoint proxy in Navigator, vedrai che il criterio è stato aggiunto a quel flusso.
9. In Navigator, seleziona l'icona PreFlow dell'endpoint target.
10. Dal Navigator, trascina il criterio JavaScript sul lato Richiesta dell'endpoint target nell'editor di flusso.
11. Salva.
12. Chiama l'API in questo modo, sostituendo il nome corretto dell'organizzazione e del proxy come appropriato:

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

Un'ultima cosa: diamo un'occhiata alla definizione XML per il criterio JavaScript utilizzato in questo esempio. L'elemento importante da notare è che l'elemento <ResourceURL> viene utilizzato per specificare il file sorgente JavaScript da eseguire. Lo stesso pattern viene utilizzato per qualsiasi file di origine JavaScript: jsc://filename.js. Se il codice JavaScript richiede inclusioni, puoi utilizzare uno o più elementi <IncludeURL> per farlo, come descritto più avanti in questo riferimento.

<?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> in configurazione, quindi recuperare il valore dell'elemento con JavaScript in fase di runtime.

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

In JavaScript, puoi recuperare il valore della proprietà della norma accedendovi come proprietà dell'oggetto Properties, come nel seguente esempio:

• Configura la proprietà. In questo caso, 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à con JavaScript. Qui, il valore recuperato, ovvero un nome di variabile, viene utilizzato dalla funzione getVariable 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 uncallout JavaScript, consulta Modo corretto per restituire un errore dal criterio JavaScript. I suggerimenti offerti nella community Apigee sono solo informativi e non rappresentano necessariamente le best practice consigliate da Google.

In un criterio JavaScript, l'accesso a request.content.asJSON in modalità di sola lettura fa sì che i numeri interi di grandi dimensioni vengano convertiti in notazione esponenziale nel corpo del messaggio. Di conseguenza, il messaggio verrà sovrascritto con i valori convertiti.

---

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 questo criterio.

Attributo	Descrizione	Predefinito	Presenza
timeLimit	Specifica il tempo massimo (in millisecondi) per l'esecuzione dello script. 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. Nota: per gli account di prova gratuita, il tempo di esecuzione è limitato a 200 ms.	N/D	Obbligatorio

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

Specifica un file della 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.

Avviso: se i file JavaScript sono archiviati a livello di organizzazione o di ambiente, assicurati che siano stati caricati correttamente con cURL utilizzando l'opzione -F o come allegato tramite un client REST. Content-Type è multipart/form-data. Per ulteriori informazioni, consulta Gestire le risorse.

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

Valore predefinito:	Nessuno
Presenza:	Facoltativo
Tipo:	Stringa

Esempio

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

Elemento <Property>

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

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

Esempio

Guarda l'esempio nella sezione Samples (Esempi).

Elemento <ResourceURL>

Specifica il file JavaScript principale che verrà eseguito nel flusso dell'API. Puoi memorizzare 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) o negli ambiti dell'organizzazione o dell'ambiente per il riutilizzo in più proxy API, come descritto in Gestire le risorse. Il codice può utilizzare gli oggetti, metodi e proprietà del modello oggetto JavaScript.

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

Valore predefinito:	Nessuno
Presenza:	È obbligatorio specificare <ResourceURL> o <Source>. Se sono presenti sia <ResourceURL> che <Source>, <ResourceURL> viene ignorato.
Tipo:	Stringa

Esempio

Consulta l'esempio di base nella sezione Samples (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 dell'API.

Valore predefinito:	Nessuno
Presenza:	È obbligatorio specificare <ResourceURL> o <Source>. Se sono presenti sia <ResourceURL> che <Source>, <ResourceURL> viene ignorato.
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 del 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>

Valore predefinito:	Nessuno
Presenza:	Facoltativo
Tipo:	Stringa

La procedura di configurazione di TLS per un client HTTP è la stessa utilizzata per configurare TLS per un endpoint di destinazione/server di destinazione. Per ulteriori informazioni, consulta la sezione Opzioni per la configurazione di TLS.

Note sull'utilizzo

Avviso: le chiamate di sistema non sono consentite dal modello di sicurezza. Ad esempio: letture o scritture del file system interno oppure acquisizione delle informazioni sull'utente corrente, dell'elenco dei processi o dell'utilizzo della CPU/memoria. 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.

Debug del codice dei criteri JavaScript

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

Per visualizzare le istruzioni di stampa in Debug:

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

   

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

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

Variabili di flusso

Per impostazione predefinita, questo criterio non compila alcuna variabile. Tuttavia, puoi impostare (e ottenere) le variabili di flusso nel codice JavaScript chiamando i metodi sull'oggetto context. Un pattern tipico ha questo aspetto:

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.

Suggerimento:hai bisogno di aiuto per risolvere un errore? Fai clic su nella colonna Correzione per informazioni dettagliate sulla risoluzione dei problemi.

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.

Suggerimento:hai bisogno di aiuto per risolvere un errore? Fai clic su accanto alla descrizione della causa dell'errore per visitare la pagina di risoluzione dei problemi.

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 runtime. 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

Nota: per la gestione degli errori, la best practice è intercettare la parte errorcode della risposta all'errore. Non fare affidamento sul testo in faultstring, perché potrebbe cambiare.

{
  "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 norma è definito da uno schema XML (.xsd). Come riferimento, gli schemi delle norme sono disponibili su GitHub.

Argomenti correlati

• Modello oggetto JavaScript

Articoli della community Apigee

Nella community di Apigee puoi trovare questi articoli correlati:

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