Norme JavaScript

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

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

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 criteri e sulle implicazioni di utilizzo, consulta Tipi di criteri.

Informazioni

Esistono molti casi d'uso per il criterio JavaScript. Ad esempio, puoi ottenere e impostare variabili di flusso, eseguire logica personalizzata e gestire gli errori, estrarre dati da richieste o risposte, modificare dinamicamente l'URL di destinazione backend e molto altro ancora. Questa policy ti consente di implementare un comportamento personalizzato non coperto da altre policy 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 la norma JavaScript è la registrazione. Il criterio MessageLogging è molto più adatto per la registrazione su piattaforme di logging di terze parti come Splunk, Sumo e Loggly e migliori 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 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.

Apigee supporta JavaScript eseguito sul motore JavaScript Rhino 1.7.13.

Video

Guarda un breve video per scoprire come creare un'estensione dei criteri personalizzata utilizzando i criteri JavaScript.

Esempi

Riscrivere l'URL di destinazione

Ecco un caso d'uso comune: estrarre i dati dal corpo di una richiesta, memorizzarli in una variabile di flusso e utilizzarli 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 una policy JavaScript?

  1. Nell'interfaccia utente 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 un nome allo script, ad esempio js-example.
  5. Incolla il seguente codice nell'editor di codice e salva il proxy. L'aspetto 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 presente che la variabile di flusso target.url è una variabile integrata di lettura/scrittura accessibile nel flusso della richiesta target. Quando impostiamo questa variabile con l'URL API, Apigee effettua la chiamata di backend a questo URL. Abbiamo essenzialmente riscritto l'URL di destinazione originale, che era 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 alla policy, ad esempio target-rewrite. Accetta i valori predefiniti e salva le norme.
  8. Se selezioni Proxy Endpoint Preflow nel navigatore, vedrai che il criterio è stato aggiunto a questo flusso.
  9. Nel navigatore, seleziona l'icona Target Endpoint PreFlow.
  10. Dal navigatore, trascina la policy JavaScript sul lato Richiesta dell'endpoint di destinazione nell'editor del flusso.
  11. Salva.
  12. Chiama l'API in questo modo, sostituendo il nome dell'organizzazione e il nome del proxy corretti in base alle tue esigenze:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

Infine, diamo un'occhiata alla definizione XML per i criteri JavaScript utilizzati in questo esempio. La cosa importante da notare è che l'elemento <ResourceURL> viene utilizzato per specificare il file di origine JavaScript da eseguire. Questo stesso pattern viene utilizzato per qualsiasi file di origine JavaScript: jsc://filename.js. Se il tuo codice JavaScript richiede inclusioni, puoi utilizzare uno o più elementi <IncludeURL> per eseguirle, 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> 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 i tag di apertura e chiusura) è il valore letterale che verrà ricevuto da JavaScript.

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

  • 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 il nome di una variabile, viene quindi 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 Modo corretto per restituire l'errore dalla policy JavaScript. I suggerimenti offerti 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>

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

I seguenti attributi sono specifici di queste norme.

Attributo Descrizione Predefinito Presenza
timeLimit

Specifica il tempo massimo (in millisecondi) consentito 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.

 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 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>
Predefinito: Nessuno
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>
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 verrà eseguito nel flusso 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 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>, <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.

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 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 che utilizzi 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 delle norme 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, vedi Debug con istruzioni JavaScript print().

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

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 di Apigee: