Norme JavaScript

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Cosa

Questo criterio consente di aggiungere codice JavaScript personalizzato da eseguire 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. 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.

Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Informazioni

Il criterio JavaScript può essere utilizzato in molti casi d'uso. 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 del backend e molto altro. Questo criterio consente di implementare un comportamento personalizzato che non è coperto da altri criteri di Apigee standard. Infatti, puoi utilizzare un criterio JavaScript per applicare 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 MessageLogging è molto più adatto per eseguire il logging su piattaforme di logging di terze parti come Splunk, Sumo e Loggly. È inoltre possibile migliorare le prestazioni del proxy API eseguendo il criterio MessageLogging 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 di Apigee.

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

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

Video

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

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

Esempi

Riscrivi l'URL di destinazione

Ecco un caso d'uso comune: estrazione dei dati da un corpo di richiesta, archiviazione dei dati in una variabile di flusso e utilizzo di questa variabile di flusso altrove nel flusso 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 in modo dinamico all'URL utilizzato per chiamare il servizio di backend. Come lo faresti in un criterio JavsScript?

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

1. Nella UI di Apigee, apri il proxy che hai creato nell'editor proxy.
2. Seleziona la scheda Develop.
3. Dal menu Nuovo, seleziona Nuovo script.
4. Nella finestra di dialogo, seleziona JavaScript e assegna un nome allo script, ad esempio js-example.
5. Incolla il seguente codice nell'editor di codice e salva il proxy. È importante notare l'oggetto context. Questo oggetto è disponibile per il codice JavaScript in qualsiasi punto del flusso 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 a oggetti JavaScript di Apigee. Tieni inoltre presente che la variabile di flusso target.url è una variabile integrata di lettura/scrittura accessibile nel flusso Richiesta target. Quando impostiamo questa variabile con l'URL dell'API, Apigee effettua la chiamata di backend a quell'URL. Essenzialmente abbiamo riscritto l'URL di destinazione originale, che corrispondeva a quello specificato al momento della creazione del 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. Dal 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 pre-flusso dell'endpoint proxy nel navigatore, vedrai che il criterio è stato aggiunto a quel flusso.
9. Nel navigatore, seleziona l'icona Preflusso endpoint target.
10. Dal navigatore, trascina il criterio JavaScript sul lato Richiesta dell'endpoint di destinazione nell'editor di flusso.
11. Salva.
12. Chiama l'API in questo modo, sostituendo il nome dell'organizzazione e il nome del proxy corretti, a seconda dei casi:

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

Come ultima cosa, diamo un'occhiata alla definizione XML del criterio JavaScript utilizzato in questo esempio. È importante notare che l'elemento <ResourceURL> viene utilizzato per specificare il file sorgente JavaScript da eseguire. Questo stesso pattern viene utilizzato per qualsiasi file di origine JavaScript: jsc://filename.js. Se il codice JavaScript richiede l'inclusione, 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>

Recupera il valore della proprietà da JavaScript

Puoi aggiungere un elemento <Property> nella 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 il tag di apertura e quello di chiusura) è il valore letterale che verrà ricevuto da JavaScript.

In JavaScript, puoi recuperare il valore della proprietà del criterio accedendovi come proprietà dell'oggetto Properties, come indicato di seguito:

• Configura la proprietà. Qui 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. In questo caso, il valore recuperato (il nome di una variabile) viene poi 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 un callout JavaScript, consulta Il modo corretto per restituire un errore dalle norme JavaScript. I suggerimenti offerti nella community Apigee sono solo a scopo informativo e non rappresentano necessariamente le best practice consigliate da Google.

All'interno di un criterio JavaScript, l'accesso a request.content.asJSON in modalità di sola lettura comporta la conversione di numeri interi di grandi dimensioni in notazione esponenziale nel corpo del messaggio. Di conseguenza, il messaggio verrà sovrascritto con i valori convertiti.

---

Riferimento elemento

Il riferimento agli elementi 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.

Attributo	Descrizione	Predefinito	Presenza
timeLimit	Specifica il tempo massimo (in millisecondi) durante il quale lo 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. Nota: per gli account di prova gratuiti, 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 della norma. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri. Facoltativamente, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.	N/A	Obbligatorio
continueOnError	Impostalo su false per restituire un errore in caso di errore di un criterio. Questo è il comportamento previsto per la maggior parte dei criteri. Imposta su true per fare in modo che l'esecuzione del flusso continui anche in caso di errore di un criterio. Vedi anche: Le regole di errore vengono attivate SOLO in stato di errore (informazioni su continueOnError) Gestione dei guasti all'interno del flusso di corrente	false	Facoltativo
enabled	Imposta il criterio su true per applicare il criterio. Impostala su false per disattivare il criterio. Il criterio non verrà applicato anche se rimane associato a un flusso.	true	Facoltativo
async	Questo attributo è obsoleto.	false	Deprecata

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>

Predefinito	N/A Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza	Facoltativo
Tipo	Stringa

Elemento <IncludeURL>

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

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 file allegato tramite un client REST. Il tipo di contenuto è multipart/form-data. Per saperne di più, vedi Gestione delle risorse.

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

Predefinita:	Nessuna selezione
Presenza:	Facoltativo
Tipo:	Stringa

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>

Predefinita:	Nessuna selezione
Presenza:	Facoltativo
Tipo:	Stringa

Attributi

Attributo	Descrizione	Predefinito	Presenza
name	Specifica il nome della proprietà.	N/D	Obbligatorio.

Esempio

Esamina l'esempio riportato 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 bundle 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 Gestione delle risorse. Il codice può utilizzare gli oggetti, i metodi e le proprietà del modello a oggetti JavaScript.

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

Predefinita:	Nessuna selezione
Presenza:	È obbligatorio specificare <ResourceURL> o <Source>. Se <ResourceURL> e <Source> sono entrambi presenti, il campo <ResourceURL> viene ignorato.
Tipo:	Stringa

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.

Predefinita:	Nessuna selezione
Presenza:	È obbligatorio specificare <ResourceURL> o <Source>. Se <ResourceURL> e <Source> sono entrambi presenti, il campo <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 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>

Predefinita:	Nessuna selezione
Presenza:	Facoltativo
Tipo:	Stringa

Il processo di configurazione di TLS per un client HTTP è lo stesso utilizzato per configurare TLS per un targetEndpoint/TargetServer. Per ulteriori informazioni, vedi Opzioni per la configurazione di TLS.

Note sull'utilizzo

Avviso: le chiamate di sistema non sono consentite dal modello di sicurezza. Ad esempio: operazioni di lettura o scrittura del file system interno oppure di recupero delle informazioni sull'utente correnti, dell'elenco dei processi o dell'utilizzo di CPU/memoria. Sebbene alcune di queste chiamate possano funzionare, non sono supportate e potrebbero essere disattivate attivamente in qualsiasi momento. Per la compatibilità con l'inoltro, dovresti evitare di effettuare queste chiamate nel tuo codice.

Debug del codice del criterio JavaScript

Utilizza la funzione print() per inviare le informazioni di debug nel riquadro dell'output della transazione nello strumento di debug. Per dettagli ed esempi, consulta la pagina relativa al debug con le istruzioni print() di JavaScript.

Per visualizzare le istruzioni di stampa in Debug:

1. Apri lo strumento di debug e avvia una sessione di traccia per un proxy che contiene il criterio JavaScript.
2. Chiama il proxy.
3. Nello strumento di debug, 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 inviare le informazioni di debug allo strumento di debug. Questa funzione è disponibile direttamente tramite il modello a oggetti JavaScript. Per maggiori dettagli, consulta Eseguire il debug di JavaScript con i feedback print().

Variabili di flusso

Questo criterio non compila alcuna variabile per impostazione predefinita; tuttavia, puoi impostare (e ottenere) variabili di flusso nel codice JavaScript richiamando i metodi nell'oggetto di contesto. Un pattern tipico è simile al seguente:

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

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

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Apigee 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.

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

Codice di errore	Stato HTTP	Causa	Correggi
steps.javascript.ScriptExecutionFailed	500	Il criterio JavaScript può generare molti tipi diversi di errori ScriptExecutionFailed. I tipi di errori più comuni includono RangeError, ReferenceError, SyntaxError, TypeError ed URIError.
steps.javascript.ScriptExecutionFailedLineNumber	500	Si è verificato un errore nel codice JavaScript. Consulta la stringa dell'errore per i dettagli.	N/A
steps.javascript.ScriptSecurityError	500	Si è verificato un errore di sicurezza durante l'esecuzione di JavaScript. Consulta la stringa di errore per i dettagli.	N/A

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 errore	Causa	Correggi
InvalidResourceUrlFormat	Se il formato dell'URL della risorsa specificato nell'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 che non esiste, il deployment del proxy API non riesce. Il file di origine di riferimento deve esistere a livello di organizzazione, proxy API o ambiente.
WrongResourceType	Questo errore si verifica durante il deployment se gli elementi <ResourceURL> o <IncludeURL> del criterio JavaScript fanno riferimento a qualsiasi 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 viene dichiarato o se l'URL della risorsa non è definito all'interno di questo elemento. L'elemento <ResourceURL> è obbligatorio. In alternativa, viene dichiarato l'elemento <IncludeURL>, ma l'URL della risorsa non è definito all'interno di questo elemento. L'elemento <IncludeURL> è facoltativo, ma, se 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 maggiori informazioni, consulta la sezione Cosa devi sapere sugli errori dei criteri.

Variabili	Dove	Esempio
fault.name="fault_name"	fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di 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 consiste nell'eseguire il trap della parte errorcode della risposta di 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 criterio è definito da uno schema XML (.xsd). Per riferimento, gli schemi dei criteri sono disponibili su GitHub.

Argomenti correlati

• Modello a oggetti JavaScript

Articoli della community Apigee

Puoi trovare questi articoli correlati nella community Apigee:

• Come gestire le intestazioni multivalore in JavaScript?