本章節匯總了原API Gateway中API定義相關問題。
API定義問題
API定義問題
API Gateway是否支援gzip資料壓縮，是否需要添加要求標頭Accept-Encoding ？
支援的，同時符合以下三點時會將應答壓縮：
請求中攜帶Accept-Encoding頭，並且這個欄位的值必須包含gzip。
應答body大小大於2K。
應答body contenttype為text/xml text/plain text/css application/javascript application/x-javascript application/rss+xml application/xml application/json application/octet-stream。
使用者傳了一個未定義的參數，網關將如何處理？
入參映射（過濾未知參數）模式下，網關將過濾掉使用者多傳的參數。
入參映射（透傳未知參數）模式和入參透傳模式下，網關會將參數透傳到後端服務。
後端服務是否可以使用HTTPS？
可以，在錄入後端服務地址時，請以https://開頭，且需要保證您的後端服務已有SSL認證。
API基礎定義是什嗎？
可以配置您API被訪問的方式，包含：http或https，以及使用HTTP方法，目前網關支援所有標準的HTTP方法。
為什麼要填寫API描述？
對於API功能的具體描述，會展示給您的使用者。
API類型是什嗎？
API的類型包含公開、私人兩種。若在雲市場上架商品，公開的介面會上架展示給客戶，私人介面不會展示給客戶。
API名稱是什嗎？
名稱是API的標識，一個有意義的名稱，可以讓您的使用者能夠快速理解API的功能。
API更新是否會有延遲？
不會，API一旦發布會立即生效。
如何使您的API支援HTTPS？
首先，您需要申請一張SSL認證，然後將SSL認證，將認證綁定到網關（查看分組管理—點擊分組名稱進入分組詳情-找到相應網域名稱-上傳認證）。
其次，將您的API請求協議修改為：HTTPS或者HTTP和HTTPS。
後端服務地址如何錄入？
後端服務地址可以是網域名稱，也可以是IP，錄入時，要以http://或者https://開頭
後端服務地址中支援動態參數，用[param]表示。
後端服務地址中可以存在多個動態參數，多個動態參數名稱不可重複。
後端服務地址中的動態參數需要配合Path中的動態參數使用，在配置Path時，配置與Path的映射關係。
為什麼要定義參數？
參數是API請求的重要組成部分，網關可以根據參數定義為您的使用者產生API手冊。
參數定義是必須的嗎？
不是，但推薦您定義，以便您的API使用者能夠清楚地理解您的API。
不定義參數網關如何處理？
會根據配置的入參請求模式進行處理。
參數定義包含什嗎？
描述參數在請求中的位置（path、header、query、body）、參數說明、參數樣本及參數值限制。
可以對參數做哪些限制？
網關不僅支援參數最大值、最小值、長度、枚舉校正，還支援正則、Json Schema校正。
Path是什嗎？
Path是您的API調用時展示給客戶的固定路徑，也是API的標識，在同一分組下HTTP Method+Path不可以重複。
在Restful API中，一般表示為資源，格式為資源/子資源，如：instance/disk。
Path中支援動態參數，用[param]表示，如：instance/disk/[diskid]，可以與後端服務地址中的動態參數進行映射。
如何配置Path與後端服務地址中的動態參數？
在配置Path時，控制台可以自動帶出後端服務地址中的動態參數，您需要將其與Path中動態參數對應上即可。
Path與後端服務地址中的動態參數名稱、順序是否必須保持一致？
不需要。在配置Path時，可以建立映射關係。
APP是什麼，怎麼從使用者實際的應用關聯到我們定義的APP，實際應用是移動端還是Web端？
APP是您在阿里雲的一個虛擬應用，是調用API時的身份標識，它可以是您的一個Web應用，也可以是移動端應用，或者其他。API網關會自動給每個APP分配一對APP Key和Secret，用以簽章要求，調用API。
如何指定調用環境？
調用API時，預設是調用線上環境的API。
如果要調用測試環境，請在header中增加參數：X-Ca-Stage:TEST。
如果要調用預發環境，請在header中增加參數：X-Ca-Stage:PRE。
如何擷取API Gateway報錯資訊？
所有的 API 請求只要到達了網關，網關就會返回請求結果資訊。
使用者需要查看應答的Header部分。其中X-Ca開頭的均為網關返回，比較重要訊息是：
X-Ca-Request-Id：請求唯一ID，請求一旦進入API Gateway應用後，API Gateway就會產生請求ID並通過回應標頭返回給用戶端，建議用戶端與後端服務都記錄此請求ID，以便用於問題排查與跟蹤。X-Ca-Error-Message：API Gateway返回的錯誤訊息，當請求出現錯誤時API Gateway會通過回應標頭將錯誤訊息返回給用戶端。X-Ca-Error-Code：API Gateway系統錯誤碼，當請求出現錯誤被網關攔截後，由API Gateway提供的錯誤碼。
在應答的Header中獲得X-Ca-Error-Code與X-Ca-Error-Message可以基本明確報錯原因，而X-Ca-Request-Id可以用於在Log Service中查詢請求日誌、通過控制台查詢結果、或提供給技術服務人員進行日誌排查。
X-Ca-Error-Code可以尋找錯誤碼表來擷取更詳細的排錯解釋。
如何關閉公網訪問？
API Gateway支援關閉分組的公網訪問，僅通過內網訪問。操作步驟如下：
登入API Gateway控制台，在左側欄單擊開放API——分組管理。
在分組列表中找到想要關閉公網訪問的分組，單擊分組名稱進入分組詳情頁。
在分組詳情頁的公網次層網域後面找到關閉公網訪問按鈕，單擊確定後即可關閉公網訪問。
關閉公網訪問後，所有來自公網的訪問，包括自訂公網網域名稱的訪問都將被拒絕，僅支援通過內網網域名稱調用。
API Gateway調試功能不支援內網網域名稱的調試。
HTTP/HTTPS請求的傳回值為空白
HTTP/HTTPS 請求的返回結果有 HttpCode、Header、Body 三部分。當請求報錯時，由於沒有進入商務邏輯，所以返回的 Body 可能為空白，表現為“傳回值為空白”，但實際上，重要訊息都在 Header 裡面。
使用者發起的 API 請求只要能夠到達網關，就會返回成功/錯誤的結果資訊。
重要的返回資訊都在Header裡面，以X-Ca開頭的為網關返回的資訊。其中較主要的為下面的幾個資訊：
X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
//請求唯一ID，請求一旦進入API Gateway應用後，API Gateway就會產生請求ID並通過回應標頭返回給用戶端，建議用戶端與後端服務都記錄此請求ID，可用於問題排查與跟蹤
X-Ca-Error-Message: Invalid Url
//API Gateway返回的錯誤訊息，當請求出現錯誤時API Gateway會通過回應標頭將錯誤訊息返回給用戶端
X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}
//當開啟Debug模式後會返回Debug資訊，此資訊後期可能會有變更，僅用做聯調階段參考所以如果發送請求後，發現傳回值為空白，那麼看一下返回的 Header 資訊。如果請求到達網關就錯誤返回了，那麼 Body 為空白很正常，會表現為傳回值為空白，但是在 Header 裡面會有重要訊息。
如果Header也為空白，那麼說明請求沒有達到網關，請自行檢查網路狀況等。
各種語言擷取和查看 HTTP/HTTPS 頭部資訊的方法均可在網上查詢到。
HTTPS 認證報錯
調用 HTTPS 介面出現認證認證錯誤或者提示認證已經到期。
原因及解決方案
認證不合法
API 提供者使用的認證是其他非主流機構頒發的認證，此類認證使用瀏覽器訪問是沒有問題的，因為瀏覽器會自動更新根憑證。但老版本作業系統的根憑證對這些機構（憑證授權單位）的不信任或者信任時間已經到期。
解決方案：
升級用戶端根憑證。如：Java+Linux 升級 OpenSSL 用戶端即可，其他動作系統+程式設計語言，請升級程式設計語言中 HTTPS 使用的根憑證。
聯絡 API 提供者，要求其更換相容性更好的主流 SSL 憑證。
程式中忽略檢查 SSL 憑證有效性（不推薦），忽略後會有請求被劫持的安全風險。只在與 API 供應商無法提供相容性更好的主流 SSL 憑證，且安全風險可控的前提下，可以考慮使用此方法。
API提供者的 SSL 憑證到期
提供者的 SSL 憑證到期。
解決方案：
聯絡 API 提供者，要求其更換 SSL 憑證。
程式中忽略檢查 SSL 憑證有效性（不推薦），忽略後會有請求被劫持的安全風險。只在與 API 供應商無法提供相容性更好的主流 SSL 憑證，且安全風險可控的前提下，可以考慮使用此方法。
後端服務調不通
如果您在使用API Gateway的過程中，遇到後端服務調不通的情況，您可參考如下方法進行排查：
需要檢查您錄入的後端服務地址是否正確。
需要保證您的後端服務可以被網關訪問到。
檢查您API定義的“後端逾時”時間。
在API定義時會要求您錄入一個逾時時間，當您的後端服務沒有在您指定的時間內返回時，API Gateway仍然會提示您無法串連後端服務。您可以根據後端服務的實際耗時對後端逾時進行調整，專享執行個體最大支援5min。
說明注意：單位是ms（毫秒）。
後端逾時時間注意不能設定為0，更多關於逾時時間的描述可參考TCP連線逾時時間配置。
如後端服務在 ECS ，請檢查安全性群組設定，是否可以被外部存取。請保證安全性群組可以被API Gateway的出口IP段訪問。
需要強調，API Gateway訪問外部的出口IP不能保證不會變動，通過設定安全性群組來判斷請求來源的方法可能會由於API Gateway出口IP變化而導致API Gateway訪問後端服務失敗，因此我們不建議使用安全性群組方法。API Gateway提供了完整的後端簽名驗證的方式來做身份認證，使用後端簽名機制可以完全避免這種不確定性，我們強烈建議使用此方法來確認請求來源。使用具體文檔：後端簽名外掛程式。
API Gateway執行個體出口IP查看方法：
API Gateway的出口IP請查看分組所在執行個體的出口IP，具體查看方法：
1、 先登入API Gateway控制台-【API管理】-【分組管理】-【分組詳情】查看分組所在執行個體資訊。
2、到【執行個體與叢集】頁面查看對應執行個體的出口地址。