Proxy-Anfragen

Wenn Sie einen vom Managed Runtime CDN bereitgestellten Proxy-Server benutzen, können Sie über dieselbe Domain wie die Ihrer Storefront Anfragen an APIs senden, die von anderen Domains gehostet werden.

Warum Sie dieselbe Domain wie Ihre Storefront verwenden sollten Nehmen wir einmal an, dass Ihre Storefront auf www.northerntrailoutfitters.com gehostet wird und Sie Commerce-Daten über eine Anfrage an api.commercecloud.salesforce.com abrufen möchten. Um diese Anfrage ohne Proxy-Vorgang durchzuführen, sind zusätzliche Konfigurationsschritte erforderlich und der Vorgang wäre nicht so schnell und beobachtbar wie mit Proxy. Hier sind die beiden Ansätze im Vergleich:

Nachdem Sie die Vorteile von Proxys kennengelernt haben, sehen wir uns jetzt die verschiedenen Methoden zu deren Konfiguration an.

Bei der lokalen Entwicklung werden die Proxys hauptsächlich durch die Bearbeitung des mobify.ssrParameters.proxyConfigs-Arrays in <PROJECT_DIR>/config/default.js konfiguriert:

Das proxyConfigs-Array enthält Objekte, die eine Proxy-Konfiguration mit den folgenden Eigenschaften definieren:

• host: der Host, der Ihre Anfragen empfängt, einschließlich Domain und Subdomains.
• path: die Zeichenfolge, über die in Ihren Anfragepfaden der Proxy-Vorgang ausgelöst wird.
• protocol: das Netzwerkprotokoll (entweder http oder https). Optional (Standardwert ist https).

Um in Ihrem Anwendungscode eine Proxy-Anfrage zu erstellen, befolgen Sie bei der Konstruktion Ihrer Anfragepfade dieses Muster: /mobify/proxy/<PROXY_PATH>

Sehen wir uns die folgende Beispielanfrage an, die api als <PROXY_PATH>-Wert verwendet. Standardmäßig verfügen alle mit dem PWA Kit erstellten Projekte über eine Standardkonfiguration, die den api-Pfad mit der B2C Commerce API assoziiert.

Unsere Beispielanfrage enthält darüber hinaus zwei Helferfunktionen, die gewährleisten, dass API-Anforderungen konsistent funktionieren:

1. getAppOrigin aus dem PWA Kit React SDK gibt den korrekten Ursprung für sowohl lokale Entwicklungs- als auch Managed Runtime-Umgebungen zurück.
2. fetch aus der cross-fetch-Bibliothek handhabt die Unterschiede zwischen über einen Browser und in Node.js durchgeführten Netzwerkanfragen.

Bei jeder Änderung Ihrer Proxy-Konfiguration während der lokalen Entwicklung müssen Sie Ihren lokalen Entwicklungs-Server neu starten, damit die Änderungen in Kraft treten.

Zur Konfiguration von Proxys für Managed Runtime-Umgebungen können Sie entweder das Runtime Admin-Tool oder die Managed Runtime API verwenden.

Gehen Sie wie folgt vor, um Proxys für eine Managed Runtime-Umgebung mit unserem webbasierten Admin-Tool zu konfiguriere:

1. Melden Sie sich im Runtime Admin-Tool an.
2. Klicken Sie auf Ihr Projekt.
3. Klicken Sie auf eine Umgebung.
4. Klicken Sie im linken Navigationsmenü auf Umgebungseinstellungen.
5. Klicken Sie im Abschnitt Advanced (Erweitert) auf Edit (Bearbeiten).
6. Klicken Sie unter Proxy Configs (Proxy-Konfigurationen) auf Add New Proxy (Neuen Proxy hinzufügen).
7. Geben Sie den Pfad, das Protokoll und den Host ein.
8. Wiederholen Sie diese Schritte für bis zu 8 Proxy-Konfigurationen.
9. Gehen Sie zurück zum Anfang des Abschnitts Advanced (Erweitert) und klicken Sie auf Update (Aktualisieren).
10. Warten Sie, bis die erneute Bereitstellung des Bündels abgeschlossen ist.
11. Verifizieren Sie, dass die Proxy-Konfiguration wie erwartet funktioniert.

Mit dem /target-Endpunkt der Managed Runtime API können Sie Proxys für Managed Runtime-Umgebungen auch programmgesteuert konfigurieren. (Die Managed Runtime API verwendet anstatt "Umgebung" häufig den Begriff "Ziel", aber beide Begriffe haben in diesem Kontext dieselbe Bedeutung.)

Bei der Erstellung oder Aktualisierung von Umgebungen akzeptiert der JSON-Anfragetext ein Array von Proxy-Konfigurationsobjekten über ein Feld namens ssr_proxy_configs. Diese Proxy-Konfigurationsobjekte werden genauso mit host, path und protocol (optional) definiert wie in Konfigurationsdateien.

Hier ist eine Beispielanfrage, die eine Umgebung mit einer Proxy-Konfiguration für den api-Pfad aktualisiert:

Um Ausfallzeiten zu vermeiden, müssen die Schritte für das Hinzufügen oder Entfernen von Proxys in einer Production-Umgebung in einer bestimmten Reihenfolge ausgeführt werden.

So fügen Sie einer Production-Umgebung einen Proxy hinzu:

1. Bearbeiten Sie mit Runtime Admin oder der Managed Runtime API die Umgebungseinstellungen für die Production-Umgebung. (Befolgen Sie die zuvor beschriebenen Anweisungen.)
2. Fügen Sie den Umgebungseinstellungen den neuen Proxy hinzu und speichern Sie die Änderungen.
3. Aktualisieren Sie Ihren PWA Kit-Code, damit dieser neue Proxy verwendet wird.
4. Pushen Sie ein neues Bündel Ihres PWA Kit-Codes in Managed Runtime.
5. Stellen Sie das neue Bündel bereit.

So entfernen Sie einen Proxy aus einer Production-Umgebung:

1. Aktualisieren Sie Ihren PWA Kit-Code, damit dieser neue Proxy verwendet wird.
2. Pushen Sie ein neues Bündel Ihres PWA Kit-Codes in Managed Runtime.
3. Stellen Sie das neue Bündel bereit.
4. Bearbeiten Sie mit Runtime Admin oder der Managed Runtime API die Umgebungseinstellungen für die Production-Umgebung. (Befolgen Sie die zuvor beschriebenen Anweisungen.)
5. Entfernen Sie den neuen Proxy aus den Umgebungseinstellungen und speichern Sie die Änderungen.

Mithilfe von Umgebungsvariablen können Sie die Proxy-Konfigurationen für die lokale Entwicklung überschreiben.

Legen Sie eine Umgebungsvariable namens SSR_PROXY1 fest, um das erste Element im proxyConfigs-Array zu überschreiben. Für das Überschreiben des zweiten Elements verwenden Sie die Variable SSR_PROXY2 und so weiter.

Es funktioniert wie folgt: Wenn die Umgebungsvariable SSR_PROXY1 auf https://api-staging.example.com/api gesetzt wird, ersetzt sie das erste Element im proxyConfigs-Array mit dem folgenden Proxy-Konfigurationsobjekt:

Diese Umgebungsvariablen werden während der lokalen Entwicklung häufig mit dem npm start-Befehl verwendet, um verschiedenen Instanzen des API-Hosts wie die Staging- oder Production-Instanz zu verwenden. Im folgenden Beispiel wird das erste Proxy-Konfigurationsobjekt so überschrieben, dass der api-Pfad Anfragen an eine Staging-Instanz sendet:

Nach der Konfiguration von Proxy-Einstellungen können Sie sie mithilfe der Hilfsprogrammfunktion getProxyConfigs aus dem PWA Kit React SDK einsehen. So können Sie beispielsweise je nach der Umgebung, in der Ihr Code ausgeführt wird, eine andere Client-ID verwenden:

Wenn eine Anfrage über den Proxy-Server geleitet wird, werden sowohl Anfrage als auch Antwort modifiziert, damit sie transparent mit dem Code Ihrer Anwendung zusammenarbeiten.

Die folgenden Modifikationen werden an der Anfrage vorgenommen, bevor diese an den Host gesendet wird:

• Das Präfix /mobify/proxy/<PROXY_PATH>/ wird entfernt.
• Der HTTP-Header X-Mobify: true wird hinzugefügt.

Proxidierte Anfragen leiten darüber hinaus alle Abfrage-String-Parameter und -Header, einschließlich Cookies, weiter.

Die folgenden Modifikationen werden an der Antwort vorgenommen, bevor diese an den Client gesendet wird:

• Der HTTP-Header X-Request-Url: <URL> wird der angeforderten URL hinzugefügt
• Wenn es sich bei der Antwort um eine Umleitung handelt und der host des Location-Headers der Antwort dem host des Proxys entspricht, erhält host das Präfix /mobify/proxy/<PROXY_PATH>/.
• Wenn die Antwort Set-Cookie-Headers enthält, deren domain dem host des Proxys entspricht, werden die Header entsprechend aktualisiert. Beispiel: Set-Cookie: key=val; domain=api.commercecloud.com is updated to Set-Cookie: key=val; domain=www.northerntrailoutfitters.com.
• Wenn die Antwort einen Access-Control-Allow-Origin-Header enthält, dessen Wert dem host des Proxys entspricht, wird dieser auf Access-Control-Allow-Origin: https://www.northerntrailoutfitters.com aktualisiert.

Um Ihre Modifikationen zu testen, konfigurieren Sie eine Proxy-Konfiguration mit httpbin.org als Host. Wenn Sie eine Anfrage über diesen Proxy senden, sendet er alle Header zurück, die er erhält.

Standardmäßig werden Proxy-Anfragen vom CDN nicht zwischengespeichert. Dieses Standardverfahren ermöglicht, dass Proxy-Anfragen in Ihrem Code transparent verwendet werden können, ohne dass es durch inkorrektes Caching der Antworten zu Problemen kommt.

Wenn Sie möchten, dass eine Proxy-Anfrage vom CDN zwischengespeichert wird, ändern Sie das in Ihrer Anfrage verwendete Pfad-Präfix von proxy zu caching.

Zwischengespeicherte Proxy-Anfragen unterscheiden sich von Standard-Proxy-Anfragen wie folgt:

• Der HTTP-Header Cookie wird entfernt.

Zwischengespeicherte Antworten unterscheiden sich von Standardantworten wie folgt:

• Alle Set-Cookie-HTTP-Header werden entfernt.

Zwischengespeicherte Antworten enthalten die folgenden HTTP-Header, damit die Antworten bei verschiedenen Werten dieser Header separat zwischengespeichert werden:

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

Antworten, die andere HTTP-Header enthalten, werden nicht separat zwischengespeichert, wenn ihre Werte unterschiedlich sind.

Für Proxys gelten andere Einschränkungen als für den App Server.

• Die Ausführungszeit für Proxy-Anfragen ist auf 30 Sekunden beschränkt. Erfolgt innerhalt dieser Zeit keine Antwort vom Ursprung, wird eine HTTP 504-Fehlermeldung zurückgegeben.
• Wenn protocol auf https eingestellt ist, müssen Proxy-Hosts das TLS-Protokoll (Transport Level Security) Version 1.2 oder höher verwenden.
• Bei der Größe von Anfragen oder Antworten gibt es keine Einschränkungen.
• Proxy-Anfragen können den Cookie-Header verwenden. Proxy-Antworten können den Set-Cookie-Header enthalten.
• Der Proxy-Host muss eine öffentliche Adresse haben.

Jetzt wissen Sie, wie und warum Proxys in Ihrer Commerce App eingesetzt werden. Sehen Sie sich die weiteren Informationen in der PWA Kit-Dokumentation an.