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

I file di origine JavaScript devono avere un'estensione .js. Apigee supporta JavaScript in esecuzione sul motore JavaScript Rhino 1.7.13.

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 alle prestazioni e all'ottimizzazione delle policy Apigee.
Per eseguire chiamate di sistema. Il modello di sicurezza non consente chiamate di sistema dal criterio JavaScript. Ad esempio, non sono consentite letture o scritture del file system interno, informazioni sull'utente corrente, elenchi di processi o utilizzo di CPU/memoria. Anche se alcune chiamate potrebbero funzionare, non sono supportate e possono essere disattivate in qualsiasi momento. Per la compatibilità futura, evita di effettuare queste chiamate nel codice.

Queste norme sono estendibili e il loro utilizzo potrebbe avere implicazioni in termini di costi o 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 una policy JavaScript.

Nota:per provare questo esempio, crea un nuovo proxy nell'editor dei proxy. Quando crei il proxy, fornisci un URL del servizio di backend, ad esempio http://www.example.com. Questo esempio riscrive dinamicamente l'URL backend. Se devi creare un nuovo proxy, consulta il tutorial introduttivo.

Nell'interfaccia utente di Apigee, apri il proxy che hai creato nell'editor proxy.
Seleziona la scheda Sviluppa.
Nel menu Nuovo, seleziona Nuovo script.
Nella finestra di dialogo, seleziona JavaScript e assegna allo script il nome js-example.
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 al momento della 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);
}
```
Nel menu Nuova norma, seleziona JavaScript.
Assegna al criterio il nome target-rewrite. Accetta i valori predefiniti e salva le norme.
Dopo aver selezionato Proxy Endpoint Preflow in Navigator, il criterio viene aggiunto al flusso.
In Navigator, seleziona Target Endpoint PreFlow.
Nel Navigator, trascina il criterio JavaScript sul lato Request dell'endpoint di destinazione nell'editor di flusso.
Salva.
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);

All'interno di un criterio JavaScript, l'accesso a request.content.asJSON in modalità di sola lettura converte i numeri interi grandi in notazione esponenziale nel corpo del messaggio. In questo modo, il messaggio viene 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>

< 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 può essere eseguito uno 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 senza costi aggiuntivi, 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	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: 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 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

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

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

Avviso: se i file JavaScript sono archiviati a livello di proxy o ambiente, assicurati di caricarli correttamente con cURL utilizzando l'opzione -F o come allegato di file tramite un client REST. Il valore Content-Type è multipart/form-data. Per saperne di più, consulta Gestione delle risorse.

<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 saperne di più, consulta Opzioni per la configurazione di TLS.

Utilizzare JavaScript per gestire gli errori

Puoi utilizzare la policy JavaScript per gestire e restituire gli errori. Per una discussione su questo argomento, vedi Correct way to return an error from a JavaScript policy nella community Apigee. Tieni presente che i post e i commenti della community non rappresentano necessariamente le best practice consigliate da Apigee.

Eseguire il debug del codice del criterio JavaScript

Utilizza la funzione print() per visualizzare le informazioni di debug nel riquadro di output delle transazioni dello 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:

Apri lo strumento di debug e avvia una sessione di traccia per un proxy che contiene la tua policy JavaScript.
Chiama il proxy.
Nello strumento di debug, fai clic sul criterio JavaScript, poi sulla scheda Proprietà per visualizzare la proprietà "stepExecution-stdout" che mostra l'output dell'istruzione di stampa.
In questo riquadro vengono visualizzati i tuoi estratti conto stampati.

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

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee 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.

Fault code	HTTP status	Cause	Fix
`steps.javascript.ScriptExecutionFailed`	`500`	The `JavaScript` policy can throw many different types of `ScriptExecutionFailed` errors. Commonly seen types of errors include RangeError, ReferenceError, SyntaxError, TypeError, and URIError.
`steps.javascript.ScriptExecutionFailedLineNumber`	`500`	An error occurred in the `JavaScript` code. See the fault string for details.	N/A
`steps.javascript.ScriptSecurityError`	`500`	A security error occurred when the `JavaScript` executed. See the fault string for details.	N/A

Deployment errors

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

Error name	Cause	Fix
`InvalidResourceUrlFormat`	If the format of the resource URL specified within the `<ResourceURL>` or the `<IncludeURL>` element of the `JavaScript` policy is invalid, then the deployment of the API proxy fails.
`InvalidResourceUrlReference`	If the `<ResourceURL>` or the `<IncludeURL>` elements refer to a `JavaScript` file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level.
`WrongResourceType`	This error occurs during deployment if the `<ResourceURL>` or the `<IncludeURL>` elements of the `JavaScript` policy refer to any resource type other than jsc (`JavaScript` file).
`NoResourceURLOrSource`	The deployment of the `JavaScript` policy can fail with this error if the `<ResourceURL>` element is not declared or if the resource URL is not defined within this element. `<ResourceURL>` element is a mandatory element. Or, The `<IncludeURL>` element is declared but the resource URL is not defined within this element. The `<IncludeURL>` element is optional but if declared, the resource URL must be specified within the `<IncludeURL>` element.

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.

Variables	Where	Example
`fault.name="fault_name"`	`fault_name` is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	`fault.name Matches "ScriptExecutionFailed"`
`javascript.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`javascript.JavaScript-1.failed = true`

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
  "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

Articoli della community Apigee

Puoi trovare questi articoli correlati nella community Apigee:

Come gestire le intestazioni con più valori in JavaScript

Norme JavaScript Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Esempi

Riscrivere l'URL di destinazione

Recuperare il valore della proprietà da JavaScript

Riferimento elemento

Attributi <Javascript>

Elemento <DisplayName>

Elemento <IncludeURL>

Elemento <Property>

Attributi

Esempio

Elemento <ResourceURL>

Esempio

Elemento <Source>

Esempio

Elemento <SSLInfo>

Utilizzare JavaScript per gestire gli errori

Eseguire il debug del codice del criterio JavaScript

Variabili di flusso

Messaggi di errore

Runtime errors

Deployment errors

Fault variables

Example error response

Example fault rule

Schema

Argomenti correlati

Articoli della community Apigee

Norme JavaScript