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.

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.

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

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

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

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.

È 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 eseguire l'override delle configurazioni proxy per l'ambiente di sviluppo locale impostando variabili di ambiente.

Impostare una variabile di ambiente denominata SSR_PROXY1 per eseguire l'override del primo elemento nella matrice proxyConfigs, impostarne una denominata SSR_PROXY2 per eseguire l'override del 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 eseguito l'override del 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.

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.

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.

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.

I proxy hanno vincoli diversi rispetto all'App Server.

• Il tempo di esecuzione per le richieste proxy è limitato a 30 secondi. Se una risposta dall'origine non viene completata entro questo limite di tempo, viene restituito un errore HTTP 504.
• Gli host proxy devono utilizzare le versioni 1.2 o successive del protocollo TLS (Transport Level Security) quando protocol è impostato su https.
• Non sono previsti limiti per le dimensioni delle richieste o delle risposte.
• Le richieste proxy possono utilizzare l'intestazione Cookie. Le risposte proxy possono includere l'intestazione Set-Cookie.
• L'host proxy deve essere indirizzabile pubblicamente.

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.