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
路徑與 Salesforce Commerce API 產生關聯的預設設定。
我們的範例要求也具有兩個 Helper 函式,以確保 API 要求運作一致:
- 來自 PWA Kit React SDK 的
getAppOrigin
會傳回本機開發和 Managed Runtime 環境的正確來源。 - 來自
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,請依照下列步驟進行:
- 登入 Runtime Admin 工具。
- 按一下您的專案。
- 按一下環境。
- 在左側選單按一下 [Environment Settings] (環境設定)。
- 在 [Advanced] (進階) 部分,按一下 [Edit] (編輯)。
- 在 [Proxy Configs] (Proxy 設定) 中,按一下 [Add New Proxy] (新增 Proxy)。
- 輸入路徑、通訊協定和主機。
- 可重複進行多達 8 次 Proxy 設定。
- 返回到 [Advanced] (進階) 部分的開頭,並按一下 [Update] (更新)。
- 等待套件完成重新部署。
- 確認 Proxy 設定是否如預期運作。
您也可以使用 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 環境:
- 使用 Runtime Admin 或 Managed Runtime API 來編輯 Production 環境的環境設定。(請依照先前說明的指示進行。)
- 新增 Proxy 至環境設定並儲存您的編輯。
- 更新您的 PWA Kit 程式碼來使用新的 Proxy。
- 推送新的 PWA Kit 程式碼套件至 Managed Runtime。
- 部署新的套件。
若要從 Production 環境中移除 Proxy:
- 更新您的 PWA Kit 程式碼來使用新的 Proxy。
- 推送新的 PWA Kit 程式碼套件至 Managed Runtime。
- 部署新的套件。
- 使用 Runtime Admin 或 Managed Runtime API 來編輯 Production 環境的環境設定。(請依照先前說明的指示進行。)
- 在環境設定中移除新的 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 標頭的回應在其值不同時, 不會 分別快取。
- 當
protocol
設定為https
時,Proxy 主機的傳輸層安全性 (TLS) 協定必須為 1.2 版本或以上。
這樣您就已經瞭解如何在商務應用程式中使用 Proxy 與為什麼需要 Proxy 了,請繼續探索 PWA Kit 文件。