Requests via proxy

À l’aide d’un serveur proxy fourni par le CDN de Managed Runtime, vous pouvez router les requests vers les API hébergées sur différents domaines via le même domaine que votre boutique.

Pourquoi utiliser le même domaine que votre boutique ? Supposez que votre boutique est hébergée à l'adresse www.northerntrailoutfitters.com et que vous souhaitez récupérer des données commerciales en envoyant une request à api.commercecloud.salesforce.com. Lancer cette request sans utiliser de proxy implique des étapes de configuration supplémentaires et ce n'est pas aussi rapide et aussi facile à observer qu'avec un proxy. Comparons les deux approches.

Maintenant que vous comprenez l'intérêt d'utiliser des proxies, explorons les différentes méthodes permettant de les configurer.

Pour le développement local, la principale façon de configurer les proxies consiste à modifier le tableau mobify.ssrParameters.proxyConfigs dans <PROJECT_DIR>/config/default.js :

Le tableau proxyConfigs contient des objets qui définissent une configuration de proxy avec les propriétés suivantes :

• host : l'hôte qui reçoit vos requests, y compris le domaine et les sous-domaines.
• path : la chaîne utilisée dans vos chemins d'accès de request pour déclencher l'utilisation d'un proxy.
• protocol : le protocole réseau (http ou https). Facultatif (la valeur par défaut est https).

Pour lancer une request en proxy dans votre code d'application, suivez ce schéma lors de la construction de vos chemins de request : /mobify/proxy/<PROXY_PATH>.

Examinons un exemple de request qui utilise api comme valeur de <PROXY_PATH>. Par défaut, tous les projets créés avec PWA Kit sont livrés avec une configuration par défaut qui associe le chemin api à Salesforce Commerce API.

Dans l'exemple, notre request comporte également deux fonctions d'aide pour garantir que les requests API fonctionnent de manière cohérente :

1. getAppOrigin, du SDK React de PWA Kit, renvoie l’origine correcte pour l’environnement de développement local et celui de Managed Runtime.
2. fetch, de la bibliothèque cross-fetch, gère les différences entre les requests réseau effectuées dans un navigateur et celles effectuées dans Node.js.

À chaque modification de configuration de votre proxy pendant le développement local, vous devez redémarrer votre serveur de développement local pour que les modifications prennent effet.

Vous avez deux possibilités pour configurer les proxies pour les environnements Managed Runtime : à l'aide de l'outil Runtime Admin, ou à l'aide de l'API Managed Runtime.

Utiliser Runtime Admin

Pour configurer les proxies pour un environnement Managed Runtime à l'aide de notre outil d'administration Web, procédez comme suit :

1. Connectez-vous à l'outil Runtime Admin.
2. Cliquez sur votre projet.
3. Cliquez sur un environnement.
4. Cliquez sur Environment Settings (Paramètres d'environnement) dans le menu de navigation de gauche.
5. Dans la section Advanced (Avancés), cliquez sur Edit (Modifier).
6. Sous Proxy Configs (Configurations de proxy), cliquez sur Add New Proxy (Ajouter un nouveau proxy).
7. Indiquez le chemin d'accès, le protocole et l'hôte.
8. Répétez l'opération pour un maximum de 8 configurations de proxy.
9. Revenez au début de la section Advanced et cliquez sur Update (Mettre à jour).
10. Attendez que le paquet finisse de se redéployer.
11. Vérifiez que la configuration du proxy fonctionne comme prévu.

Utiliser l’API Managed Runtime

Vous pouvez également configurer des proxies pour les environnements Managed Runtime à l'aide de la programmation en utilisant le point de terminaison /target de l'API Managed Runtime. (L'API Managed Runtime utilise souvent le terme « target », soit cible, au lieu d'environnement, mais les deux termes font référence à la même chose).

Lors de la création ou de la mise à jour d'environnements, le corps de la request JSON accepte un tableau d'objets de configuration de proxy à partir d'un champ appelé ssr_proxy_configs. Ces objets de configuration de proxy sont définis de la même manière que dans les fichiers de configuration à l’aide des propriétés host, path et protocol (facultatif).

Voici un exemple de request qui met à jour un environnement pour inclure une configuration de proxy pour le chemin d'accès api :

Pour éviter les temps d'arrêt, les étapes d'ajout ou de suppression des proxies dans un environnement de production doivent respecter un ordre précis.

Pour ajouter un proxy à un environnement de production :

1. Modifiez les paramètres de l'environnement de production à l'aide de Runtime Admin ou de l'API Managed Runtime. (Suivez les instructions décrites précédemment).
2. Ajoutez le nouveau proxy aux paramètres de l'environnement et enregistrez vos modifications.
3. Mettez à jour votre code PWA Kit pour utiliser le nouveau proxy.
4. Envoyez un nouveau paquet de votre code PWA Kit en push vers Managed Runtime.
5. Déployez le nouveau paquet.

Pour supprimer un proxy d'un environnement de production :

1. Mettez à jour votre code PWA Kit pour utiliser le nouveau proxy.
2. Envoyez un nouveau paquet de votre code PWA Kit en push vers Managed Runtime.
3. Déployez le nouveau paquet.
4. Modifiez les paramètres de l'environnement de production à l'aide de Runtime Admin ou de l'API Managed Runtime. (Suivez les instructions décrites précédemment).
5. Supprimez le proxy des paramètres d'environnement et enregistrez vos modifications.

Vous pouvez remplacer des configurations de proxy pour le développement local en configurant des variables d’environnement.

Définissez une variable d'environnement appelée SSR_PROXY1 pour remplacer le premier élément du tableau proxyConfigs. Définissez-en une appelée SSR_PROXY2 pour remplacer le deuxième élément, et ainsi de suite.

Voici comment cela fonctionne : si la variable d'environnement SSR_PROXY1 est définie sur https://api-staging.example.com/api, elle remplace le premier élément du tableau proxyConfigs par l'objet de configuration de proxy suivant :

Ces variables d'environnement sont couramment utilisées avec la commande npm start lors du développement local pour utiliser différentes instances de l'hôte de l'API, telles que staging ou production. Voici un exemple qui remplace le premier objet de configuration du proxy afin que le chemin api route les requests vers une instance staging :

Une fois les paramètres de proxy configurés, vous pouvez les consulter à l’aide de la fonction utilitaire getProxyConfigs du SDK React de PWA Kit. Par exemple, vous pouvez utiliser un identifiant client différent en fonction de l'environnement dans lequel votre code est exécuté :

Lorsqu'une request est routée par le serveur proxy, la request et la réponse sont toutes deux modifiées pour fonctionner de manière transparente avec le code de votre application.

Modifications de la request

Les modifications suivantes sont appliquées à la request avant de l'envoyer à l'hôte :

• Suppression du préfixe /mobify/proxy/<PROXY_PATH>/.
• Ajout d'un en-tête HTTP de X-Mobify: true.

Les requests passant par un proxy transmettent également tous les paramètres de la chaîne de requête et les en-têtes, y compris les cookies.

Modifications de la réponse

Les modifications suivantes sont appliquées à la réponse avant de l'envoyer au client :

• Ajout d'un en-tête HTTP de `X-Request-Url: `` avec l'URL demandée.
• Si la réponse est une redirection et que dans l'en-tête Location de la réponse, l'host correspond à l'host du proxy, alors cet host est préfixé par /mobify/proxy/<PROXY_PATH>/.
• Si la réponse contient des en-têtes Set-Cookie dont le domain correspond à l'host du proxy, ils sont modifiés pour correspondre à ce dernier. Par exemple, Set-Cookie: key=val; domain=api.commercecloud.com devient Set-Cookie: key=val; domain=www.northerntrailoutfitters.com.
• Si la réponse contient un en-tête Access-Control-Allow-Origin dont la valeur correspond à l'host du proxy, il est modifié en Access-Control-Allow-Origin: https://www.northerntrailoutfitters.com.

Pour tester vos modifications, créez une configuration de proxy avec l'hôte httpbin.org. Si vous lancez une request par le biais de ce proxy, il renvoie les en-têtes qu'il reçoit.

Par défaut, les requests passant par un proxy ne sont pas mises en cache par le CDN. Cette valeur par défaut permet d'utiliser les requests de proxy de manière transparente dans votre code, sans avoir à vous soucier de problèmes de mise en cache des réponses.

Si vous souhaitez vraiment qu’une request de proxy soit mise en cache par le CDN, modifiez le préfixe du chemin utilisé dans votre request pour changer proxy en caching.

Détails de la mise en cache

Les requests de proxy en cache diffèrent des demandes de proxy standard :

• L'en-tête HTTP Cookie est supprimé.

Les réponses en cache diffèrent des réponses standard :

• Tous les en-têtes HTTP Set-Cookie sont supprimés.

Les réponses mises en cache comprennent les en-têtes HTTP suivants, de sorte que lorsque les valeurs de ces en-têtes varient, les réponses sont mises en cache séparément :

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

Les réponses qui comprennent d'autres en-têtes HTTP ne sont pas mises en cache séparément lorsque leurs valeurs varient.

• Les hôtes recourant au proxy doivent utiliser la version 1.2 ou supérieure du protocole Transport Level Security (TLS) lorsque protocol est défini comme https.

Maintenant que vous comprenez comment et pourquoi utiliser les proxies dans votre application de commerce, continuez à explorer la documentation de PWA Kit.