Invio delle richieste a un proxy

Utilizzando un server proxy fornito dalla rete CDN di Managed Runtime è possibile eseguire il routing delle richieste alle API ospitate su domini diversi attraverso lo stesso dominio dello storefront.
Associated diagram

Perché utilizzare lo stesso dominio dello storefront? Si supponga che lo storefront sia ospitato su www.northerntrailoutfitters.com e che si intenda recuperare i dati di e-commerce con una richiesta a api.commercecloud.salesforce.com. L'esecuzione di questa richiesta senza l'invio al proxy comporta fasi di configurazione aggiuntive ed è un'operazione meno veloce e osservabile. Ecco un confronto tra i due approcci.

Senza invio al proxyCon invio al proxy
È necessario configurare il server API affinché risponda con intestazioni CORS (Cross-Origin Resource Sharing).Nessuna configurazione supplementare richiesta per CORS.
Le richieste API prevedono una richiesta preliminare supplementare, rallentando le prestazioni.Nessuna richiesta di rete supplementare effettuata.
Se il server API non memorizza in cache le risposte, si perde un'opportunità di notevole miglioramento delle prestazioni.È possibile istruire la rete CDN di Managed Runtime a memorizzare in cache richieste specifiche.
Se i registri per il server API non sono accessibili, è difficile misurare l'impatto sulle prestazioni complessive.Vengono registrate tutte le richieste API sottoposte a routing attraverso la rete CDN di Managed Runtime tramite proxy.

Dopo aver illustrato l'importanza dei proxy, vengono analizzati i vari metodi per configurarli.

Per lo sviluppo locale, il metodo principale per configurare i proxy consiste nel modificare la matrice mobify.ssrParameters.proxyConfigs in <PROJECT_DIR>/config/default.js:

La matrice proxyConfigs contiene oggetti che definiscono una configurazione proxy con le seguenti proprietà:

  • host: l'host che riceve le richieste, inclusi dominio e sottodomini.
  • path: la stringa utilizzata nei percorsi delle richieste per attivare l'invio al proxy.
  • protocol: il protocollo di rete (http o https). Facoltativo (il valore predefinito è https).

Per effettuare una richiesta proxy nel codice dell'applicazione, costruire i percorsi delle richieste seguendo questo modello: /mobify/proxy/<PROXY_PATH>.

Se si possiedono molte configurazioni proxy diverse, scegliere i percorsi proxy che consentono di riconoscere facilmente le API utilizzate.

Si esamini una richiesta di esempio che utilizza api come valore <PROXY_PATH>. Tutti i progetti creati con PWA Kit presentano una configurazione predefinita che associa il percorso api a Salesforce Commerce API.

La seguente richiesta di esempio presenta inoltre due funzioni helper per garantire un funzionamento coerente delle richieste API:

  1. getAppOrigin da PWA Kit React SDK restituisce l'origine corretta per gli ambienti Managed Runtime e di sviluppo locale.
  2. fetch dalla libreria cross-fetch gestisce le differenze tra le richieste di rete effettuate in un browser e quelle in Node.js.

Ogni volta che la configurazione proxy viene modificata durante lo sviluppo locale, è necessario riavviare il server di sviluppo locale affinché le modifiche abbiano effetto.

Managed Runtime ignora le impostazioni proxy in default.js e altri file di configurazione in app/config a meno che il nome file non corrisponda al nome di un ambiente Managed Runtime. Per ulteriori informazioni, vedere le configurazioni specifiche per ambiente.

La configurazione dei proxy per gli ambienti Managed Runtime può avvenire in due modi: con lo strumento Runtime Admin o con Managed Runtime API.

Uso di Runtime Admin

Per configurare i proxy per un ambiente Managed Runtime mediante lo strumento di amministrazione basato sul Web, seguire questa procedura:

  1. Accedere allo strumento Runtime Admin.
  2. Fare clic sul progetto.
  3. Fare clic su un ambiente.
  4. Fare clic su Environment Settings (Impostazioni ambiente) nel menu di navigazione a sinistra.
  5. Nella sezione Advanced (Avanzate), fare clic su Edit (Modifica).
  6. In Proxy Configs (Configurazioni proxy), fare clic su Add New Proxy (Aggiungi nuovo proxy).
  7. Inserire percorso, protocollo e host.
  8. Ripetere la procedura per un massimo di 8 configurazioni proxy.
  9. Tornare all'inizio della sezione Advanced (Avanzate) e fare clic su Update (Aggiorna).
  10. Attendere la fine della redistribuzione del bundle.
  11. Verificare che la configurazione proxy funzioni come previsto.

Screenshot di Runtime Admin

Uso di Managed Runtime API

È possibile configurare i proxy per gli ambienti Managed Runtime anche a livello di programmazione utilizzando l'endpoint /target di Managed Runtime API. (In Managed Runtime API viene utilizzato spesso il termine "target" anziché "ambiente", ma entrambi si riferiscono allo stesso concetto.)

Quando si creano o si aggiornano gli ambienti, il corpo della richiesta JSON accetta una matrice di oggetti di configurazione proxy da un campo denominato ssr_proxy_configs. Tali oggetti sono definiti con le proprietà host, path e protocol (facoltativa), come nei file di configurazione.

Di seguito una richiesta di esempio che aggiorna un ambiente per includere una configurazione proxy per il percorso api:

Per evitare i tempi di inattività, o downtime, è necessario eseguire la procedura di aggiunta o rimozione di proxy in un ambiente Production seguendo un ordine specifico.

Per aggiungere un proxy a un ambiente Production:

  1. Modificare le impostazioni dell'ambiente Production utilizzando Runtime Admin o Managed Runtime API. (Seguire le istruzioni descritte in precedenza.)
  2. Aggiungere il nuovo proxy alle impostazioni dell'ambiente e salvare le modifiche.
  3. Aggiornare il codice PWA Kit per utilizzare il nuovo proxy.
  4. Eseguire il push di un nuovo bundle del codice PWA Kit a Managed Runtime.
  5. Distribuire il nuovo bundle.

Per rimuovere un proxy da un ambiente Production:

  1. Aggiornare il codice PWA Kit per utilizzare il nuovo proxy.
  2. Eseguire il push di un nuovo bundle del codice PWA Kit a Managed Runtime.
  3. Distribuire il nuovo bundle.
  4. Modificare le impostazioni dell'ambiente Production utilizzando Runtime Admin o Managed Runtime API. (Seguire le istruzioni descritte in precedenza.)
  5. Rimuovere il nuovo proxy dalle impostazioni dell'ambiente e salvare le modifiche.

È possibile sostituire le configurazioni proxy per l'ambiente di sviluppo locale impostando variabili di ambiente.

Impostare una variabile di ambiente denominata SSR_PROXY1 per sostituire il primo elemento nella matrice proxyConfigs, impostarne una denominata SSR_PROXY2 per sostituire il secondo elemento e così via.

Funzionamento: se è impostata su https://api-staging.example.com/api, la variabile di ambiente SSR_PROXY1 sostituisce il primo elemento nella matrice proxyConfigs con il seguente oggetto di configurazione proxy:

Per poter utilizzare istanze diverse dell'host API, ad esempio Staging o Production, queste variabili di ambiente sono comunemente usate con il comando npm start durante lo sviluppo locale. Nel seguente esempio viene sostituito il primo oggetto di configurazione proxy per fare in modo che il percorso api esegua il routing delle richieste a un'istanza Staging:

Dopo aver configurato le impostazioni proxy, è possibile ricercarle utilizzando la funzione di utilità getProxyConfigs da PWA Kit React SDK. Ad esempio, è possibile utilizzare un ID client diverso a seconda dell'ambiente in cui viene eseguito il codice:

Quando una richiesta viene sottoposta a routing attraverso il server proxy, sia la richiesta sia la risposta vengono modificate in modo da renderne trasparente il funzionamento con il codice dell'applicazione.

Gli esempi forniti in questa sezione presuppongono che l'app sia ospitata su www.northerntrailoutfitters.com e configurata per l'invio delle richieste al proxy api.commercecloud.com.

Modifiche - Richiesta

Le seguenti modifiche sono applicate alla richiesta prima del suo invio all'host:

  • Rimozione del prefisso /mobify/proxy/<PROXY_PATH>/.
  • Aggiunta dell'intestazione HTTP X-Mobify: true.

Le richieste inviate al proxy inoltrano anche tutti i parametri di stringa di query e tutte le intestazioni, inclusi i cookie.

Modifiche - Risposta

Le seguenti modifiche sono applicate alla risposta prima del suo invio al client:

  • Aggiunta di un'intestazione HTTP di X-Request-Url: <URL> insieme all'URL richiesto.
  • Se la risposta è un reindirizzamento e ha un'intestazione Location con host corrispondente all'host del proxy, all'host viene aggiunto il prefisso /mobify/proxy/<PROXY_PATH>/.
  • Se la risposta contiene intestazioni Set-Cookie con domain corrispondente all'host del proxy, queste vengono aggiornate in modo da corrispondere. Ad esempio, Set-Cookie: key=val; domain=api.commercecloud.com viene aggiornato a Set-Cookie: key=val; domain=www.northerntrailoutfitters.com.
  • Se la risposta contiene un'intestazione Access-Control-Allow-Origin con valore corrispondente all'host del proxy, questa viene aggiornata ad Access-Control-Allow-Origin: https://www.northerntrailoutfitters.com.

Per testare le modifiche, effettuare una configurazione proxy con httpbin.org come host. Se si effettua una richiesta tramite tale proxy, questo ritrasmette qualsiasi intestazione ricevuta.

Per impostazione predefinita, le richieste proxy non vengono memorizzate in cache dalla rete CDN. Grazie a questa impostazione, le richieste proxy vengono utilizzate in modo trasparente nel codice, senza presentare problemi di caching non corretto delle risposte.

Se si desidera che una richiesta proxy venga effettivamente memorizzata in cache dalla rete CDN, modificare il prefisso del percorso utilizzato nella richiesta da proxy a caching.

Dettagli del caching

Le richieste proxy memorizzate nella cache presentano le seguenti differenze rispetto alle richieste proxy standard:

  • L'intestazione HTTP Cookie viene rimossa.

Le risposte memorizzate nella cache presentano le seguenti differenze rispetto alle risposte standard:

  • Tutte le intestazioni HTTP Set-Cookie vengono rimosse.

Le risposte nella cache includono le seguenti intestazioni HTTP. Pertanto, quando i valori delle intestazioni cambiano, le risposte vengono memorizzate in cache separatamente:

  • Accept
  • Accept-Charset
  • Accept-Encoding
  • Accept-Language
  • Authorization
  • Range

Le risposte che includono altre intestazioni HTTP non vengono memorizzate in cache separatamente quando i relativi valori cambiano.

  • Gli host proxy devono utilizzare le versioni 1.2 o successive del protocollo TLS (Transport Level Security) quando protocol è impostato su https.

Dopo aver appreso in che modo e per che motivo utilizzare i proxy nell'app di e-commerce, continuare a consultare la documentazione su PWA Kit.