Proxy 要求

使用由 Managed Runtime 的 CDN 所提供的 Proxy 伺服器，就可以透過和網店相同的網域，將要求路由至代管在不同網域的 API。
相關圖表

為什麼要使用與網店相同的網域？想像一下您的網店位於 www.northerntrailoutfitters.com 上，您想向 api.commercecloud.salesforce.com 發出要求來擷取商務資料。在沒有 Proxy 的情況下發出要求，需要額外的設定步驟，且不如透過 Proxy 快速而可觀察。讓我們來比較這兩種方法。

沒有 Proxy有 Proxy
您必須將 API 伺服器設定為可以使用跨來源資源共用 (CORS) 標頭進行回應。無需進行額外 CORS 設定。
API 要求需要額外的預檢要求，會減緩效能。無需進行額外的網路要求。
若 API 伺服器沒有快取到回應，您就失去大幅提升效能的機會。您可以指示 Managed Runtime 的 CDN 快取特定要求。
若您沒有存取 API 伺服器記錄檔的權限，就很難評估這會如何影響整體成效。所有透過 Proxy 經過 Managed Runtime 的 CDN 路由的 API 要求均會受到記錄。

這樣您就已經瞭解使用 Proxy 的價值所在了，讓我們來探索不同的 Proxy 設定方式吧。

就本機開發來說，主要的 Proxy 設定方式為編輯 <PROJECT_DIR>/config/default.js 內的 mobify.ssrParameters.proxyConfigs 陣列：

proxyConfigs 陣列包含可定義 Proxy 設定的物件，其屬性如下：

  • host：接收您要求的主機，包括網域和子網域。
  • path：在要求路徑中用於觸發 Proxy 處理的字串。
  • protocol：網路通訊協定 (http 或 https)。可選填 (預設值為 https)。

若要在應用程式程式碼中做出 Proxy 要求，請依照此模式來架構您的要求路徑：/mobify/proxy/<PROXY_PATH>。

若您有許多不同的 Proxy 設定，請選擇最容易辨識您使用的 API 的 Proxy 路徑。

讓我們看看使用 api 作為 <PROXY_PATH> 值的範例要求。根據預設，使用 PWA Kit 建立的所有專案都附帶將 api 路徑與 B2C Commerce API 產生關聯的預設設定。

我們的範例要求也具有兩個 Helper 函式，以確保 API 要求運作一致：

  1. 來自 PWA Kit React SDK 的 getAppOrigin 會傳回本機開發和 Managed Runtime 環境的正確來源。
  2. 來自 cross-fetch 資產庫的 fetch 會處理在瀏覽器和 Node.js 做出網路要求之間的不同之處。

每當您在本機開發期間變更 Proxy 設定時，您都 必須 重新啟動本機開發伺服器，變更才會生效。

Managed Runtime 會忽略 default.js 中的 Proxy 設定和 app/config 中的其他設定檔，除非檔案名稱符合 Managed Runtime 環境的名稱。如需更多資訊，請參閱環境特定的設定。

為 Managed Runtime 環境設定 Proxy 有兩個選擇：使用 Runtime Admin 工具或使用 Managed Runtime API。

若要使用我們網頁式的管理工具來為 Managed Runtime 環境設定 Proxy，請依照下列步驟進行：

  1. 登入 Runtime Admin 工具。
  2. 按一下您的專案。
  3. 按一下環境。
  4. 在左側選單按一下 [Environment Settings] (環境設定)。
  5. 在 [Advanced] (進階) 部分，按一下 [Edit] (編輯)。
  6. 在 [Proxy Configs] (Proxy 設定) 中，按一下 [Add New Proxy] (新增 Proxy)。
  7. 輸入路徑、通訊協定和主機。
  8. 可重複進行多達 8 次 Proxy 設定。
  9. 返回到 [Advanced] (進階) 部分的開頭，並按一下 [Update] (更新)。
  10. 等待套件完成重新部署。
  11. 確認 Proxy 設定是否如預期運作。

Runtime Admin 螢幕截圖

您也可以使用 Managed Runtime API 的 /target 端點，以程式設計方式為 Managed Runtime 環境設定 Proxy。(Managed Runtime API 經常使用「目標」而不是「環境」，但兩個詞指的是同一概念。)

在建立或更新環境時，JSON 要求本文會接受來自名為 ssr_proxy_configs 的欄位的 Proxy 設定物件陣列。這些 Proxy 設定物件會以 host、path、protocol (選擇性) 屬性來定義，就像在設定檔中一樣。

以下是更新環境以包含 api 路徑 Proxy 設定的範例要求：

為避免停機，必須以特定順序在 Production 環境中完成新增或移除 Proxy 的步驟。

若要新增 Proxy 至 Production 環境：

  1. 使用 Runtime Admin 或 Managed Runtime API 來編輯 Production 環境的環境設定。(請依照先前說明的指示進行。)
  2. 新增 Proxy 至環境設定並儲存您的編輯。
  3. 更新您的 PWA Kit 程式碼來使用新的 Proxy。
  4. 推送新的 PWA Kit 程式碼套件至 Managed Runtime。
  5. 部署新的套件。

若要從 Production 環境中移除 Proxy：

  1. 更新您的 PWA Kit 程式碼來使用新的 Proxy。
  2. 推送新的 PWA Kit 程式碼套件至 Managed Runtime。
  3. 部署新的套件。
  4. 使用 Runtime Admin 或 Managed Runtime API 來編輯 Production 環境的環境設定。(請依照先前說明的指示進行。)
  5. 在環境設定中移除新的 Proxy 並儲存您的編輯。

您可以設定環境變數，來為本機開發覆寫 Proxy 設定。

設定稱為 SSR_PROXY1 的環境變數來覆寫 proxyConfigs 陣列的第一個元件，設定稱為 SSR_PROXY2 的變數來覆寫第二個元件，以此類推。

以下是其運作方式：若環境變數 SSR_PROXY1 設定為 https://api-staging.example.com/api，它會將 proxyConfigs 陣列中的第一個元素替換為以下 Proxy 設定物件：

這些環境變數通常在本機開發期間與 npm start 命令一起使用，以便使用 API 主機的不同執行個體，像是 Staging 或 Production。以下是覆寫第一個 Proxy 設定物件的範例，好讓 api 路徑將要求路由至 Staging 執行個體：

完成 Proxy 設定後，您可以使用 PWA Kit React SDK 中的公用程式函式 getProxyConfigs 來搜尋 Proxy 設定。舉例來說，您可以根據程式碼所執行的環境而定，使用不同的用戶端 ID：

當要求透過 Proxy 伺服器進行路由時，要求和回應都會經過修改，以和您的應用程式程式碼確實合作執行。

此章節提供的範例假設應用程式代管於 www.northerntrailoutfitters.com 且設定為將要求 Proxy 至 api.commercecloud.com.

在將要求傳送到主機之前，會對要求進行以下修改：

  • 移除 /mobify/proxy/<PROXY_PATH>/ 前綴。
  • 新增 X-Mobify: true HTTP 標頭。

Proxy 要求也會轉送所有查詢字串參數和標頭，包括 Cookie。

在將回應傳送到用戶端之前，會對回應進行以下修改：

  • 新增 X-Request-Url: <URL> HTTP 標頭和所要求的 URL。
  • 若回應為重新導向，且回應的 Location 標頭之 host 與 Proxy 的 host 相符，那麼 host 的前綴為 /mobify/proxy/<PROXY_PATH>/。
  • 若回應包含 Set-Cookie 標頭，其 domain 與 Proxy 的 host 相符，則會更新它們以相符。舉例來說，Set-Cookie: key=val; domain=api.commercecloud.com 會更新為 Set-Cookie: key=val; domain=www.northerntrailoutfitters.com。
  • 若回應包含 Access-Control-Allow-Origin 標頭，其值與 Proxy 的 host 相符，則會更新為 Access-Control-Allow-Origin: https://www.northerntrailoutfitters.com。

若要測試您的修改，請使用 httpbin.org 作為主機進行 Proxy 設定。當您透過該 Proxy 做出要求時，會回應至其接收的任何標頭。

根據預設，CDN 不會快取 Proxy 的要求。此預設允許在您的程式碼中透明地使用 Proxy 要求，而不必擔心不正確地快取回應。

當您 真的 想要 CDN 快取 Proxy 要求時，請將要求中使用的路徑前綴從 proxy 變更為 caching。

已快取的 Proxy 要求與標準 Proxy 要求的不同之處如下：

  • Cookie HTTP 標頭已移除。

已快取的回應與標準回應的不同之處如下：

  • 任何 Set-Cookie HTTP 標頭均已移除。

已快取的回應會包含以下 HTTP 標頭，一旦這些標頭的值發生變化，將分別快取回應：

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

包含其他 HTTP 標頭的回應在其值不同時， 不會 分別快取。

Proxy 擁有不同於應用程式伺服器的限制。

  • Proxy 要求的執行時間限制為 30 秒。如果來自來源的回應未在此時間內完成，便會傳回 HTTP 504。
  • 當 protocol 設定為 https 時，Proxy 主機的傳輸層安全性 (TLS) 協定必須為 1.2 版本或以上。
  • 對於要求或回應的大小沒有限制。
  • 經由 Proxy 的要求可以使用 Cookie 標頭。經由 Proxy 的回應可以包含 Set-Cookie 標頭。
  • 經由 Proxy 的主機必須可公開定址。

這樣您就已經瞭解如何在商務應用程式中使用 Proxy 與為什麼需要 Proxy 了，請繼續探索 PWA Kit 文件。