對擴充功能進行偵錯

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

您可以使用兩個位置顯示的訊息偵錯擴充功能：追蹤工具和擴充功能記錄。如果擴充功能無法正常運作，有時需要這兩處的資訊才能找出問題。

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

    Trace 工具中顯示的擴充功能相關錯誤通常不會包含太多詳細資料，只會指出哪個擴充功能呼叫失敗，以及 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 中的 ExtensionCallout 政策開始，經過擴充功能傳送至外部資源，然後再傳回。因此任何位置都可能發生錯誤。

您看到的錯誤可能屬於下列類別。

擴充功能設定錯誤

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

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

Trace 工具中的證據

在 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'

ExtensionCallout 政策設定錯誤

如果擴充功能候選字政策設定錯誤 (例如政策設定語法有誤，或設定鍵/值不正確)，就會發生這類錯誤。視政策設定方式而定，這類錯誤有兩種形式：

  • 外部資源評估的值有誤

    如果擴充功能認為設定錯誤有效，但外部資源無效，就可能發生這種情況。舉例來說，如果擴充功能將不正確的資料庫 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，並將部分 JSON 傳遞至資源。舉例來說，Cloud Logging 擴充功能設定 JSON 包含 metadata 物件，其內容會傳遞至 Cloud Logging。如果金鑰名稱有誤 (例如使用 typ 而非 type)，外部資源可能會傳回錯誤，並顯示為擴充功能記錄中的項目：

    details: 'Resource type cannot be empty'

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

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

Trace 工具中的證據

在 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 會向擴充功能傳回錯誤，而擴充功能會將錯誤新增至擴充功能記錄。

Trace 工具中的證據

在 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'