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.
Sans proxy | Avec proxy |
---|---|
Vous devez configurer le serveur d'API pour qu'il réponde avec des en-têtes CORS (cross-origin resource sharing). | Aucune configuration supplémentaire n'est requise pour CORS. |
Les requests d'API nécessitent une request de contrôle préalable, ce qui ralentit les performances. | Aucune request de réseau supplémentaire n'a été lancée. |
Si le serveur d'API ne met pas les réponses en cache, vous perdez une occasion d'améliorer considérablement les performances. | Vous pouvez demander au CDN de Managed Runtime de mettre en cache des requests spécifiques. |
Si vous n'avez pas accès aux journaux du serveur d'API, il est difficile de mesurer son impact sur les performances globales. | Toutes les requests d’API qui sont routées par le CDN de Managed Runtime via des proxies sont consignées. |
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
ouhttps
). Facultatif (la valeur par défaut esthttps
).
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>
.
Si vous avez beaucoup de configurations de proxy différentes, choisissez des chemins de proxy qui permettent de reconnaître facilement les API que vous utilisez.
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 :
getAppOrigin
, du SDK React de PWA Kit, renvoie l’origine correcte pour l’environnement de développement local et celui de Managed Runtime.fetch
, de la bibliothèquecross-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.
Le Managed Runtime ignore les paramètres de proxy dans default.js
et les autres fichiers de configuration dans app/config
, sauf si le nom de fichier correspond au nom d’un environnement Managed Runtime. Pour en savoir plus, reportez-vous à la section Configurations spécifiques à l’environnement.
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.
Pour configurer les proxies pour un environnement Managed Runtime à l'aide de notre outil d'administration Web, procédez comme suit :
- Connectez-vous à l'outil Runtime Admin.
- Cliquez sur votre projet.
- Cliquez sur un environnement.
- Cliquez sur Environment Settings (Paramètres d'environnement) dans le menu de navigation de gauche.
- Dans la section Advanced (Avancés), cliquez sur Edit (Modifier).
- Sous Proxy Configs (Configurations de proxy), cliquez sur Add New Proxy (Ajouter un nouveau proxy).
- Indiquez le chemin d'accès, le protocole et l'hôte.
- Répétez l'opération pour un maximum de 8 configurations de proxy.
- Revenez au début de la section Advanced et cliquez sur Update (Mettre à jour).
- Attendez que le paquet finisse de se redéployer.
- Vérifiez que la configuration du proxy fonctionne comme prévu.
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 :
- 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).
- Ajoutez le nouveau proxy aux paramètres de l'environnement et enregistrez vos modifications.
- Mettez à jour votre code PWA Kit pour utiliser le nouveau proxy.
- Envoyez un nouveau paquet de votre code PWA Kit en push vers Managed Runtime.
- Déployez le nouveau paquet.
Pour supprimer un proxy d'un environnement de production :
- Mettez à jour votre code PWA Kit pour utiliser le nouveau proxy.
- Envoyez un nouveau paquet de votre code PWA Kit en push vers Managed Runtime.
- Déployez le nouveau paquet.
- 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).
- 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.
Les exemples fournis dans cette section supposent que l'application est hébergée à l'adresse www.northerntrailoutfitters.com
et qu'elle est configurée pour acheminer les requests via proxy vers api.commercecloud.com.
.
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.
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 cethost
est préfixé par/mobify/proxy/<PROXY_PATH>/
. - Si la réponse contient des en-têtes
Set-Cookie
dont ledomain
correspond à l'host
du proxy, ils sont modifiés pour correspondre à ce dernier. Par exemple,Set-Cookie: key=val; domain=api.commercecloud.com
devientSet-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é enAccess-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
.
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 commehttps
.
Maintenant que vous comprenez comment et pourquoi utiliser les proxies dans votre application de commerce, continuez à explorer la documentation de PWA Kit.