對擴充功能進行偵錯

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

如要對擴充功能進行偵錯，您可以使用追蹤工具和擴充功能記錄這兩個位置顯示的訊息。當擴充功能無法運作時，有時可能需要同時提供這兩處的資訊，才能找出問題所在。

  • Apigee Edge 追蹤工具可讓您在開發 API Proxy 程式碼時，反覆測試和編輯。追蹤記錄訊息包含 API Proxy 程式碼的錯誤，包括 API Proxy 和政策設定。

    追蹤記錄工具中顯示的擴充功能相關錯誤通常不會包含太多詳細資料，只是會顯示哪些擴充功能呼叫失敗，並同時提供 HTTP 錯誤代碼。如果在這裡看不到任何實用資訊，不妨尋找您正在使用的擴充功能記錄。

  • 擴充功能會在執行階段產生記錄項目。(只有機構管理員可查看擴充功能記錄)。

    這些記錄檔包含由擴充功能設為進行互動的外部資源所傳回的項目。舉例來說，如果擴充功能中的外部資源憑證設定錯誤，錯誤可能會顯示在這裡。

    記錄中也包含來自內部擴充功能程式碼的項目。查看記錄檔時，請記得部分項目與你要修正的錯誤無關。與擴充功能相關的記錄項目通常以 details 這個字開頭，如下列 Cloud Pub/Sub 擴充功能中的記錄項目所示：

    details: 'Invalid resource name given (name=projects/example-test-123456/topic/extension-example). Refer to https://cloud.google.com/pubsub/docs/admin#resource_names for more information.'

錯誤類型和原因

擴充功能要求處理流程從 API Proxy 中的 Extension callout 政策，從擴充功能傳送到外部資源，然後再回到外部資源。因此上述任何位置都可能會發生錯誤。

可能出現的錯誤分為以下類別。

擴充功能設定發生錯誤

這是機構管理員將擴充功能新增至環境時所做的設定。

舉例來說，如果您使用錯誤的 Google Cloud 專案 ID 設定 Cloud Logging 擴充功能，Google Cloud Logging 就會傳回錯誤給擴充功能。這些錯誤的詳細資訊通常會顯示在擴充功能記錄中。

追蹤記錄工具的證據

在 Proxy 編輯器中，這些錯誤通常會顯示為 4xx 或 5xx 層級錯誤。不過，Proxy 編輯器不會顯示有關錯誤原因的任何具體資訊，除非是指出擴充功能傳回錯誤。

{
  "fault": {
    "faultstring":"Execution of ConnectorCallout Logging-Extension failed. Reason: Connector returned error statuscode=500",
    "detail": {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

擴充功能記錄中的證據

這類錯誤的詳細資料會顯示於擴充功能的記錄項目中。Cloud Pub/Sub 服務傳回的錯誤訊息如下，來自專案 ID 格式錯誤的結果。

details: 'Project does not exist: example-test-12345'

額外資訊摘要政策設定有誤

如果 Extension callout 政策設定錯誤 (發生政策設定語法錯誤，或透過不正確的設定鍵/值) 設定錯誤。視政策的設定方式而定，這些錯誤有兩種形式：

  • 外部資源評估的值有誤

    這可能是因為擴充功能發現設定錯誤，但外部資源無效。舉例來說，如果擴充功能將錯誤的資料庫 ID 傳送至 Cloud Spanner，Cloud Spanner 會傳回擴充功能記錄中的錯誤：

    details: 'Database not found: projects/example-test-123456/instances/spanner-extension-example-db/databases/my-business-d'

    政策 <Input> 元素中不正確的設定 JSON 也可能會發生這個錯誤。就部分擴充功能而言，擴充功能會處理 JSON 的部分內容，並將部分內容傳遞至資源。舉例來說，「Cloud Logging 擴充功能」設定 JSON 包含的 metadata 物件，其內容會傳送至 Cloud Logging。如果金鑰名稱不正確，例如 typ 而不是 type，可能會傳回外部資源的錯誤，這些資源會顯示為擴充功能記錄中的項目：

    details: 'Resource type cannot be empty'

  • 擴充功能評估的值不正確

    這些錯誤包括在 <Input> 元素 JSON 中經政策評估的部分含有語法錯誤，以及 <Action> 元素中的動作名稱拼字錯誤等等。這些錯誤通常會出現在追蹤記錄工具中，但不會顯示在擴充功能記錄中。

追蹤記錄工具的證據

在 Proxy 編輯器中，這些錯誤通常會顯示為 4xx 或 5xx 層級錯誤。不過，Proxy 編輯器不會顯示有關錯誤原因的任何具體資訊，除非是指出擴充功能傳回錯誤。如果在 Cloud Firestore 擴充功能中的動作名稱拼寫錯誤，追蹤記錄工具中就會出現下列錯誤。

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404","detail":
    {
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

擴充功能記錄中的證據

如果政策設定導致外部資源發生處理錯誤，錯誤通常會出現在記錄中。

如果因與擴充功能無關的原因，對外部資源提出的要求失敗，就會發生這個錯誤。

例如，假設您使用 Cloud Spanner 擴充功能在資料庫中新增資料列，但該資料列的主鍵值已用於現有資料列。Cloud Spanner 會在擴充功能中傳回錯誤，藉此將錯誤新增至擴充功能記錄檔。

追蹤記錄工具的證據

在 Proxy 編輯器中，這些錯誤通常會顯示為 4xx 或 5xx 層級錯誤。不過，Proxy 編輯器不會顯示任何與錯誤原因相關的特定資訊，除非指出擴充功能傳回錯誤。

{
  "fault":{
    "faultstring":"Execution of ConnectorCallout Add-User-Data failed. Reason: Connector returned error statuscode=404",
    "detail":{
      "errorcode":"steps.connectorcallout.ExecutionFailed"
    }
  }
}

擴充功能記錄中的證據

紀錄中通常會有項目包含外部資源本身的訊息。以下 Cloud Spanner 的記錄訊息說明現有的主鍵值錯誤。

details: 'Row [jonesy42] in table user already exists'