設計及開發 API Proxy 的最佳做法

您目前查看的是 Apigee Edge 說明文件。
參閱 Apigee X 說明文件。 資訊

本文件旨在提供一組標準和最佳做法，協助您透過 Apigee Edge 進行開發工作。本文涵蓋的主題包括設計、程式設計、政策用途、監控和偵錯。這些資訊來自開發人員與 Apigee 合作，成功實作成功 API 計畫的開發人員。這份文件即時更新，系統會不時更新這份文件。

除了本文指南外，Apigee Edge Antipatterns 社群文章可能也很實用。

開發標準

註解與說明文件

  • 在 ProxyEndpoint 和 TargetEndpoint 設定中提供內嵌註解。註解可提高資料流的可讀性，特別是當政策檔案名稱不足以表示「資料流」的基礎功能的時候。
  • 提供實用的評論。避免使用明顯的註解。
  • 使用一致的縮排、間距、垂直對齊等方式。

架構式程式設計

架構式程式設計是指將 API Proxy 資源儲存在自己的版本管控系統中，以便在各個本機開發環境中重複使用。舉例來說，如要重複使用某項政策，請將政策儲存在原始碼控管系統中，讓開發人員能夠同步至政策，並在自己的 Proxy 開發環境中使用。

  • 如要啟用 DRY (「不要重複」)，政策設定和指令碼應實作可重複使用的特殊函式。舉例來說，用來從要求訊息擷取查詢參數的專屬政策，可以稱為 ExtractVariables.ExtractRequestParameters。插入 CORS 標頭的專屬政策可稱為 AssignMessage.SetCORSHeaders。接著，這些政策即可儲存在來源控制系統中，並新增至每個需要擷取參數或設定 CORS 標頭的 API Proxy，無須建立備援 (且因此較不易管理) 設定。
  • 清除 API Proxy 未使用的政策和資源 (JavaScript、Java、XSLT 等)，尤其是有機會拖慢匯入及部署程序的大型資源。

命名慣例

  • 政策 name 屬性和 XML 政策檔案名稱必須相同。
  • 指令碼和服務摘要政策 name 屬性與資源檔案名稱應相同。
  • DisplayName 應向從未使用過該 API Proxy 的使用者，準確說明這項政策的功能。
  • 按照功能命名政策。Apigee 建議您為政策建立一致的命名慣例。舉例來說，可以使用簡短的前置字串，後接一串以連字號分隔的描述性字詞。例如，適用於 AssignMessage 政策的 AM-xxx。 另請參閱 apigeelint 工具。
  • 為資源檔案使用適當的副檔名，.js 適用於 JavaScript、.py 適用於 Python，.jar 則用於 Java JAR 檔案。
  • 變數名稱必須一致。如果選擇樣式 (例如 amlCase 或 Under_score)，則請在整個 API Proxy 中使用該樣式。
  • 盡可能使用變數前置字串，以便根據用途整理變數，例如 Consumer.username 和 Consumer.password。

API Proxy 開發

初步設計考量

  • 如需符合 REST 樣式的 API 設計指南，請下載電子書： Web API Design: The Missing Link。
  • 盡可能運用 Apigee Edge 政策和功能來建立 API Proxy。 避免在 JavaScript、Java 或 Python 資源中編寫所有 Proxy 邏輯。
  • 以有條理的方式建構 Flows。多個 Flows，每個 Flow 都有一個條件，偏好用於指向相同 PreFlow 和 Postflow 的多個條件式連結。
  • 設為「failsafe」，建立預設 API Proxy，且 ProxyEndpoint BasePath 為 /。這可用於將基本 API 要求重新導向至開發人員網站、傳回自訂回應，或執行比傳回預設 messaging.adaptors.http.flow.ApplicationNotFound 更實用的動作。
  • 使用 TargetServer 資源，將 TargetEndpoint 設定與具體網址分離，支援跨環境推送。
    請參閱跨後端伺服器負載平衡的相關說明。
  • 如有多個 RouteRules，請建立一個「default」，也就是不設有條件的 RouteRule。確保已在條件式路徑清單中為最後定義預設的 RouteRule。轉送規則會在 ProxyEndpoint 中由上往下評估。
    請參閱 API Proxy 設定參考資料。
  • API Proxy 套件大小：API Proxy 套件不得超過 15 MB。在 Apigee Edge for Private Cloud 中，您可以藉由修改下列位置的 thrift_framed_transport_size_in_mb 屬性來變更大小限制：cassandra.yaml (在 Cassandra 中) 和 conf/apigee/management-server/repository.properties。
  • API 版本管理：如要瞭解 Apigee 對 API 版本管理的想法與建議，請參閱《Web API Design: The Missing Link》電子書中的「版本管理」一文。

啟用 CORS

發布 API 之前，您必須在 API Proxy 上啟用 CORS，以便支援用戶端的跨來源要求。

CORS (跨來源資源共享) 是一種標準機制，可讓在網頁中執行 JavaScript XMLHttpRequest (XHR) 呼叫，以便與非來源網域的資源互動。CORS 是針對所有瀏覽器強制執行的同源政策通常實作的解決方案。舉例來說，如果您透過在瀏覽器中執行的 JavaScript 程式碼向 Twitter API 發出 XHR 呼叫，呼叫就會失敗。這是因為在瀏覽器中放送該網頁的網域與提供 Twitter API 的網域不同。CORS 提供這個問題的解決方案：如果伺服器想要提供跨來源資源共享，允許「選擇加入」狀態。

如要瞭解如何在發布 API 前啟用 API Proxy 的 CORS，請參閱「在 API Proxy 中新增 CORS 支援」一文。

訊息酬載大小

為了避免 Edge 中的記憶體問題，訊息酬載大小限制在 10 MB 以內。超過這些大小會導致 protocol.http.TooBigBody 錯誤。

這篇 Apigee 社群貼文也會討論這個問題。

以下是處理 Edge 中大型訊息大小的建議策略：

  • 串流要求和回應。請注意，直播時，政策無法再存取訊息內容。請參閱串流要求和回應。
  • 在 Edge for Private Cloud 4.15.07 以下版本中編輯訊息處理器 http.properties 檔案，以便提高 HTTPResponse.body.buffer.limit 參數的限制。將變更部署至實際工作環境之前，請務必先進行測試。
  • 在 Edge for Private Cloud 4.16.01 以上版本中，含有酬載的要求必須包含 Content-Length 標頭，或者若要串流傳輸「Transfer-coding: chunked」標頭。如要將 POST 傳送至含有空白酬載的 API Proxy，則必須傳遞 Content-Length 為 0。
  • 在 Edge for Private Cloud 4.16.01 以上版本中，請在 /opt/apigee/router.properties 或 message-processor.properties 中設定下列屬性來變更限制。詳情請參閱「在路由器或訊息處理器上設定訊息大小限制」一文。

    這兩種屬性的預設值都是「10m」，對應 10 MB：
    • conf_http_HTTPRequest.body.buffer.limit
    • conf_http_HTTPResponse.body.buffer.limit

錯誤處理

  • 運用 FaultRules 處理所有錯誤處理作業。(LiftFault 政策可用於停止訊息 Flow，並將處理作業傳送至 FaultRules Flow)。
  • 在 FaultRules Flow 中，使用 AssignMessage 政策建構錯誤回應，而非 IncreaseFault 政策。根據發生的錯誤類型，有條件地執行 AssignMessage 政策。
  • 一律包含預設的「全部接收」錯誤處理常式，以便系統產生的錯誤可對應至客戶定義的錯誤回應格式。
  • 盡可能確保錯誤回應符合貴公司或專案可用的任何標準格式。
  • 使用有意義的淺顯易懂的錯誤訊息，提供錯誤條件的解決方案建議。

請參閱處理錯誤。

如要瞭解業界最佳做法，請參閱「符合 REST 樣式的錯誤回應設計」。

保留

鍵/值對應

  • 鍵/值對應僅適用於有限的資料集。並非專為長期資料儲存設計。
  • 使用鍵/值對應時，請考量效能，因為這項資訊儲存在 Cassandra 資料庫中。

請參閱鍵/值對應作業政策。

回應快取

  • 如果回應失敗或要求不是 GET，請不要填入回應快取。不應快取建立、更新和刪除的項目。<SkipCachePopulation>response.status.code != 200 or request.verb != "GET"</SkipCachePopulation>
  • 以單一一致的內容類型 (例如 XML 或 JSON) 填入快取。擷取 responseCache 項目後，請使用 JSONtoXML 或 XMLToJSON 轉換為需要的內容類型。這可避免儲存重複資料、三倍或更多的資料。
  • 確認快取金鑰足以滿足快取需求。在許多情況下，request.querystring 可用來當做專屬 ID。
  • 除非明確需要，否則請勿在快取金鑰中加入 API 金鑰 (client_id)。在大多數情況下，僅由金鑰保護的 API 會將特定要求的相同資料傳回給所有用戶端。視 API 金鑰而定，為多個項目儲存相同值的效率較低。
  • 設定適當的快取效期間隔，避免寫入無效讀取。
  • 請盡可能提高回應快取政策，以便盡快在 ProxyEndpoint 回應 PostFlow 執行快取填入作業。換句話說，請先完成翻譯和中介服務步驟，包括以 JavaScript 為基礎的中介服務，以及 JSON 和 XML 之間的轉換作業。只要使用中介服務的資料，就能避免每次擷取快取資料時執行中介服務步驟的效能成本。

    請注意，如果中介服務產生了與請求不同的回應，建議您改為快取未中介服務的資料。

  • 用於查詢快取項目的回應快取政策應在 ProxyEndpoint 要求 PreFlow 中。傳回快取項目前，請避免實作過多邏輯，而不是快取金鑰產生作業。以免快取的好處降到最低。
  • 一般來說，回應快取查詢應盡可能靠近用戶端要求。反之，您應盡可能將回應快取填入最接近用戶端回應的位置。
  • 在 Proxy 中使用多個不同的回應快取政策時，請遵守下列規範，確保各項政策的個別行為產生不同的行為：
    • 以互斥條件執行各項政策。這有助於確保只會執行多個回應快取政策的其中一項。
    • 為每個回應快取政策定義不同的快取資源。請在政策的 <CacheResource> 元素中指定快取資源。

請參閱回應快取政策。

政策和自訂程式碼

政策或自訂程式碼？

  • 請盡可能優先使用內建政策。Apigee 政策經過強化、最佳化及支援。例如，請使用標準 AssignMessage 和 ExtractVariables 政策，而非 JavaScript (如果可行) 建立酬載、從酬載 (XPath、JSONPath) 擷取資訊等等。
  • JavaScript 比 Python 和 Java 來得好。不過，如果主要需求是效能，就應該使用 Java 而非 JavaScript。

JavaScript

  • 如果 JavaScript 比 Apigee 政策更直觀 (例如，為許多不同的 URI 組合設定 target.url)，請使用 JavaScript。
  • 剖析複雜的酬載，例如疊代 JSON 物件和 Base64 編碼/解碼。
  • JavaScript 政策有時間限制，因此系統會封鎖無限迴圈。
  • 請一律使用 JavaScript 步驟，並將檔案放入 jsc 資源資料夾。JavaScript 政策類型會在部署時預先編譯程式碼。

請參閱「使用 JavaScript 的程式設計 API Proxy」一節。

Java

  • 如果效能是最高優先順序，或是無法在 JavaScript 中實作邏輯，請使用 Java。
  • 在原始碼追蹤中加入 Java 來源檔案。

如要瞭解如何在 API Proxy 中使用 Java，請參閱透過 Java 呼叫將回應轉換為大寫和 Java 呼叫政策。

Python

  • 除非絕對必要，否則請勿使用 Python。Python 指令碼可能會在執行階段解譯程式碼，因此可能會導致簡易執行作業發生效能瓶頸。

指令碼呼叫 (Java、JavaScript、Python)

  • 使用全域 try/catch 或同等參數。
  • 擲回有意義的例外狀況，並正確擷取這些例外狀況以用於故障回應。
  • 盡早擲回例外狀況並擷取例外狀況。請勿使用全域 try/catch 來處理所有例外狀況。
  • 視需要執行空值和未定義的檢查。舉例來說，擷取選用流程變數時應執行這項作業。
  • 避免在指令碼呼叫中發出 HTTP/S 要求。請改用 Apigee Service 呼叫政策，因為政策可以順利處理連線。

JavaScript

  • API 平台上的 JavaScript 透過 E4X 支援 XML。

請參閱 JavaScript 物件模型。

Java

  • 存取訊息酬載時，請嘗試使用 context.getMessage() 與 context.getResponseMessage 或 context.getRequestMessage。這樣可以確保程式碼可以在要求和回應流程中擷取酬載。
  • 將程式庫匯入 Apigee Edge 機構或環境，並不會在 JAR 檔案中納入這些程式庫。這麼做可減少組合大小，並允許其他 JAR 檔案存取同一個程式庫存放區。
  • 使用 Apigee 資源 API 匯入 JAR 檔案，而不要將其納入 API Proxy 資源資料夾。這麼做可縮短部署時間，並讓多個 API Proxy 參照相同的 JAR 檔案。另一個好處是類別載入器隔離。
  • 請勿使用 Java 處理資源，例如建立及管理執行緒集區。

請參閱使用 Java 呼叫將回應轉換為大寫。

Python

  • 擲回有意義的例外狀況，並適當擷取這些例外狀況以用於 Apigee 錯誤回應

請參閱 Python 指令碼政策。

服務摘要

  • 使用 Proxy 鏈結的有效用途很多，您需要在一個 API Proxy 中使用服務呼叫來呼叫另一個 API Proxy。如果您使用 Proxy 鏈結，請務必避免將「無限迴圈」遞迴呼叫返回同一個 API Proxy。

    如果您在相同機構和環境中的 Proxy 之間連線，請務必參閱串連 API Proxy 一文，進一步瞭解如何實作本機連線，以避免不必要的網路負擔。

  • 使用 AssignMessage 政策建構 Service 呼叫要求訊息，並在訊息變數中填入要求物件。(包括設定要求酬載、路徑和方法)。
  • 政策內設定的網址需要通訊協定規格，也就是說，網址的通訊協定部分 (例如 https://) 不能由變數指定。此外，您必須針對網址的網域部分和其餘網址使用不同的變數。例如：https://{domain}/{path}
  • 將 Service 呼叫 的回應物件儲存在另一個訊息變數中。接著，您可以剖析訊息變數，並保留原始訊息酬載，供其他政策使用。

請參閱服務呼叫政策。

存取實體

AccessEntity 政策

  • 為提高效能，請以 uuid (而非應用程式名稱) 查詢應用程式。

請參閱存取實體政策。

記錄功能

  • 對所有套件和同一個套件使用一般的系統記錄檔政策。這樣做可保持記錄格式一致。

請參閱 MessageLogging 政策。

Monitoring

雲端客戶不需要檢查 Apigee Edge 的個別元件，例如路由器、訊息處理器等。Apigee 的全球營運團隊會根據客戶提出的健康狀態檢查要求，徹底監控所有元件以及 API 健康狀態檢查。

Apigee 數據分析

Analytics (分析) 可以在測量錯誤百分比時，提供非關鍵的 API 監控功能。

請參閱 Analytics (分析) 資訊主頁。

追蹤記錄

在開發或實際執行 API 作業期間，API Edge 管理 UI 中的追蹤工具對於執行階段 API 問題進行偵錯時非常實用。

請參閱使用追蹤工具。

安全性