Proxy API di programmazione con JavaScript

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. informazioni

In questo argomento imparerai a utilizzare JavaScript per aggiungere in modo dinamico intestazioni HTTP a un messaggio di risposta, nonché ad analizzare una risposta JSON e restituire un sottoinsieme delle sue proprietà all'app richiedente.

Scarica e prova il codice campione

Informazioni su questo esempio di libro di ricette

Questo esempio di ricettario illustra un pattern del proxy API in cui implementi il comportamento dell'API in JavaScript. Gli esempi JavaScript sono progettati per mostrare come utilizzare variabili semplici e contenuti dei messaggi. Un esempio mostra come ottenere e impostare le variabili. Il secondo esempio mostra come analizzare JSON e creare un messaggio a partire dal risultato.

Nel proxy API sono presenti due esempi di JavaScript:

  • setHeaders.js: questo codice JavaScript riceve i valori di alcune variabili che vengono impostati quando viene richiamato un proxy API. Il codice JavaScript aggiunge queste variabili al messaggio di risposta in modo che tu possa vederne i valori per ogni richiesta che effettui.
  • minimize.js: questo codice JavaScript mostra come utilizzare i contenuti dei messaggi. L'idea alla base di questo esempio è che un servizio spesso restituisce più dati del necessario. Quindi, il codice JavaScript analizza il messaggio di risposta, estrae alcune proprietà interessanti e quindi le utilizza per creare i contenuti del messaggio di risposta.

Codice di setHeader.js:

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

Codice di minimize.js:

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

Puoi accedere alle variabili di flusso in JavaScript tramite l'oggetto di contesto. Questo oggetto fa parte del modello a oggetti JavaScript Edge. Per maggiori dettagli sul modello a oggetti, consulta la sezione Modello a oggetti JavaScript.

Prima di iniziare

Prima di esplorare l'esempio di questo libro di ricette, dovresti anche acquisire familiarità con questi concetti fondamentali:

  • Cosa sono i criteri e come collegarli ai proxy. Per un'introduzione alle norme, consulta la sezione Che cosa sono i criteri?.
  • La struttura di un flusso proxy, come spiegato in Configurare i flussi. I flussi consentono di specificare la sequenza in cui i criteri vengono eseguiti da un proxy API. In questo esempio, vengono creati e aggiunti diversi criteri a un flusso proxy API.
  • Modalità di organizzazione di un progetto proxy API nel file system, come spiegato nella documentazione di configurazione del proxy API.
  • Conoscenza pratica di XML, JSON e JavaScript. In questo esempio, creerai il proxy API e i relativi criteri con i file XML che risiedono nel file system.

Se hai scaricato il codice di esempio, puoi individuare tutti i file discussi in questo argomento nella cartella di esempio javascript-cookbook. Le seguenti sezioni illustrano in dettaglio il codice di esempio.

Informazioni sul flusso proxy

Per eseguire JavaScript in un proxy API, devi collegarlo a un flusso utilizzando un allegato del criterio denominato "Passaggio". Un criterio di tipo JavaScript (nota con le lettere maiuscole) contiene semplicemente un riferimento al nome di un file JavaScript. Devi indirizzare il criterio a un file JavaScript utilizzando l'elemento ResourceURL.

Ad esempio, il criterio seguente fa riferimento al file JavaScript denominato setHeader.js.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

Puoi collegare questo criterio a un flusso proxy API come qualsiasi altro tipo di criterio. Se colleghi il criterio al flusso proxy API, indichi dove deve essere eseguito il codice JavaScript. Ciò consente di eseguire JavaScript che interagisce con i messaggi di richiesta o di risposta mentre questi messaggi "fluiscono" attraverso il proxy API. In questo esempio, entrambi i JavaScript vengono eseguiti nel flusso di risposta, poiché i criteri svolgono due operazioni: impostare le intestazioni HTTP nel messaggio di risposta e "ridurre al minimo" il messaggio di risposta che Apigee Edge restituisce all'app richiedente.

Se apri questa configurazione del flusso nell'interfaccia utente di gestione, vedrai la configurazione del flusso di seguito.

Seleziona Endpoint proxy > predefinito > PostFlow nel riquadro di navigazione.

Di seguito è mostrata la configurazione XML corrispondente per ProxyEndpoint denominata "default". 

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

Ecco un riepilogo degli elementi del flusso.

  • <Request>: l'elemento <Request> è composto da diversi elementi <Step>. Ogni passaggio chiama uno dei criteri che crei nel resto di questo argomento. Questi criteri collegano un codice JavaScript al flusso proxy API e la posizione del collegamento del criterio determina quando viene eseguito il codice JavaScript.
  • <Response>: l'elemento <Response> include anche <Steps>. Questi passaggi includono anche i criteri di chiamata che sono responsabili dell'elaborazione della risposta finale dal target (che in questo esempio è il target di servizio fittizio di Apigee; tieni presente l'impostazione HTTPTargetConnection in /apiproxy/targets/default.xml).
  • <HTTPProxyConnection>: specifica il percorso host e URI che definiscono l'indirizzo di rete che le app chiamano per utilizzare l'API.
  • <RouteRule>: questo elemento specifica quale configurazione TargetEndpoint viene richiamata da ProxyEndpoint.

Aggiunta di codice JavaScript a un proxy

JavaScript (come gli script Python, i file JAR Java, i file YAML e così via) vengono archiviati come risorse. Quando inizi a lavorare con JavaScript, è più facile archiviare i tuoi file JavaScript nel proxy API. Man mano che procedi, JavaScript deve essere reso il più possibile generico e riutilizzabile e poi archiviato a livello di ambiente o organizzazione. In questo modo, eviti di dover archiviare gli stessi file JavaScript in più proxy API, che possono diventare rapidamente ingestibili.

Per scoprire di più sull'archiviazione delle risorse a livello di organizzazione e ambiente, vedi File di risorse.

Prova

Per istruzioni sul deployment e sulla chiamata del proxy, consulta il file README del ricettario JavaScript.

Importazione e deployment del proxy API

Dopo aver apportato le modifiche, puoi salvare il proxy API nello strumento di creazione dei proxy API nell'interfaccia utente di gestione.

In alternativa, puoi eseguire il comando seguente nella directory /api-platform-samples/doc-samples/javascript-cookbook.

$ sh deploy.sh

Test di JavaScript

Esegui questo comando nella directory /api-platform-samples/doc-samples/javascript-cookbook.

$ sh invoke.sh

Il flag curl -v viene utilizzato nello script shell per visualizzare le intestazioni HTTP nel messaggio di risposta modificato da JavaScript.

Puoi inviare una richiesta direttamente come indicato di seguito:

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook

Se JavaScript viene eseguito correttamente, verrà visualizzata una risposta simile alla seguente:

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

Ora puoi modificare il codice JavaScript per provare nuove soluzioni, eseguire nuovamente il deployment del proxy API e verificare i risultati inviando la stessa richiesta. Assicurati sempre di eseguire il deployment del proxy API che contiene il codice JavaScript per applicare le modifiche.

Errori di script

Inevitabilmente noterai degli errori durante la scrittura del codice JavaScript. Di seguito è mostrato il formato degli errori JavaScript che noterai inviati da un proxy API.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

Quando utilizzare JavaScript

Su Apigee Edge, di solito esiste più di un modo per implementare funzionalità specifiche. Se possibile, utilizza criteri pronti all'uso ed evita la tentazione di codificare tutta la logica del proxy API in JavaScript. Anche se Apigee Edge utilizza il codice JavaScript compilato per migliorare le prestazioni, è improbabile che JavaScript abbia le stesse prestazioni dei criteri. JavaScript potrebbe essere più difficile da gestire ed eseguire il debug. Prenota JavaScript per le funzionalità specifiche per i tuoi requisiti.

Se le funzionalità personalizzate ti preoccupano le prestazioni, utilizza Java dove possibile.

Riepilogo

In questo argomento di ricettario hai imparato come è possibile includere JavaScript in una configurazione proxy API per implementare un comportamento personalizzato. Il comportamento personalizzato implementato dagli esempi mostra come recuperare e modificare le variabili, nonché come analizzare il codice JSON e creare messaggi di risposta personalizzati.