Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza
documentazione di Apigee Edge.
Cosa
Questo criterio consente di aggiungere codice JavaScript personalizzato che viene eseguito nel contesto di un'API flusso proxy. Nel codice JavaScript personalizzato, puoi utilizzare gli oggetti, i metodi e le proprietà il modello a oggetti JavaScript di Apigee. Il modello a oggetti consente di ottenere, impostare e rimuovere variabili nel contesto del flusso proxy. Tu può anche utilizzare le funzioni crittografiche di base fornite con il modello a oggetti.
Questo criterio è una norma estendibile e il suo utilizzo potrebbe comportare costi o di utilizzo delle applicazioni, a seconda della licenza Apigee. Per informazioni sui tipi di norme e le implicazioni per l'utilizzo, consulta Tipi di criteri.
Informazioni
Esistono molti casi d'uso per il criterio JavaScript. Ad esempio, puoi ottenere e impostare il flusso variabili, eseguire logica personalizzata e gestire gli errori, estrarre i dati dalle richieste risposte rapide, modificare dinamicamente l'URL di destinazione del backend e altro ancora. Questo criterio consente di implementare un comportamento personalizzato non coperto da altri criteri Apigee standard. Infatti, è possibile usare un criterio JavaScript per ottenere molti degli stessi comportamenti implementati da altri criteri, comeAssignMessage ed ExtractVariable.
Un caso d'uso che non consigliamo per il criterio JavaScript è il logging. La Il criterio MessageLogging è molto più adatto per il logging su piattaforme di logging di terze parti come Splunk, Sumo e Loggly, puoi migliorare le prestazioni del proxy API eseguendo il criterio MessageLogging in PostClientFlow, che viene eseguita dopo che la risposta è stata inviata al client.
Il criterio JavaScript consente di specificare un file di origine JavaScript da eseguire o
puoi includere il codice JavaScript direttamente nella configurazione del criterio con <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 è sempre archiviato in un
posizione standard all'interno del bundle proxy: apiproxy/resources/jsc
. In alternativa, puoi anche
e archiviare il codice sorgente in un file di risorse a livello di ambiente o organizzazione. Per
istruzioni, vedi File di risorse. Puoi
e caricare il codice JavaScript tramite l'editor proxy della UI di Apigee.
I file sorgente JavaScript devono avere sempre un'estensione .js
.
Apigee supporta JavaScript che viene eseguito sul motore Rhino JavaScript 1.7.13.
Video
Guarda un breve video per imparare a creare un'estensione di una norma personalizzata utilizzando JavaScript .
Esempi
Riscrivi l'URL di destinazione
Ecco un caso d'uso comune: estrazione dei dati dal corpo di una richiesta, archiviazione in un flusso utilizzando la variabile di flusso altrove nel flusso proxy. Supponiamo che tu abbia un'app dove l'utente inserisce il proprio nome in un modulo HTML e lo invia. Vuoi che il proxy API estrarre i dati del modulo e aggiungerli dinamicamente all'URL utilizzato per chiamare il servizio di backend. Come lo faresti in una norma JavsScript?
- Nella UI di Apigee, apri il proxy che hai creato nell'editor proxy.
- Seleziona la scheda Sviluppo.
- Dal menu Nuovo, seleziona Nuovo script.
- Nella finestra di dialogo, seleziona JavaScript e assegna un nome allo script, ad esempio
js-example
. - Incolla il seguente codice nell'editor di codice e salva il proxy. La cosa importante
è l'oggetto
context
. Questo oggetto è disponibile per il codice JavaScript in qualsiasi punto del flusso del proxy. È usata per ottenere costanti specifiche del flusso, per richiamare get/set e per altre operazioni. Questa parte dell'oggetto fa parte Modello a oggetti JavaScript. Tieni presente che che la variabile di flussotarget.url
è una variabile integrata di lettura/scrittura che è accessibile nel flusso di richiesta target. Se impostiamo la variabile con l'URL dell'API, Apigee effettua la chiamata di backend a quell'URL. Fondamentalmente abbiamo riscritto l'URL di destinazione originale, ovvero il valore 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); }
- Dal menu Nuova norma, seleziona JavaScript.
- Assegna un nome al criterio, ad esempio
target-rewrite
. Accetta le impostazioni predefinite e salva il criterio. - Se selezioni il flusso di pre-flusso degli endpoint proxy nel Navigatore, vedrai che il criterio a quel flusso.
- Nel riquadro di navigazione, seleziona l'icona PreFlow endpoint di destinazione.
- Dal Navigatore, trascina il criterio JavaScript sul lato Richiesta della finestra Endpoint nell'editor del flusso.
- Salva.
- Chiama l'API in questo modo, sostituendo il nome corretto dell'organizzazione e il nome del proxy con appropriato:
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example
Infine, esaminiamo la definizione XML del criterio JavaScript utilizzato in
in questo esempio. È importante notare che il <ResourceURL>
viene utilizzato per specificare il file sorgente JavaScript da eseguire. Viene usato lo stesso pattern
per qualsiasi file sorgente JavaScript: jsc://filename.js
. Se il tuo codice JavaScript
richiede, puoi utilizzare uno o più elementi <IncludeURL>
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
con JavaScript in fase di esecuzione.
Utilizza l'attributo name
dell'elemento per specificare il nome con cui accedere all'elemento
proprietà del codice JavaScript. Il valore dell'elemento <Property>
(il valore
tra i tag di apertura e chiusura) è il valore letterale che riceverà
JavaScript.
In JavaScript, puoi recuperare il valore della proprietà del criterio accedendo come proprietà del metodo
Oggetto Properties
, come nell'esempio seguente:
- 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, ossia 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 una callout JavaScript; consulta Metodo corretto per restituire un errore dal criterio JavaScript. I suggerimenti offerti nella community Apigee sono relativi informazioni e non rappresentano necessariamente le best practice consigliate da Google.
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>
<Javascript> Attributi
<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">
Gli attributi riportati di seguito sono specifici di questo criterio.
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
timeLimit |
Specifica il tempo massimo (in millisecondi) che lo script può eseguire
eseguire il deployment. Ad esempio, se viene superato un limite di 200 ms, il criterio genera il seguente errore:
|
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 Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
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 |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
<IncludeURL> elemento
Specifica un file della 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 nelle norme. Il codice può utilizzare oggetti, metodi
del modello a oggetti JavaScript.
Includi più di una risorsa di dipendenza JavaScript con
<IncludeURL>
elementi.
<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
Predefinita: | Nessuno |
Presenza: | Facoltativo |
Tipo: | Stringa |
Esempio
Consulta l'esempio di base nella sezione Samples.
<Property> elemento
Specifica una proprietà a cui puoi accedere dal codice JavaScript in fase di runtime.
<Properties> <Property name="propName">propertyValue</Property> </Properties>
Predefinita: | 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.
<ResourceURL> elemento
Specifica il file JavaScript principale che verrà eseguito nel flusso dell'API. Puoi archiviare questo file
nell'ambito del proxy API (in /apiproxy/resources/jsc
nel bundle proxy API o
sezione Script del riquadro di navigazione dell'editor proxy API) o a livello di organizzazione
Ambiti di ambiente per il riutilizzo in più proxy API, come descritto in Gestione delle risorse. Il codice può utilizzare gli oggetti,
metodi e proprietà del modello a oggetti JavaScript.
<ResourceURL>jsc://my-javascript.js</ResourceURL>
Predefinita: | Nessuno |
Presenza: | È obbligatorio specificare <ResourceURL> o <Source> . Se
<ResourceURL> e <Source> sono entrambi presenti <ResourceURL> viene ignorato. |
Tipo: | Stringa |
Esempio
Consulta l'esempio di base nella sezione Samples.
<Source> elemento
Consente di inserire JavaScript direttamente nella configurazione XML del criterio. Il valore inserito Il codice JavaScript viene eseguito quando il criterio viene eseguito nel flusso dell'API.
Predefinita: | Nessuno |
Presenza: | È obbligatorio specificare <ResourceURL> o <Source> . Se
<ResourceURL> e <Source> sono entrambi presenti <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>
<SSLInfo> elemento
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>
Predefinita: | Nessuno |
Presenza: | Facoltativo |
Tipo: | Stringa |
La procedura per configurare TLS per un client HTTP è la stessa che utilizzi per configurare TLS per un TargetEndpoint/TargetServer. Per ulteriori informazioni, vedi Opzioni per la configurazione di TLS.
Note sull'utilizzo
Debug del codice del criterio JavaScript
Utilizza la funzione print()
per inviare le informazioni di debug alla transazione
riquadro di output nello strumento di debug. Per dettagli ed esempi, vedi Debug con JavaScript
print()
estratti conto.
Per visualizzare le istruzioni di stampa in Debug:
- Apri lo strumento di debug e avvia una sessione di traccia per un proxy contenente il codice JavaScript .
- Chiama il proxy.
- Nello strumento di debug, fai clic su Output di tutte le transazioni per aprire l'output
dal riquadro.
- Gli estratti conto cartacei verranno visualizzati in questo riquadro.
Puoi utilizzare la funzione print()
per inviare le informazioni di debug allo strumento di debug. Questa funzione è disponibile direttamente
attraverso il modello a oggetti JavaScript. Per maggiori dettagli, vedi
Esegui il debug di JavaScript con le istruzioni Print().
Variabili di flusso
Questo criterio non compila le variabili per impostazione predefinita. ma puoi impostare (e ottenere) il flusso nel tuo codice JavaScript richiamando metodi sull'oggetto di contesto. Un modello tipico ha il seguente aspetto:
context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"))
L'oggetto 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.
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. |
build |
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.
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. |
build |
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. |
build |
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 ). |
build |
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> . |
build |
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
{ "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,
schemi di criteri
sono disponibili su GitHub.
Argomenti correlati
Articoli della community Apigee
Puoi trovare questi articoli correlati nella community Apigee: