為API介面配置策略 - API Gateway

雲原生API Gateway支援對API和介面級進行添加策略和配置外掛程式，提高API和介面的安全性、效能和可維護性。

重要

策略配置修改後即時生效，無需重新發布。
API級策略的外掛程式配置預設應用於介面級。
介面不允許刪除API級策略，支援介面級的策略覆蓋API級策略。

操作步驟

雲原生API Gateway提供了執行個體內和執行個體外兩種添加API策略的方式：
執行個體外API
1. 登入雲原生API Gateway控制台。左側導覽列選擇API，並在頂部功能表列選擇地區。
2. 單擊目標API，您可以在下拉框中選擇需要添加策略的執行個體。
執行個體內API
1. 登入雲原生API Gateway控制台。左側導覽列選擇執行個體，並在頂部功能表列選擇地區。
2. 在執行個體頁面，單擊目標網關執行個體ID。左側導覽列選擇API，單擊目標API。
您可以進行API級或介面級策略&外掛程式配置：
- API級：單擊API策略配置頁簽，針對全部介面進行API級策略&外掛程式配置，然後單擊啟用策略/外掛程式。
- 介面級：在介面列表頁簽單擊目標介面，單擊策略配置頁簽，然後單擊啟用策略/外掛程式。
在啟用策略/外掛程式面板中，選擇策略或外掛程式進行配置。詳情請參見策略配置和外掛程式配置。

策略配置

限流策略

雲原生API Gateway支援在API和介面層級上實施限流策略，有效防止外部請求超過後端服務的承載能力並避免級聯雪崩的發生。在高並發情境下，限流通過阻止部分請求來確保後端服務始終可用。使您能夠精準控制每個API和介面在指定時間周期內的請求數量，不超過預設的閾值。

限流策略包含並發控制、流量控制和熔斷策略。

並發控制策略：並發規則的原理是統計當前網關處理中的請求數之和，當指標達到設定的閾值時立即攔截流量，可配置為後端服務的最大並發處理請求數，實現在高並發下的後端服務可用性保護。

操作步驟

您可在添加策略頁面，單擊並發控制卡片，在添加策略: 並發控制面板配置相關參數。

配置項			說明
是否開啟			開啟後，並發規則生效。
總體並發數閾值			設定總體並發數閾值。
Web fallback 行為	返回指定內容	HTTP狀態代碼	設定HTTP狀態代碼。預設為429。
		返回 content-type	選擇返回 content-type為普通文本或JSON。
		HTTP 返迴文本	輸入返迴文本。
	返回指定內容	跳轉地址	輸入跳轉地址。

流量控制策略：流控規則的原理是監控API和介面的QPS指標，當指標達到設定的閾值時立即攔截流量，避免後端服務被瞬時的流量高峰衝垮，從而保障高可用性。

操作步驟

您可在添加策略頁面，單擊流量控制卡片，在添加策略: 流量控制面板配置相關參數。

配置項			說明
是否開啟			開啟後，流量控制規則生效。
總體QPS閾值			設定總體QPS閾值。
Web fallback 行為	返回指定內容	HTTP狀態代碼	設定HTTP狀態代碼。預設為429。
		返回 content-type	選擇返回 content-type為普通文本或JSON。
		HTTP 返迴文本	輸入返迴文本。
	跳轉到指定頁面	跳轉地址	輸入跳轉地址。

熔斷策略：熔斷規則的原理是監控API和介面的回應時間或異常比例，當達到指定的閾值時立即降低依賴優先順序。在指定的時間內，系統不會調用該不穩定的資源，避免後端服務受到影響，從而保障後端的高可用性。當指定時間過後，再重新恢複對該資源的調用。

操作步驟

您可在添加策略頁面，單擊熔斷卡片，在添加策略: 熔斷面板配置相關參數。

配置項			說明
是否開啟			開啟後，熔斷規則生效。
統計視窗時間長度			統計的時間視窗長度，取值範圍為1秒~120分鐘。
最小請求數目			觸發熔斷的最小請求數目，若當前統計視窗內的請求數小於此值，即使達到熔斷條件規則也不會觸發。
閾實值型別			選擇以慢調用比例（%）或異常比例（%）作為閾值。選擇以慢調用比例（%）作為閾值，需要設定允許的慢調用RT（即最大的回應時間），請求的回應時間大於該值則統計為慢調用。在降級閾值中設定觸發熔斷的慢調用比例。規則開啟後，在單位統計時間長度內請求數目大於設定的最小請求數目，並且慢調用的比例大於閾值，則接下來的熔斷時間長度內請求會自動被熔斷。經過熔斷時間長度後，熔斷器會進入探測恢複狀態，若接下來的一個請求回應時間小於設定的慢調用RT，則結束熔斷；若大於設定的慢調用RT，則會再次被熔斷。選擇以異常比例（%）作為閾值，需要在降級閾值中設定觸發熔斷的異常比例。規則開啟後，在單位統計時間長度內業務異常數目大於設定的最小請求數目，並且異常的比例大於閾值，則接下來的熔斷時間長度內請求會自動被熔斷。
慢調用RT			設定允許的慢調用RT（即最大的回應時間）。
熔斷比例閾值			觸發熔斷的慢調用比例閾值，取值範圍 0-100（代表 0%-100%）。
熔斷時間長度（s）			即熔斷觸發後持續的時間。資源進入熔斷狀態後，在配置的熔斷時間長度內，請求都會快速失敗。
Web fallback 行為	返回指定內容	HTTP狀態代碼	設定HTTP狀態代碼。預設為429。
		返回 content-type	選擇返回 content-type為普通文本或JSON。
		HTTP 返迴文本	輸入返迴文本。
	跳轉到指定頁面	跳轉地址	輸入跳轉地址。

重寫策略

通過配置重寫策略，您可以在將請求轉寄至目標後端服務之前靈活地修改請求路徑和主機域，以滿足特定業務環境和架構的需求。重寫策略能夠精確控制請求的路徑和主機域，從而確保請求被正確API和介面到合適的服務或端點。

操作步驟

您可在添加策略頁面，單擊HTTP重寫進入添加策略: HTTP重寫面板配置相關參數。

路徑（Path）重寫
對於路徑（Path）重寫，雲原生API Gateway支援以下兩種重寫入模式。
- 精確重寫：僅支援介面級重寫。
- 正則重寫：支援介面級和API級重寫。
精確重寫
精確重寫可以修改原始請求的Path首碼。
樣本一
原始請求的Path為/app/test，但轉寄給後端服務的Path為/test，配置方式建議如下：
API和介面匹配條件：匹配方式為精確匹配，Path為/app/。
重寫：重寫方式為精確重寫，Path為/。
說明
API和介面匹配條件的Path必須設定為/app/，因為精確重寫只會修改精確匹配字串。如果API和介面匹配條件的Path設定為/app，那麼經重寫後的Path結果將會是//test，不符合預期。
樣本二
原始請求的Path為/v1/test，但轉寄給後端服務的Path為/v2/test。配置方式建議如下：
API和介面匹配條件：匹配方式為精確匹配，Path為/v1。
重寫：重寫方式為精確重寫，Path為/v2。
重要
精確重寫要求API和介面的匹配方式為精確匹配，精確匹配和正則匹配不支援精確重寫。由於API和介面匹配方式為精確匹配且可以匹配所有帶有指定首碼Path的請求，所以您在配置精確重寫時需要關注是否需要對所有這些請求進行重寫，否則建議使用精確重寫。
正則重寫
正則重寫可以部分修改原始請求的Path。正則重寫包括兩個元素，一個是模式比對串，用於匹配Path上需要修改的部分；另一個是替換串，用於替換匹配成功的Path部分。關於Regex的規範，請參見Regex文法。
樣本一
原始請求的Path為/aaa/one/bbb/one/ccc，但轉寄給後端服務的Path為/aaa/two/bbb/two/ccc，配置方式建議如下：
API和介面匹配條件：匹配方式為精確匹配，Path為/aaa/one/bbb/one/ccc。
重寫：重寫方式為正則重寫，模式串為one，替換串為two。
樣本二
原始請求的Path為/httpbin/(.*)/(.*)，希望去掉首碼/httpbin並且將兩個Regex部分進行位置交換，配置方式建議如下：
API和介面匹配條件：匹配方式為正則匹配，Path為/httpbin/(.*)/(.*)。
重寫：重寫方式為正則重寫，模式串為/httpbin/(.*)/(.*)，替換串為/\2/\1，其中\1表示第一個正則匹配到的字串，\2表示第二個正則匹配到的字串，對應Nginx中的$1，$2用法。
樣本三
對於開啟版本管理並且使用方式為Path的REST API，希望往後端轉寄時去掉請求path中的版本欄位。例如：原始請求Path為/basePath/version/order/get，但轉寄給後端服務的Path為/basePath/order/get，配置方式建議如下：
選擇使用 API策略配置
重寫：重寫方式為正則重寫，模式串為(/.*)/version(/.*)，替換串為\1\2，其中\1表示第一個正則匹配到的字串，\2表示第二個正則匹配到的字串，對應Nginx中的$1，$2用法。
說明
正則重寫屬於高階用法，文法較為複雜且一般用於特殊的情境，建議您選擇精確重寫。
主機域（Host）重寫
對於主機域（Host）重寫，雲原生API Gateway支援精確重寫。
例如，原始請求的Host為test.com，但轉寄給後端服務的Host為dev.com，在重寫策略中將重寫主機設定為dev.com。

Header修改策略

在將請求轉寄至目標後端服務之前，或在後端服務的響應返回給用戶端之前，Header設定功能允許您修改原始請求中的頭資訊。

操作步驟

您可在添加策略頁面，單擊Header修改卡片，在添加策略: Header修改面板配置相關參數。

配置項	說明
開啟	是否開啟Header修改策略。開啟：開啟Header修改策略後，網關會控制請求和響應的Header。關閉：關閉Header修改策略後，網關不會控制請求和響應的Header。
Header類型	選擇Header類型。請求：表示將會對請求的Header進行設定。響應：表示將會對響應的Header進行設定。
操作類型	選擇操作類型。新增：向請求或響應新增一個Header。說明如果新增的Header已存在，那麼Header Value將會拼接在已有的Header值後面，並通過英文逗號（,）分隔。修改：修改請求或響應指定的Header。說明如果指定的Header不存在，將會按照Header Key和Header Value進行新增操作。如果指定的Header存在，將會進行覆蓋修改操作。刪除：刪除請求或響應指定的Header。
Header Key	輸入請求或響應的頭部名。
Header Value	輸入請求或響應的頭部值。

跨域資源共用策略

跨域資源共用（CORS，Cross-Origin Resource Sharing）是一項重要的安全性原則，允許Web應用伺服器進行跨域存取控制，從而實現安全的資料轉送。雲原生API Gateway支援在API和介面層級配置跨域策略，您可以根據實際需求，限定允許訪問資源的網域名稱和要求方法。

重要

跨域對於Mock服務不生效，請配置一個真實的後端測試服務。

操作步驟

您可在添加策略頁面，單擊跨域卡片，在添加策略: 跨域面板配置相關參數。

配置項	描述
開啟	開啟開啟右側的開關。開啟：開啟跨域策略後，您的伺服器資源允許被設定的第三方來源站點通過瀏覽器進行跨域訪問。關閉：關閉跨域策略後，您的伺服器資源禁止被任意第三方來源站點通過瀏覽器進行跨域訪問。
允許的訪問來源	設定允許通過瀏覽器訪問伺服器資源的網站。參數輸入規則如下：允許所有的訪問來源：``。允許指定根網域名稱的訪問來源：`.example.com`。允許多個具體的訪問來源：以`http://`或`https://`開頭，並且以斷行符號分隔。說明該參數作用於`Access-Control-Allow-Origin`頭部。當用戶端請求的Origin頭部匹配上任意您設定的允許的訪問來源，跨域響應的`Access-Control-Allow-Origin`將會被設定為用戶端請求的Origin頭部。
允許的方法	選擇跨域訪問時允許的HTTP方法。常見的方法有GET、POST、PUT、DELETE、HEAD、OPTIONS和PATCH。說明該參數作用於Access-Control-Allow-Methods頭部。
允許的要求標頭部	除了瀏覽器內建的基礎Header，設定跨域訪問時允許的Header。參數輸入規則如下：允許所有的要求標頭部：`*`。允許多個具體的要求標頭部：輸入具體的要求標頭部，並以斷行符號分隔。說明該參數作用於Access-Control-Allow-Headers頭部。
允許的回應標頭部	允許瀏覽器、JavaScript指令碼訪問的回應標頭部。參數輸入規則如下：允許所有的回應標頭部：`*`。允許多個具體的回應標頭部：輸入具體的回應標頭部，並以斷行符號分隔。說明該參數作用於Access-Control-Expose-Headers頭部。
允許攜帶憑證	跨域訪問時是否允許攜帶憑證資訊。說明該參數作用於Access-Control-Allow-Credentials頭部。
預檢的到期時間	對於非簡單請求，設定OPTIONS預檢請求在瀏覽器的最大緩衝時間。說明該參數作用於Access-Control-Max-Age頭部。

流量複製策略

流量複製策略可以將線上應用流量複製到指定服務。這一功能為系統的模擬測試和問題定位提供了支援，協助您有效評估應用效能和進行故障排查。

操作步驟

您可在添加策略頁面，單擊流量複製卡片，在添加策略: 流量複製面板配置相關參數。

參數	描述
開啟	API或介面流量複製策略的啟用開關。
目標服務	複製的流量要轉寄的目標服務。說明目標服務只支援HTTP/HTTPS協議。
連接埠	目標服務的連接埠，您也可以選擇動態連接埠。說明動態連接埠適用於服務連接埠會動態變化的情境，但不支援有多連接埠的服務，請勿在多連接埠情境選擇動態連接埠。
流量複製比例（%）	複製流量的比例，取值為0-100。說明若設定為50，則當前API和介面會有50%的流量被複製到目標服務。

逾時策略

雲原生API Gateway提供API和介面層級的逾時設定，您可以按需為指定API和介面配置網關等待請求響應結果的最大時間。如果網關在設定的時間內未收到後端服務的響應，將向用戶端返回一個 HTTP 狀態代碼為 504（Gateway Timeout）的響應結果。

操作步驟

您可在添加策略頁面，單擊逾時卡片，在添加策略：逾時面板配置相關參數。

說明

逾時策略配置完成且開啟後，請根據實際業務驗證服務逾時規則是否生效。

參數

描述

开启

是否開啟逾時策略。

開啟：網關API或介面逾時策略生效。
關閉：網關API或介面逾時策略失效。

超时时间

為當前API和介面設定逾時時間，單位為秒。

說明

當設定為0或者關閉逾時策略時，表示網關會一直等待請求的響應結果。

重試策略

雲原生API Gateway提供API和介面層級的重試設定，可以對出錯的請求進行自動重試。您可以根據需求配置重試條件，例如在串連失敗、後端服務不可用，或者接收到指定的HTTP狀態代碼時觸發請求重試。

API和介面的重試條件

當後端服務返回5xx錯誤時，雲原生API Gateway按照設定的重試次數對出錯的請求自動進行重試。

HTTP協議的重試條件如下：
- 5xx：如果後端服務返回任何5xx響應，或者發生串連斷開、重設、讀取逾時事件，雲原生API Gateway將嘗試對出錯請求進行重試。
  說明
  5xx包含connect-failure和refused-stream的條件。
- reset：如果發生串連斷開、重設、讀取逾時事件，雲原生API Gateway將嘗試對出錯請求進行重試。
- connect-failure：如果請求是由串連斷開導致的出錯，雲原生API Gateway將嘗試對出錯請求進行重試。
- refused-stream：如果後端服務以REFUSED_STREAM錯誤碼來重設流，雲原生API Gateway將嘗試對出錯請求進行重試。
- retriable-status-codes：如果後端服務響應結果的HTTP狀態代碼匹配上您指定的重試狀態代碼，雲原生API Gateway將嘗試對該請求進行重試。
  說明
  只有在重試條件中指定了retriable-status-codes，才能使用重試狀態代碼。
gRPC協議的重試條件如下：
- cancelled：如果後端gRPC服務的回應標頭部中的gRPC狀態代碼為cancelled，雲原生API Gateway將嘗試對該請求進行重試。
- deadline-exceeded：如果後端gRPC服務的回應標頭部中的gRPC狀態代碼為deadline-exceeded，雲原生API Gateway將嘗試對該請求進行重試。
- internal：如果後端gRPC服務的回應標頭部中的gRPC狀態代碼為internal，雲原生API Gateway將嘗試對該請求進行重試。
- resource-exhausted：如果後端gRPC服務的回應標頭部中的gRPC狀態代碼為resource-exhausted，雲原生API Gateway將嘗試對該請求進行重試。
- unavailable：如果後端gRPC服務的回應標頭部中的gRPC狀態代碼為unavailable，雲原生API Gateway將嘗試對該請求進行重試。

操作步驟

您可在添加策略頁面，單擊重試卡片，在添加策略: 重試面板配置相關參數。

說明

重試策略配置完成且開啟後，請根據實際業務驗證服務重試規則是否生效。

參數	描述
開啟	是否開啟重試策略。開啟：網關API或介面重試策略生效。關閉：網關API或介面重試策略失效。關閉重試後，網關內部有預設重試配置，重試次數預設為2次，重試條件預設為`connect-failure`、`refused-stream`、`unavailable`、`cancelled`和`retriable-status-codes`。
重試次數	設定對出錯請求的最大重試次數。重試次數支援設定0~10次，建議不超過2次。重試次數設定為0，表示取消重試。
重試條件	選擇合適的，支援多選。
重試狀態代碼	對特定HTTP狀態代碼的響應進行重試，支援配置多種HTTP狀態代碼。重要重試條件指定`retriable-status-codes`，才能配置重試狀態代碼。

外掛程式配置

單擊添加外掛程式頁簽。
在快捷導航處，選擇要安裝的外掛程式類型或者搜尋外掛程式名稱，單擊外掛程式卡片：
- 如果外掛程式未安裝，在安裝外掛程式的彈出框中單擊安裝並配置，在啟用外掛程式的彈框中配置外掛程式規則，並選擇啟用狀態。
- 如果外掛程式已安裝，在啟用外掛程式的彈框中，配置外掛程式規則，並選擇啟用狀態。
單擊確定，返回API的掛載列表，可以看到介面的外掛程式掛載情況和啟用狀態。

操作步驟

執行個體外API

執行個體內API

策略配置

限流策略

重寫策略

路徑（Path）重寫

精確重寫

樣本一

樣本二

正則重寫

樣本一

樣本二

樣本三

主機域（Host）重寫

Header修改策略

跨域資源共用策略

流量複製策略

逾時策略

重試策略

外掛程式配置