Proxy-Anfragen

Mit der Proxyfunktionalität von Managed Runtime können Sie Anfragen an APIs, die in verschiedenen Domains gehostet werden, über dieselbe Domain wie Ihre Storefront weiterleiten.

Warum Sie dieselbe Domain wie Ihre Storefront verwenden sollten Stellen Sie sich vor, Ihre Storefront wird unter www.northerntrailoutfitters.com gehostet und Sie möchten die B2C Commerce API von api.commercecloud.salesforce.com anfordern. 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.

Während der lokalen Entwicklung können Proxys konfiguriert werden, indem das Array mobify.ssrParameters.proxyConfigs in <PROJECT_DIR>/config/default.js bearbeitet wird. So konfigurieren Sie beispielsweise einen Proxy für die B2C Commerce API:

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

• host: Der Ursprungshost, der Ihre Anfragen empfängt.
• path: Der Name, der im Anfragenpfad zur Identifizierung dieses Proxys verwendet wird.

Um eine Proxy-Anfrage in Ihrem Anwendungscode zu stellen, befolgen Sie beim Erstellen von Anfragepfaden dieses Muster: /mobify/proxy/<PROXY_PATH>.

Sehen wir uns die folgende Beispielanfrage an, die api als path-Wert verwendet. Standardmäßig enthalten Projekte, die mit PWA Kit erstellt wurden, eine Proxy-Konfiguration, die den api-Pfad der B2C Commerce API zuordnet.

Wenn Sie die Proxy-Konfiguration während der lokalen Entwicklung ändern, müssen Sie den lokalen Entwicklungsserver neu starten, damit die Änderungen wirksam werden.

Managed Runtime ignoriert die Proxy-Einstellungen in Konfigurationsdateien. Stattdessen müssen Proxys mit Runtime Admin oder der Managed Runtime API konfiguriert werden.

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

1. Melden Sie sich bei Runtime Admin 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.

Sie können Proxys für Managed Runtime-Umgebungen auch programmgesteuert mithilfe des Endpunkts projects_target_partial_update konfigurieren. Die Managed Runtime API verwendet anstatt "Umgebung" häufig den Begriff "Ziel", aber beide Begriffe haben in diesem Kontext dieselbe Bedeutung.

Hier ist eine Beispielanfrage, die eine Umgebung mit einer Proxy-Konfiguration für api- und ocapi-Pfade aktualisiert:

Bei der Erstellung oder Aktualisierung von Umgebungen akzeptiert der JSON-Anfragetext ein Array von Proxy-Konfigurationsobjekten über ein Feld namens ssr_proxy_configs. Proxy-Konfigurationsobjekte enthalten host und path, wie in Konfigurationsdateien.

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.

In der lokalen Entwicklung können Sie die Proxy-Konfigurationen mithilfe von Umgebungsvariablen ü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 als Proxy verwendet wird, werden sowohl die Anfrage an den Ursprung als auch die Antwort vom Ursprung geändert, damit sie transparent mit Ihrem Anwendungscode funktionieren.

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.

Proxy-Anfragen leiten alle Parameter und Header der Abfragezeichenfolge, einschließlich Cookies, weiter.

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

• Fügen Sie einen HTTP-Header von X-Request-Url: <URL> mit der URL hinzu, die angefordert wurde.
• 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.
• Der Ursprung muss ein gültiges Zertifikat bereitstellen und TLS 1.2 oder höher unterstützen, andernfalls wird HTTP 502 zurückgegeben. Sie können mit demTool von SSL Labs überprüfen, ob Ihre Ursprünge TLS unterstützen.
• 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. Wenn der Proxy-Host nur aus einem privaten Netzwerk erreichbar ist oder wie demandware.net-Hosts blockiert wird, wird ein HTTP-Fehler zurückgegeben.
• Der Caching-Proxy unterstützt nur die Methoden HEAD, GET und OPTIONS. POST-Anfragen werden nicht unterstützt.

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.