對擴充功能進行偵錯

您正在查看 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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

  • 您可以使用 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 中的 ExtensionCallout 政策開始，經過擴充功能，傳送至外部資源，然後再傳回。因此，這些位置都可能發生錯誤。

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

擴充功能設定中的錯誤

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

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

Trace 工具中的證據

在 Proxy 編輯器中，這些錯誤通常會顯示為 4xx 或 5xx 層級錯誤。不過，除了指出擴充功能傳回錯誤之外，代理程式編輯器不會顯示任何有關錯誤原因的詳細資訊。

{
  "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 政策設定中的錯誤

當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 層級錯誤。不過，除了指出擴充功能傳回錯誤訊息，代理程式編輯器不會顯示任何有關錯誤原因的詳細資訊。如果在 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 層級錯誤。不過，除了指出擴充功能傳回錯誤之外，代理程式編輯器不會顯示任何錯誤原因的詳細資訊。

{
  "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'