全部產品
Search

搜尋本產品

    API Gateway：API調試及自助排錯

    文件中心

    API Gateway：API調試及自助排錯

    更新時間：Jul 13, 2024

    API Gateway支援使用者對配置在API Gateway中的發行API進行線上調試，本文重點介紹如何通過API調試中的自助排錯功能進行調試過程中的問題排查。

    1. 概述

    API控制台支援對發行API進行調試，而在調試過程中遇到問題時，如何理解報錯資訊並快速定位和解決問題。本文將結合API調試頁面提供的自助排錯能力進行介紹。

    說明

    • API調試支援摘要簽名認證、簡單認證（AppCode）、BasicAuth外掛程式認證。

    • API調試支援 multipart/form-data，可在調試頁面上傳檔案。

    • 調試頁請求報文最大支援512KB，若請求報文較大，建議使用SDK調試。

    • 配置的執行個體黑白名單以及IP存取控制外掛程式需允許存取API調試的IP地址，具體IP地址可以在API調試頁面左下角的調試提示中擷取。

    2. 調試資訊擷取錯誤資訊

    所有的API請求只要到達網關，網關就會返回請求結果資訊。使用者可以查看返回結果的頭部，即Header部分，來擷取API Gateway返回的資訊。其中X-Ca開頭的屬性均為API Gateway返回，其中您需要重點關注的資訊為：

    • X-Ca-Error-Code。API Gateway系統錯誤碼，當請求出現錯誤被網關攔截後，由API Gateway提供的錯誤碼。

    • X-Ca-Request-Id。請求唯一ID，請求一旦進入API Gateway應用後，API Gateway就會產生請求ID並通過回應標頭返回給用戶端，建議用戶端與後端服務都記錄此請求ID，可用於問題排查與跟蹤。

    • X-Ca-Error-Message。API Gateway返回的錯誤訊息，當請求出現錯誤時API Gateway會通過回應標頭將錯誤訊息返回給用戶端。

    2.1. 根據X-Ca-Request-Id查詢更多調用資訊

    在應答的Header中獲得X-Ca-Error-Code與X-Ca-Error-Message可以基本明確報錯原因，而X-Ca-Request-Id可以用於在Log Service中查詢請求日誌、通過控制台查詢結果、或提供給技術服務人員進行日誌排查。

    控制台查詢步驟如下：

    1. 登入API Gateway控制台。

    2. 在左側欄單擊API調用——自助排錯，輸入API所在Region以及X-Ca-Request-Id，單擊查詢，就可以看到對應的日誌資訊。

    說明

    可以參考通過Log Service查看API調用日誌，文檔中有日誌各欄位具體的含義，可以協助更好的查看日誌資訊。

    2.1.1. API Gateway報錯

    當本次API Gateway調用響應資訊中API Gateway錯誤碼（X-Ca-Error-Code）不為空白，說明本次調用被API Gateway攔截。錯誤碼由一個6位長度的字元描述。當請求被API Gateway攔截時，API Gateway會返回相應的錯誤資訊，並附有簡單的錯誤原因說明（X-Ca-Error-Message），可以根據該部分內容排查錯誤原因。更多錯誤碼解釋請參考錯誤碼表。

    2.1.2. 後端服務報錯

    當本次調用的HTTP狀態代碼不為200，且API Gateway錯誤碼為空白，則表示本次調用API Gateway成功將請求轉寄到後端服務，後端服務經過處理後返回非200的狀態代碼。這時候需要檢查後端服務商務邏輯。如果是通過雲市場購買的API，則需要諮詢雲市場的服務提供者。

    2.1.3. 請求成功

    當的本次調用返回的HTTP狀態代碼為200，則表示本次請求API Gateway成功轉寄請求到後端服務，並且後端服務返回成功的應答。

    3. 擷取Trace日誌

    在API調試頁面發送請求後。可以在Trace日誌中可以查看API Gateway收到的請求、API Gateway的處理詳情、API Gateway發給後端服務的請求、API Gateway收到的應答、API Gateway給用戶端返回的應答。

    如果使用的是子帳號或者角色扮演帳號，發送請求前需要勾選記錄Trace日誌，則需要確保使用的帳號被主帳號授予了當前API所在執行個體的AcquireGatewayToken介面RAM許可權。樣本如下，更多詳情可以參考使用 RAM 管理 API。

    {
 "Version": "1",
 "Statement": [
 {
 "Effect": "ALLOW",
 "Action": "apigateway:AcquireGatewayToken",
 "Resource": "acs:apigateway:{#regionId}:{#accountId}:instance/{#InstanceId}"
 }
 ]
}
# 其中{#}為變數標識，需要替換為實際值。

    4. 使用自助排錯分析錯誤原因

    自助排錯中的問題診斷展示了本次調用的部分日誌資料，當調用出現失敗的情況時，可以根據該部分的資訊定位和排查問題。這裡介紹部分欄位用於快速定位出錯位置：

    • TotalLatency：API Gateway從接收到用戶端請求，到完成用戶端響應的總時間

    • ServiceLatency：API Gateway向後端服務發送請求，到接收完後端服務響應的時間

    通過上述兩個欄位可以快速分析出報錯位置，當ServiceLatency為0則表示請求在API Gateway被攔截，未到達後端服務；當ServiceLatency不為0則表示請求到達後端服務。另外，整個請求鏈路的IO時間點也記錄在日誌中：

    • FrontRequestStart：API Gateway開始接收到用戶端請求的時間點

    • FrontRequestEnd：API Gateway完成接收用戶端請求的時間點

    • BackendRequestStart：API Gateway開始向後端服務發起請求的時間點

    • BackendRequestEnd：API Gateway完成向後端服務發起請求的時間點

    • BackendResponseStart：API Gateway開始接收到後端服務響應的時間點

    • BackendResponseEnd：API Gateway完成接收後端服務響應的時間點

    • FrontResponseStart：API Gateway開始向用戶端發送響應的時間點

    • FrontResponseEnd：API Gateway完成向用戶端發送響應的時間點

    利用好請求日誌資訊能快速解決調用問題，詳細的日誌欄位含義請參考通過Log Service查看API調用日誌。