使用偵錯功能

本頁面適用於 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本節說明如何建立及管理偵錯工作階段，以及如何使用 Apigee UI 和 API 查看要求和回應資料。

使用「Offline Debug」，查看及分析先前下載的偵錯工作階段。

建立偵錯工作階段

偵錯工具簡單易用。您會先啟動偵錯工作階段，接著向 Apigee 發出 API 呼叫，然後在使用者介面中查看要求和回應資料。

使用 Apigee UI 或 API 建立偵錯工作階段，如以下各節所述。

Apigee UI

如要建立偵錯工作階段，請按照下列步驟操作：

  1. 在 Google Cloud 控制台，依序前往「Apigee」 >「Proxy development」(Proxy 開發) >「API Proxies」(API Proxy) 頁面。

    前往「API Proxies」(API Proxy) 頁面

  2. 選取要偵錯的 API Proxy。系統會顯示 Proxy 編輯器的「Overview」(總覽) 窗格。
  3. 按一下「偵錯」分頁。
  4. 按一下「Start debug session」。系統會顯示「Start debug session」(啟動偵錯工作階段) 窗格。

  5. 在「Start debug session」窗格中：

    1. 選取要執行偵錯工作階段的環境。

    2. (選用) 從「Filter」(篩選器) 下拉式選單中選取篩選器，套用至您正在建立的偵錯工作階段中的所有交易。預設值為 None (All transactions)，會在偵錯資料中納入所有交易。

      如要瞭解如何使用篩選器，請參閱「在偵錯工作階段中使用篩選器」。如要瞭解內建篩選器，請參閱「使用預先定義的篩選器」。

    3. 按一下「啟動」。

Apigee UI 現在會顯示「Debug session in progress」(偵錯工作階段進行中) 窗格。

按一下即可放大圖片 新的偵錯工作階段

偵錯工作階段會記錄要求 10 分鐘，或直到擷取 15 個要求為止。如果您使用 API 建立偵錯工作階段，可以調整 10 分鐘的限制。「Ends within」(結束時間) 欄位會顯示工作階段剩餘的時間。

在偵錯工作階段中，您必須先將要求傳送至所選環境中偵錯的 Proxy，偵錯窗格才會顯示任何資訊。

送出要求後，要求會顯示在「Transactions」(交易) 清單窗格中。「Transactions」(交易) 清單每五秒更新一次。

按一下即可放大圖片 交易清單中的要求

如要查看或複製交易輸出內容，請按照下列步驟操作：

  1. 在「Transactions」(交易) 清單中，按一下 「View transaction output」(查看交易輸出內容)。「Transaction output」(交易輸出內容) 窗格隨即顯示。
  2. 按一下個別交易，或點選「所有交易」。
  3. 按一下「 複製」，將交易輸出內容複製到剪貼簿。
  4. 按一下「關閉」。

API

如要使用 API 建立偵錯工作階段，請向下列資源發出 POST 要求：

https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/apis/$API/revisions/$REV/debugsessions

您也可以採取下列做法：

以下範例說明如何使用 API 建立偵錯工作階段。

curl "https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions" \
      -X POST \
      -H "Authorization: Bearer $TOKEN"

其中 $TOKEN 設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一節所述。如要瞭解本範例中使用的 curl 選項，請參閱「使用 curl」。如需可用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

以下是回應範例：

{
      "name":"56382416-c4ed-4242-6381-591bbf2788cf",
      "validity":300,
      "count":10,
      "tracesize":5120,
      "timeout":"600"
    }

系統會評估後續傳送至 API Proxy 的要求 (直到工作階段持續時間或要求數量達到上限)，並可能將這些要求儲存在偵錯工作階段資料中。

詳情請參閱「建立偵錯工作階段 API」。

使用 API 設定偵錯工作階段長度

如要使用 API 設定偵錯工作階段長度，請在偵錯工作階段建立要求中加入下列酬載：

{
      "timeout":"debug_session_length_in_seconds"
    }

以下範例建立的偵錯工作階段只有 42 秒：

curl https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions"
      -X "POST" \
      -H "Authorization: Bearer $TOKEN" \
      -d ' {
        "timeout":"42"
      } '

您只能在偵錯工作階段建立要求中設定工作階段的 timeout，工作階段建立後即無法變更其時間長度。

timeout 的預設值為 300 (5 分鐘)。最大值為 600 秒 (10 分鐘)。

複製 Proxy 網址

Proxy 網址用於將要求傳送至 API Proxy。

如要尋找及複製 Proxy 網址，請按照下列步驟操作：

  1. 在「Debug session」(偵錯工作階段) 窗格的「URL」(網址) 欄位中，按一下 「Copy」(複製)。
  2. 如果偵錯工作階段未開啟：

    1. 在 Google Cloud 控制台，依序前往 「Apigee」 > 「管理」 > 「環境」 > 「環境群組」頁面。

      前往「Environment Groups」(環境群組)

    2. 網址是您要執行偵錯工作階段的個別環境主機名稱。選取並複製。

如要選取其他 Proxy 網址，請按照下列步驟操作：

  1. 在「Debug session」(偵錯工作階段) 窗格的「URL」欄位中，按一下「Edit」(編輯) 圖示 。
  2. 進行所需變更，然後按一下「更新」。
  3. 如果偵錯工作階段未開啟：
    1. 找出 Proxy 網址。
    2. 依序點選「更多」圖示 和「編輯」圖示 。
    3. 進行所需變更，然後按一下「更新」。

在使用者介面中啟動另一個偵錯工作階段

您可以在使用者介面中建立任意數量的偵錯工作階段。

在進行中的偵錯工作階段，您可以在 Apigee UI 中啟動另一個工作階段。如要執行這項操作，請按一下「Debug session」窗格中的「Close」：

按一下即可放大圖片 關閉並返回「啟動偵錯工作階段」面板

使用者介面會返回「Start a debug session」(啟動偵錯工作階段) 面板，您可以在該面板啟動新的偵錯工作階段。

偵錯工作階段何時結束？

您無法直接「停止」執行中的偵錯工作階段。不過，您可以刪除有效工作階段的資料，如「刪除偵錯工作階段資料」一節所述。

建立偵錯工作階段時，有兩項屬性會決定工作階段何時結束：

  • timeout：工作階段期間收集資料的時間長度。預設長度取決於您啟動工作階段的方式 (透過 UI 或 API)。最大值為 600 秒 (或 10 分鐘)。
  • count：單一工作階段中，每個訊息處理器記錄的要求數量上限。由於大多數叢集中的訊息處理器數量不固定，因此計數的影響可能無法預測。Apigee 不建議自訂這項設定。

達到逾時時間或計數時，該訊息處理器的偵錯工作階段就會結束。

下列術語用於描述偵錯工作階段的狀態：

  • 「有效工作階段」是指尚未逾時或超過次數的偵錯工作階段。有效工作階段仍會記錄未篩除的要求資料。
  • 已完成的工作階段是指已達到逾時或超過計數的偵錯工作階段；已完成的工作階段不會再記錄新要求的資料，且其資料會在工作階段結束後的 24 小時內刪除。

如何解讀偵錯工作階段

本節將概略介紹偵錯工作階段。

另請參閱：

偵錯工具包含兩個主要部分：交易窗格和階段詳細資料：

  • 交易窗格會使用圖示標示 API Proxy 交易期間發生的每個重要步驟，包括政策執行、條件式步驟和轉換。將滑鼠游標懸停在任何圖示上，即可查看摘要資訊。要求流程步驟會顯示在交易對應圖頂端，回應流程步驟則會顯示在底部。
  • 「phase details」(階段詳細資料) 窗格會列出 Proxy 內部處理的相關資訊，包括已設定或讀取的變數、要求和回應標頭等。按一下任一圖示，即可查看該步驟的階段詳細資料。

交易窗格

交易窗格會顯示要求和回應的步驟。

以下是偵錯工具交易窗格範例，其中標示了主要 Proxy 處理區隔：

按一下即可放大圖片 偵錯圖表，顯示「開始 Proxy 要求」、「開始目標要求」、「開始目標回應」、「開始 Proxy 回應」、「開始 Proxy 後用戶端流程」

交易窗格圖例

以下說明交易窗格中的圖示：

本節將說明交易窗格中的圖示：

政策圖示

每種政策都有專屬圖示。這些圖示可讓您查看政策是否依正確順序執行，以及是否成功。按一下政策圖示，即可查看執行結果，以及結果是否符合預期。舉例來說，您可以查看訊息是否已正確轉換，或是否已快取。

標準政策可強化 API，控管流量、提升效能、強制執行安全措施，並提高 API 的實用性，您不必編寫程式碼或修改後端服務。

可擴充政策可讓您在 API Proxy 中加入自訂邏輯。 您可以使用這些政策，新增標準政策未提供的功能。

如要進一步瞭解政策和類別，請參閱「 政策參考總覽」。

如何篩選表格：

  • 選取一項政策類型和/或一個政策類別。
  • 按一下「Name」(名稱) 欄標題，依政策名稱排序表格。
  • 輸入關鍵字，搜尋政策名稱。

政策類型

政策類別

圖示 名稱 類型 類別
LLMTokenQuota 政策圖示 LLMTokenQuota 政策 可擴充 AI
chat_spark PromptTokenLimit 政策 可擴充 AI
shield_spark SanitizeUserPrompt 政策 可擴充 AI
shield_spark SanitizeModelResponse 政策 可擴充 AI
async SemanticCacheLookup 政策 可擴充 AI
async SemanticCachePopulate 政策 可擴充 AI
manage_search ParseDialogflowRequest 政策 可擴充 Dialog flow
chat_add_on SetDialogflowResponse 政策 可擴充 Dialog flow
stacked_line_chart DataCapture 政策 可擴充 擴充功能
display_external_input ExternalCallout 政策 標準 擴充功能
flowsheet FlowCallout 政策 可擴充 擴充功能
自動化 IntegrationCallout 政策 可擴充 擴充功能
JavaCallout 政策圖示 JavaCallout 政策 可擴充 擴充功能
JavaScript 政策圖示 JavaScript 政策 可擴充 擴充功能
add_notes MessageLogging 政策 可擴充 擴充功能
chat_paste_go PublishMessage 政策 標準 擴充功能
PythonScript 政策圖示 PythonScript 政策 可擴充 擴充功能
integration_instructions ServiceCallout 政策 可擴充 擴充功能
自動化 SetIntegrationRequest 政策 可擴充 擴充功能
waterfall_chart TraceCapture 政策 可擴充 擴充功能
cloud_done AccessEntity 政策 可擴充 調節
account_tree AssertCondition 政策 標準 調節
edit_square AssignMessage 政策 可擴充 調節
login ExtractVariables 政策 可擴充 調節
GraphQL 政策圖示 GraphQL 政策 標準 調節
sync_alt HTTPModifier 政策 標準 調節
sync_alt JSONtoXML 政策 標準 調節
account_tree KeyValueMapOperations 政策 可擴充 調節
sync_alt MonetizationLimitsCheck 政策 可擴充 調節
cloud_done OASValidation 政策 標準 調節
report RaiseFault 政策 標準 調節
sync_alt ReadPropertySet 政策 標準 調節
cloud_done SOAPMessageValidation 政策 標準 調節
sync_alt XMLtoJSON 政策 標準 調節
cloud_done XSLTransform 政策 可擴充 調節
lock AccessControl 政策 標準 安全性
安全 BasicAuthentication 政策 可擴充 安全性
connect_without_contact CORS 政策 標準 安全性
lock DecodeJWS 政策 可擴充 安全性
lock DecodeJWT 政策 標準 安全性
密碼金鑰 DeleteOAuthV2Info 政策 可擴充 安全性
lock GenerateSamlAssertion 政策 可擴充 安全性
lock GenerateJWS 政策 可擴充 安全性
lock GenerateJWT 政策 可擴充 安全性
密碼金鑰 GetOAuthV2Info 政策 可擴充 安全性
lock HMAC 政策 標準 安全性
安全 JSONThreatProtection 政策 可擴充 安全性
密碼金鑰 OAuthV2 政策 可擴充 安全性
安全 RegularExpressionProtection 政策 可擴充 安全性
密碼金鑰 RevokeOAuthV2 政策 可擴充 安全性
密碼金鑰 SetOAuthV2Info 政策 可擴充 安全性
lock ValidateSamlAssertion 政策 可擴充 安全性
key VerifyAPIKey 政策 可擴充 安全性
密碼金鑰 驗證 IAM 政策 可擴充 安全性
lock VerifyJWS 政策 可擴充 安全性
lock VerifyJWT 政策 標準 安全性
安全 XMLThreatProtection 政策 可擴充 安全性
cached InvalidateCache 政策 可擴充 流量管理
cached LookupCache 政策 可擴充 流量管理
cached PopulateCache 政策 可擴充 流量管理
配額政策圖示 配額政策 可擴充 流量管理
repartition ResetQuota 政策 可擴充 流量管理
cached ResponseCache 政策 可擴充 流量管理
emergency_home SpikeArrest 政策 標準 流量管理

其他圖示

下表說明交易窗格中其他圖示的用途。這些圖示會標示 Proxy 流程中每個重要的處理步驟。

如何篩選表格：

  • 選取一種圖示類型。
  • 按一下「Name」(名稱) 欄標題，即可依圖示名稱排序表格。
  • 輸入關鍵字，搜尋圖示名稱。

圖示類型

圖示 名稱 類型 說明
monitor 用戶端應用程式 標準交易 傳送要求至 API Proxy 的 ProxyEndpoint 的用戶端應用程式。
circle 轉換端點 標準交易 圓圈標示 Proxy 流程中的轉換端點。無論是要求從用戶端傳入、要求傳送至目標、回應從目標傳回，還是回應傳回用戶端，這些變數都會存在。
stat_0 流程區隔 標準交易

菱形代表 API Proxy 流程中流程區隔的開頭。流程區隔包括：ProxyEndpoint 要求、TargetEndpoint 要求、TargetEndpoint 回應和 ProxyEndpoint 回應。區隔包含 PreFlow、條件式流程和 PostFlow。

詳情請參閱「 條件流程」。
「條件為 true」圖示 條件式流程 true 標準交易

評估結果為 true 的條件式流程 (例如評估結果為 true 的 if 陳述式)。如需條件式流程簡介，請參閱「 條件式流程」。

請注意，部分條件是由 Apigee 產生。舉例來說，Apigee 會使用下列運算式檢查 ProxyEndpoint 是否發生錯誤：

((error.state equals PROXY_REQ_FLOW) or (error.state equals PROXY_RESP_FLOW))

條件不成立圖示 條件式流程 false 標準交易

評估結果為 false 的條件式流程。如需條件式流程的簡介，請參閱「 條件式流程」。

請注意，部分條件是由 Apigee 產生。舉例來說，Apigee 會使用下列運算式，檢查 TargetEndpoint 是否發生錯誤：

(((error.state equals TARGET_REQ_FLOW) or (error.state equals TARGET_RESP_FLOW)) or ((error.state equals REQ_SENT) or (error.state equals RESP_START)))

「flow info」(流程資訊) 圖示 流程資訊 標準交易 代表 API Proxy 執行的背景資訊，會因流程中的時間點而異。包括 Proxy 設定、目前執行狀態 (例如 PreFlow、PostFlow、流程掛鉤)、政策執行詳細資料，以及政策執行期間填入的變數，以指出 Proxy 在該時間點的特定狀態。
done_all 流程執行作業 標準交易 標示流程執行的開始或結束，指出特定流程區隔的時間範圍，以視覺化方式劃分流程邊界，並指出流程執行的順序。
commit 流程處理 標準交易 表示流程中的有效處理作業，代表執行政策和流程邏輯的時間。
bar_chart Apigee Analytics 擷取的資料 標準交易 表示 Analytics 動作已在背景執行。
location_on 後端服務 標準交易 接收要求的後端服務。 API Proxy 呼叫的後端目標。
停用圖示 已停用 步驟狀態 政策停用時，政策圖示上會顯示這個圖示。您可以使用公開 API 停用政策。請參閱 API Proxy 設定參考資料。
錯誤圖示 錯誤 步驟狀態 當政策步驟條件評估為 false 時 (請參閱「 使用流程變數的條件」)，或在 RaiseFault 政策執行時，顯示在 RaiseFault 政策圖示上。
略過圖示 已略過 步驟狀態 如果政策因步驟條件評估為 false 而未執行，政策圖示上會顯示這個圖示。詳情請參閱「 使用流程變數的條件」。

「Phase details」(階段詳細資料) 窗格

階段詳細資料窗格會顯示 Proxy 在每個處理步驟的狀態。

階段詳細資料窗格會提供許多資訊，說明 Proxy 在每個處理步驟的狀態。以下是提供的部分詳細資料。 按一下偵錯工具中的任何圖示，即可查看所選步驟的詳細資料，或使用「>」「下一步」或「<」「上一步」按鈕，在步驟之間移動。

下表說明階段詳細資料窗格中提供的詳細資料。

階段詳細資料 說明
變數

列出政策讀取及指派值的流程變數。另請參閱「 使用流程變數」。
要求標頭 列出 HTTP 要求標頭。
要求內容 顯示 HTTP 要求主體。
屬性 屬性代表 API Proxy 的內部狀態。系統預設不會顯示這些項目。
目標端點 指出選取要執行的 TargetEndpoint。
回應標頭 列出 HTTP 回應標頭。
回應內容 顯示 HTTP 回應主體。

時間軸

時間軸會指出處理時間 (以毫秒為單位) 完成所需的時間。比較經過時間區隔，有助於找出執行時間最長、導致 API 呼叫速度變慢的政策。

Epsilon 表示小於一毫秒的時間範圍。

按一下即可放大圖片 偵錯工具第 2 版使用者介面中的時間軸

展開及收合群組

本節說明如何在「Transaction」窗格中展開及收合群組。

要求和回應的交易步驟會依據先前在「Develop」(開發) 分頁中的設定方式 (依共用流程) 分組。例如：pre-proxy、post-proxy、pre-target 和 post-target。

每個分組都會清楚顯示相關政策、條件、共用流程和流程資訊。

共用流程預設會分組並收合。

您可以在「交易」窗格中執行下列操作：

項目 名稱 說明
展開所有滑桿
<img <="" alt="collapse all slider" class="screenshot" src="/static/apigee/docs/api-platform/debug/images/collapse_all_slider.png" td="" width="" /> 		全部展開
全部收合		 展開或收合所有群組。
「展開群組」圖示
「收合群組」圖示 		展開
收合		 展開或收合群組。

另請參閱：

您可以使用搜尋功能，在要求或回應中尋找字詞或詞組。

您可以使用搜尋功能，在要求或回應中尋找字詞或詞組。

注意事項：

  • 搜尋不區分大小寫
  • 搜尋功能適用於單一交易，也就是說，系統不會在整個偵錯工作階段中搜尋所有交易。
  • 搜尋功能會展開收合的部分，但不會顯示因 「View Options」選項而篩除的節點資訊。

搜尋步驟如下：

  1. 在搜尋框中輸入文字。

  2. 按下 Enter 鍵。

    搜尋結果會在「Transaction」(交易) 窗格和「Phase Details」(階段詳細資料) 窗格中醒目顯示。

  3. 按一下 keyboard_arrow_up「Back」(返回) 或 keyboard_arrow_down「Next」(下一步)，即可移至上一個或下一個步驟。
按一下即可放大圖片 Debug v2 UI 中的搜尋結果

縮放

縮放功能可讓您控制「交易」窗格的檢視畫面。

縮放功能可控制「Transaction」窗格的檢視畫面，如下所示：

按一下即可放大圖片 偵錯第 2 版縮放控制項
圖示 說明
100% 目前縮放等級。預設為 100%。
fit_screen 依螢幕大小自動調整
zoom_in 放大
zoom_out 縮小
youtube_searched_for 重設縮放設定

使用偵錯工具偵錯

偵錯功能可讓您查看 API Proxy 的許多內部詳細資料。例如：

  • 您可以一目瞭然地查看哪些政策正確執行或失敗。
  • 假設您透過其中一個 Analytics 資訊主頁，發現某個 API 的效能異常下降。現在，您可以使用 Debug 找出瓶頸所在。偵錯會提供每個處理步驟完成所需的時間 (以毫秒為單位)。如果發現某個步驟耗時過長，可以採取修正措施。
  • 您可以查看傳送至後端的標頭、查看政策設定的變數等。
  • 驗證基本路徑，即可確保政策將訊息轉送至正確的伺服器。

在偵錯工作階段中篩選資料

建立偵錯工作階段時，您可以為該工作階段新增篩選器，讓 Apigee 只傳回您需要的資料。篩選器是條件陳述式，Apigee 會根據要求和回應訊息評估篩選器，判斷是否應將偵錯資料納入偵錯工作階段。舉例來說，您可以篩選出 HTTP 回應代碼小於 599 的所有要求，或將要求中的值與自訂變數進行比較。

注意事項：

  • 如果請求因篩除而未納入偵錯工作階段，就不會計入偵錯工作階段的交易數量上限。
  • Apigee 不支援在查詢字串中新增篩選器。
  • 偵錯工作階段開始後，就無法新增篩選器。如要新增篩選器，請先建立偵錯工作階段。

使用篩選器

使用 Apigee UI 或 API 建立偵錯工作階段時，請使用篩選器，詳情請參閱下列各節。

Apigee UI

在 UI 中建立偵錯工作階段時，您可以在「Filters」(篩選器) 下拉式選單中選擇要套用至「Start a debug session」(啟動偵錯工作階段) 面板的預先定義篩選器，或選擇「Custom Filter」(自訂篩選器)，並使用篩選器語法自行建立篩選器。

API

如要使用 API 建立含有篩選器的偵錯工作階段，請在偵錯工作階段建立要求中加入下列內容做為酬載：

{
  "filter":"filter_body"
}

如要瞭解如何建構篩選器，請參閱「篩選器語法」。

以下範例建立的偵錯工作階段，僅包含標頭 A 等於 42 且標頭 B 等於 43 的交易，或錯誤代碼為 ExpectedEOF 的交易：

curl -H "Authorization: Bearer $TOKEN" -X "POST"
  https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions
  -d ' {
    "filter":"(request.header.A == '42' && request.header.B == '43') || fault.code == 'jsonparser.ExpectedEOF'"
  } '

您只能在偵錯工作階段建立要求中定義篩選器，無法在現有的偵錯工作階段中新增篩選器，也無法從進行中的偵錯工作階段中移除篩選器。

篩選器語法

篩選器支援 Apigee 條件使用的語法，詳情請參閱「條件參考資料」。包括：

此外，篩選器可以存取「流程變數參考資料」中描述的所有流程變數，以及自訂變數。以下範例僅列出部分可用於篩選器的流程變數：

# Response codes:
  response.status.code <= 599
  response.status.code >=301 && response.status.code <=420

# Requests/responses:
  request.verb == "GET"
  request.header.A == 'B' || request.queryparam.X == 'Y'

# Query parameters:
  request.queryparam.myparam == 'fish'
  (request.queryparam.param1 == 'X' || request.queryparam.param2 == 'Y') && request.queryparam.param3 == 'Z'

# Faults:
  fault.code != 'messaging.runtime.RouteFailed'
  fault.name == 'IPDeniedAccess'

如要瞭解如何使用自訂變數，請參閱 Apigee 社群中的「如何在 Apigee 中使用自訂屬性」。

預先定義的 UI 篩選器

Apigee UI 提供一組常用篩選器，因此您不必自行編寫自訂篩選器。下表匯總了預先定義的篩選器。

篩選條件名稱 說明
Response Time Greater Than

檢查延遲問題，包括：

  • target.duration 是目標延遲時間，也就是要求傳送至目標和從目標接收所需的時間，以毫秒為單位 (計算方式為 target.received.end.timestamp 和 target.sent.start.timestamp 之間的差值)
  • client.duration 是用戶端延遲時間，也就是傳送要求至用戶端及從用戶端接收要求所需的時間，以毫秒為單位 (計算方式為 client.received.end.timestamp 與 client.sent.start.timestamp 之間的差值)

例如：

target.duration > 420 && client.duration > 1000

詳情請參閱流程變數參考資料中的 client 和 target。
Response Code

檢查 HTTP 回應代碼是否與指定值相符，例如：

response.status.code <= 599
Header

檢查指定的要求標頭是否等於指定的值，例如：

request.header.cache-control.1 == "16544"
Path

檢查要求是否與指定路徑相符。您可以在值中使用萬用字元比對，例如：

request.path == /myproxy/customer/4*
Query Param

檢查指定的要求查詢參數是否等於指定的值，例如：

request.queryparam.lang == "language:en-us"
Custom

可插入自己的運算式。您可以使用流程變數參考資料中的任何物件，以及條件參考資料中的語法。此外，您也可以使用自訂變數。

如要進一步瞭解如何建立自訂篩選器，請參閱「篩選器語法」。
 

查看偵錯工作階段

Apigee 會將偵錯工作階段資料儲存 24 小時。您無法設定這個值；24 小時後，資料將無法再使用。在此之前，您可以查看偵錯工作階段。

如要查看最近的偵錯工作階段，請使用 Apigee UI 或 API，詳情請參閱下列各節。

Apigee UI

如要使用 Google Cloud 控制台查看偵錯工作階段

  1. 在 Google Cloud 控制台中，依序前往「Proxy development」(Proxy 開發)>「API Proxies」(API Proxy) 頁面。

    前往「API Proxies」(API Proxy) 頁面

  2. 按一下要偵錯的 Proxy。
  3. 按一下「偵錯」分頁。
  4. 「Recent debug sessions」會顯示可用的偵錯工作階段清單。

  5. 按一下要查看的課程連結。

API

使用 API 可執行下列操作：

使用 API 查看所有偵錯工作階段

如要查看環境中為 API Proxy 修訂版本定義的所有近期偵錯工作階段，請對下列資源發出 GET 要求：

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions

您可以視需要指定下列其中一個查詢參數，控制傳回的資料量：

  • pageSize：要列出的偵錯工作階段數量上限。頁面大小預設為 25。
  • pageToken：先前呼叫傳回的頁面權杖，可用於擷取下一頁。

以下範例說明如何查看 test 環境中 helloworld API Proxy 修訂版本 1 的偵錯工作階段。

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions" \
-X GET \
-H "Authorization: Bearer $TOKEN"

其中 $TOKEN 設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一節所述。如要瞭解本範例中使用的 curl 選項，請參閱「使用 curl」。如需可用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

回應包含 sessions 物件，其中列出目前有效的偵錯工作階段，如以下範例所示：

{
"sessions": [
{
"id": "a423ac73-0902-4cfa-4242-87a353a84d87",
"timestamp_ms": 1566330186000
},
{
"id": "f1eccbbe-1fa6-2424-83e4-3d063b47728a",
"timestamp_ms": 1566330286000
}
]
}

回應只會包含至少有一筆交易的偵錯工作階段，不含任何交易的偵錯工作階段不會列入這份清單。

詳情請參閱「List Debug sessions API」。

使用 API 查看偵錯工作階段的所有交易

如要查看偵錯工作階段的交易清單，請向下列資源發出 GET 要求：

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

其中 debugsession 是查看偵錯工作階段時傳回的偵錯工作階段 ID。

以下範例說明如何查看 test 環境中 helloworld API 修訂版本 1 的偵錯工作階段交易。

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
-X GET \
-H "Authorization: Bearer $TOKEN"

其中 $TOKEN 設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一節所述。如要瞭解本範例中使用的 curl 選項，請參閱「使用 curl」。如需可用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

回應包含交易 ID 陣列，如以下範例所示：

[
"myorg-test-ver-5qxdb-64",
"myorg-test-ver-5qxdb-65",
"myorg-test-ver-5qxdb-66",
"myorg-test-ver-5qxdb-67",
"myorg-test-ver-5qxdb-68",
"myorg-test-ver-5qxdb-69",
"myorg-test-ver-5qxdb-70",
"myorg-test-ver-5qxdb-71",
"myorg-test-ver-5qxdb-72"
]

詳情請參閱「List debug session data API」。

使用 API 查看偵錯工作階段的交易資料

如要查看偵錯工作階段的交易資料，請向下列資源發出 GET 要求：

https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/apis/{api}/revisions/{rev}/debugsessions/{debugsession}/data/{transactionId}

其中 debugsession 是查看偵錯工作階段時傳回的偵錯工作階段 ID，transactionId 則是查看偵錯工作階段的交易清單時傳回的交易 ID。

偵錯工作階段期間儲存的交易資料會採用 JSON 格式。您可以在離線偵錯工具中載入這項資料。

以下範例說明如何下載 test 環境中 helloworld API 修訂版本 1 的偵錯工作階段交易資料。

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data/myorg-test-ver-5qxdb-64" \
-X GET \
-H "Authorization: Bearer $TOKEN"

其中 $TOKEN 設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一節所述。如要瞭解本範例中使用的 curl 選項，請參閱「使用 curl」。如需可用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

回應包含 JSON 酬載，其中含有指定交易的資料，如「下載資料結構」一節所述。

偵錯資料包含流程中每個部分的要求和回應相關資訊，格式為專屬 JSON。您可以儲存這項資料，之後在離線偵錯工具中使用。

如果工作階段結束前未新增任何要求，回應會如下所示：

[]

詳情請參閱「取得偵錯工作階段資料 API」。

在使用者介面中選取檢視選項

本節說明如何選取檢視選項，篩選使用者介面中顯示的內容。

如要選擇偵錯工作階段的檢視選項，請在「View options」窗格中選取或清除選項。系統會為每位使用者保留這些偵錯工作階段的檢視選項。

按一下即可放大圖片 檢視選項清單
選項 說明
顯示已停用的政策 顯示所有已停用的政策。您可以使用公開 API 停用政策。請參閱「API Proxy 設定參考資料」。
顯示已略過的政策 顯示所有略過的政策。如果步驟條件評估為 false，系統就不會執行政策，這時就會發生略過政策的情況。詳情請參閱「使用流程變數的條件」。
顯示所有流程資訊 代表流程區隔內的轉換。
顯示所有流程條件 代表每個流程評估的條件。

分享偵錯工作階段

您可以與具備必要權限且可存取貴機構的其他使用者共用偵錯工作階段。只要將您查看偵錯工作階段時，瀏覽器顯示的網址傳送給他們即可。連結的有效期限為偵錯工作階段建立後的 24 小時內。

正在下載偵錯工作階段資料

您可以下載原始偵錯結果檔案，以便離線觀看。下載的檔案會顯示偵錯工作階段的完整詳細資料，包括所有標頭、變數和政策的內容。

偵錯工作階段資料僅在 24 小時內可供下載或在使用者介面中查看。超過這個時間後，Apigee 會刪除工作階段資料。

如要查看下載的偵錯工作階段資料，請使用離線偵錯工具。

Apigee UI

如要下載 Google Cloud 控制台中的目前偵錯工作階段，請按一下「Debug」檢視畫面中的「Download」。

API

如要使用 Apigee API 查看目前偵錯工作階段的所有交易 ID，請輸入下列指令：

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data

其中 SESSION_ID 是要下載的偵錯工作階段 ID。

請參閱「 列出偵錯工作階段的交易 ID」。

如要使用 Apigee API 取得交易的偵錯資料，請輸入下列指令：

    curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    https://apigee.googleapis.com/v1/organizations/ORG/environments/ENV/apis/PROXY/revisions/REV/debugsessions/SESSION_ID/data/TRANSACTION_ID

下載資料結構

Apigee UI 和 Apigee API 的偵錯工作階段資料下載結構不同。

Apigee UI

使用 Apigee UI 下載資料時，資料結構如下：

  • 包含整個工作階段中的所有交易
  • 將交易儲存在 Messages 陣列中
  • 包含工作階段的中繼資料 (以 DebugSession 物件形式呈現)

API

您無法使用 Apigee API 一次查看整個工作階段的資料，只能使用 API 查看個別交易資料，詳情請參閱「查看偵錯工作階段」。

例如：

{
"completed": true,
"point": [
  ...
...
}

下載資料範例

以下範例醒目顯示下載資料中的 DebugSession 中繼資料物件。這個物件後面接著 Messages 陣列，其中包含工作階段中的交易。

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
  "Messages": [
    {
      "completed": true,
      "point": [
        {
          "id": "Paused"
        },
        {
          "id": "Resumed"
        },
        {
          "id": "StateChange",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "To",
                    "value": "REQ_HEADERS_PARSED"
                  },
                  {
                    "name": "From",
                    "value": "REQ_START"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            },
            {
              "ActionResult": "RequestMessage",
              "headers": [
                {
                  "name": "accept",
                  "value": "*/*"
                },
                {
                  "name": "accept-encoding",
                  "value": "gzip,gzip,deflate,br"
                },
                {
                  "name": "content-length",
                  "value": "0"
                },
                {
                  "name": "host",
                  "value": "myorg.example.domain.net"
                },
                {
                  "name": "user-agent",
                  "value": "Google-Apigee"
                },
                {
                  "name": "x-b3-sampled",
                  "value": "0"
                },
                {
                  "name": "x-b3-spanid",
                  "value": "d4ee579206759662"
                },
                {
                  "name": "x-b3-traceid",
                  "value": "adc1e171777c237dd4ee579206759662"
                },
                {
                  "name": "x-forwarded-for",
                  "value": "66.102.8.98"
                },
                {
                  "name": "x-forwarded-proto",
                  "value": "https"
                },
                {
                  "name": "x-request-id",
                  "value": "54e05cba-4242-4490-4242-60c45c156f90"
                }
              ],
              "uRI": "/myproxy",
              "verb": "GET"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "environment.name",
                    "value": "prod"
                  },
                  {
                    "name": "environment.qualifiedname",
                    "value": "myorg__prod"
                  },
                  {
                    "name": "environment.orgname",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "organization.name",
                    "value": "myorg"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        {
          "id": "FlowInfo",
          "results": [
            {
              "ActionResult": "DebugInfo",
              "properties": {
                "property": [
                  {
                    "name": "apiproxy.qualifiedname",
                    "value": "myproxy__1"
                  },
                  {
                    "name": "apiproxy.basepath",
                    "value": "/"
                  },
                  {
                    "name": "apiproxy.revision",
                    "value": "1"
                  },
                  {
                    "name": "apiproxy.name",
                    "value": "myproxy"
                  }
                ]
              },
              "timestamp": "8-6-19 13:08:37:718"
            }
          ]
        },
        ...
      ...
    }
  ]
}

如果偵錯工作階段不含任何要求，則 Message 陣列會是空的，如下例所示：

{
  "DebugSession": {
    "Retrieved": "2019-06-08T13:08:13.395Z",
    "Organization": "myorg",
    "Environment": "prod",
    "API": "myproxy",
    "Revision": "1",
    "SessionId": "a2a271aa-4242-4ac6-97cb-aec8dcb115a9"
  },
"Messages": []
}

刪除偵錯工作階段的資料

如要使用 Apigee UI 或 API 刪除偵錯工作階段的資料，請按照下列各節的說明操作。

Apigee UI

如要在 Google Cloud 控制台刪除偵錯工作階段，請按照下列步驟操作：

  1. 在「Debug」分頁中，按一下要刪除的工作階段所在資料列。
  2. 在「Debug session」(偵錯工作階段) 窗格中，按一下 「Delete」(刪除)。

API

如要使用 API 刪除所有偵錯工作階段資料，請向下列資源發出 DELETE 要求： 

https://apigee.googleapis.com/v1/organizations/org/environments/env/apis/api/revisions/rev/debugsessions/debugsession/data

其中 debugsession 是查看偵錯工作階段時傳回的偵錯工作階段 ID。

以下範例說明如何刪除 test 環境中 helloworld API 修訂版本 1 的偵錯工作階段資料。

curl "https://apigee.googleapis.com/v1/organizations/myorg/environments/test/apis/helloworld/revisions/1/debugsessions/a423ac73-0902-4cfa-4242-87a353a84d87/data" \
      -X DELETE \
      -H "Authorization: Bearer $TOKEN"

其中 $TOKEN 設為您的 OAuth 2.0 存取權杖，如「取得 OAuth 2.0 存取權杖」一節所述。如要瞭解本範例中使用的 curl 選項，請參閱「使用 curl」。如需可用環境變數的說明，請參閱「設定 Apigee API 要求的環境變數」。

如果成功，回應主體會是空白。

偵錯工作階段資料只會保留 24 小時。如果您未在該時間前明確刪除，Apigee 會為您刪除。