500 內部伺服器錯誤 - 空白路徑

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

問題

用戶端應用程式會取得 500 Internal Server Error 的 HTTP 狀態碼，以及錯誤代碼 protocol.http.EmptyPath 做為 API 呼叫的回應。

錯誤訊息

用戶端應用程式會取得以下回應代碼：

HTTP/1.1 500 Internal Server Error

此外，您可能會遇到以下錯誤訊息：

{
   "fault":{
      "faultstring":"Request path cannot be empty",
      "detail":{
         "errorcode":"protocol.http.EmptyPath"
      }
   }
}

可能原因

如果後端伺服器的要求網址 (以流程變數 target.url 表示) 包含空白路徑，就會發生這個錯誤。

根據 RFC 3986 的第 3 節：語法元件和 RFC 3986 第 3.3 節：路徑：

  1. URI 語法 包含下列元件：

            foo://example.com:8042/over/there?name=ferret#nose
        \_/   \______________/\_________/ \_________/ \__/
         |            |            |            |       |
      scheme      authority       path        query   fragment
  2. path 元件是必要元件，且必須一律使用正斜線 (/)，即使路徑中沒有其他字元也一樣。

因此，如果後端伺服器的要求網址完全沒有 path 元件 (也就是沒有正斜線 (/)，則 Apigee Edge 會傳回 500 Internal Server Error 和錯誤代碼 protocol.http.EmptyPath。

例如：如果 target.url 的值為 https://www.mocktarget.apigee.net，則當 path 元件空白或缺少時，就會發生這個錯誤。

原因 說明 適用的疑難排解指示
後端伺服器網址 (target.url) 的路徑空白 流程變數 target.url 代表的後端伺服器網址含有空白路徑。 Edge Public and Private Cloud 使用者

常見診斷步驟

請使用下列其中一種工具/技巧診斷這項錯誤：

API Monitoring

程序 #1：使用 API 監控功能

如何使用 API Monitoring 診斷錯誤：

  1. 以適當角色的身分 登入 Apigee Edge UI。

  2. 切換至您想要調查問題的機構。

  3. 前往「分析」>「API 監控」>「調查」頁面。
  4. 請選取你發現錯誤的特定時間範圍。

  5. 將「Fault Code」與「Time」進行比較。

  6. 選取含有錯誤代碼 protocol.http.EmptyPath 的儲存格，如下所示：

  7. 錯誤代碼 protocol.http.EmptyPath 的資訊如下所示：

  8. 按一下「查看記錄」 ，展開失敗要求的資料列。

  9. 在「記錄檔」視窗中記下下列詳細資料：
    • 狀態碼： 500
    • Fault 資料來源： target
    • 錯誤代碼： protocol.http.EmptyPath
  10. 如果「Fault Source」為 target，且「Fault Code」為 protocol.http.EmptyPath，則表示後端伺服器網址具有空白路徑。

追蹤記錄

程序 2：使用追蹤工具

如何使用追蹤工具診斷錯誤：

  1. 啟用追蹤工作階段，並採取下列任一做法：
    • 等待發生 500 Internal Server Error 錯誤，或
    • 如果可以重現問題，請透過 API 呼叫來重現問題 500 Internal Server Error

  2. 確保已啟用「Show all FlowInfos」：

  3. 請選取其中一個失敗的要求，然後檢查追蹤記錄。
  4. 瀏覽追蹤記錄的不同階段，找出發生錯誤的位置。

  5. 您會在「目標要求流程開始」階段之後的流程中找到錯誤，如下所示：

  6. 記下追蹤記錄中的錯誤值。

    錯誤：要求路徑不得留空

    由於 Apigee Edge 在「目標要求流程開始」階段之後會引發錯誤，因此後端伺服器網址中的 path 為「空白」。如果流程變數 target.url (代表後端伺服器的網址) 可能透過要求流程中的任一政策以空白路徑更新，就可能發生這種情況。

  7. 從錯誤點向後到「啟動目標要求流程」階段，檢查每個流程中的「讀取和指派的變數」部分。

  8. 決定更新流程變數 target.url 的政策。

    顯示 JavaScript 政策更新流程變數 target.url 的範例追蹤記錄：

    請注意，在上方顯示的追蹤記錄範例中，系統會在名為 SetTargetURL 的 JavaScript 政策中更新流程變數變數 target.url 的值，如下所示：

    target.url : https://mocktarget.apigee.net
  9. 請注意，target.url 包含下列元件：
    • 配置： https://mocktarget.apigee.net
    • path：空白
  10. 因此，您會收到 Request path cannot be empty 錯誤。
  11. 前往追蹤記錄中的「AX」(Analytics (分析) 已記錄) 階段，然後按一下該階段。

  12. 向下捲動至「階段詳細資料」-「錯誤標頭」區段，確定「X-Apigee-fault-code」和「X-Apigee-fault-source」的值，如下所示：

  13. 您將分別看到 X-Apigee-fault-code 和 X-Apigee-fault-source 的值為 protocol.http.EmptyPath 和 target ，表示這個錯誤是因後端伺服器網址的路徑空白所致。
    回應標頭 值
    X-Apigee-fault-code protocol.http.EmptyPath
    X-Apigee-fault-source target

NGINX

程序 3：使用 NGINX 存取記錄檔

如何使用 NGINX 存取記錄檔診斷錯誤：

  1. 如果您是 Private Cloud 使用者，即可使用 NGINX 存取記錄檔來判斷 HTTP 500 Internal Server Error 的重要資訊。

  2. 查看 NGINX 存取記錄檔：

    /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

  3. 搜尋特定時間範圍內 (如果問題過去發生)，或是否有任何要求仍失敗並顯示 500 錯誤代碼500與錯誤代碼 protocol.http.EmptyPath。

  4. 如果發現 X-Apigee-fault-code 與 X-Apigee-fault-code 的值相符，但發現任何 500 錯誤，請判斷 X-Apigee-fault-code 的值。

    NGINX 存取記錄中的 500 錯誤範例：

    以上 NGINX 存取記錄中的範例項目，針對 X- Apigee-fault-code 和 X-Apigee-fault-source 提供下列值：

    標頭 值
    X-Apigee-fault-code protocol.http.EmptyPath
    X-Apigee-fault-source target

    請注意，X-Apigee-fault-code 和 X-Apigee-fault-source 的值分別為 protocol.http.EmptyPath 和 target ，表示這項錯誤是由於後端伺服器網址具有空白路徑所致。

原因：後端伺服器網址 (target.url) 的路徑空白

診斷

  1. 使用 API 監控、追蹤工具或 NGINX 存取記錄檔，按照常見診斷步驟的說明，判斷 500 Internal Server Error 的「Fault Code」和「Fault 來源」。
  2. 如果「Fault Code」為 protocol.http.EmptyPath，且「Fault Source」值為 target，則表示後端伺服器網址具有「空白路徑」。

  3. 後端伺服器網址會以 Apigee Edge 中的流程變數 target.url 表示。嘗試更新後端伺服器網址時，通常就會發生這類錯誤，即使用目標要求流程中的任一政策 (位於 Proxy/共用流程內) target.url「動態」更新，因此其中包含「空白路徑」。

  4. 請透過下列任一步驟判斷資料流變數 target.url 的確實路徑是否為空白路徑，以及該變數值的來源：

    追蹤記錄

    使用追蹤記錄工具

    如果您已擷取這個錯誤的追蹤記錄，請使用使用追蹤工具 中所述的步驟，並且：

    1. 確認 target.url 路徑是否空白。

    2. 如果是，請找出哪些政策已修改或更新 target.url 的值，以便納入空白路徑。

      顯示 JavaScript 政策更新流程變數 target.url: 的範例追蹤記錄

    3. 請注意，在上述追蹤記錄範例中，JavaScript 政策已修改或更新 target.url 的值，以包含空白路徑。
    4. 請注意，target.url 包含下列元件：
      • 配置： https://mocktarget.apigee.net
      • path：空白

    記錄檔

    使用記錄伺服器中的記錄檔

    1. 如果您沒有這個錯誤的追蹤記錄 (間歇性問題)，請使用政策將 MessageLogging 或 Service 呼叫等政策記錄在記錄檔伺服器中，並檢查是否已記錄流程變數 target.url 值的相關資訊。
    2. 如果有記錄，請查看這些記錄並：
      1. 確認 target.url 路徑是否空白，且
      2. 看看是否可以判斷哪些政策修改了 target.url 來包含空白路徑

    API Proxy

    查看失敗的 API Proxy

    如果沒有這個錯誤的追蹤記錄或記錄檔，請查看失敗的 API Proxy，找出修改或更新流程變數 target.url 以包含無效路徑的內容。請檢查下列事項：

    • API Proxy 中的政策
    • 從 Proxy 叫用的任何共用流程

  5. 仔細檢查特定政策 (例如 AssignMessage 或 JavaScript) 仔細修改或更新流程變數 target.url 的原因，並判斷導致 target.url 路徑空白的原因。

    以下是一些政策範例，無法正確更新流程變數 target.url，使其包含空白路徑，導致這個錯誤。

    範例 #1

    範例 1：JavaScript 政策更新 target.url 變數 

    var url = "https://mocktarget.apigee.net"
context.setVariable("target.url", url);

    在上述範例中，請注意，資料流變數 target.url 已更新為另一個變數 url 中的值 https://mocktarget.apigee.net。

    請注意，target.url 包含下列元件：

    • 配置： https://mocktarget.apigee.net
    • path：空白

    由於路徑空白，因此 Apigee Edge 會傳回 500 Internal Server Error 且錯誤代碼 protocol.http.EmptyPath。

    範例 #2

    示例 2：JavaScript 政策更新 target.url 變數

    var path = context.getVariable("request.header.Path");
var url = "https://mocktarget.apigee.net" + path
context.setVariable("target.url", url);

    在上述範例中，請注意，藉由串連變數 url 中的 https://mocktarget.apigee.net 值和 另一個變數 path 的值 (系統會擷取該變數的值從 request.header.Path. 擷取)，藉此更新資料流變數 target.url

    如果您可以存取實際要求或追蹤記錄，就可以驗證傳遞至 request.header.Path 的實際值。

    使用者提出的要求範例：

    curl -v https://HOST_ALIAS/v1/myproxy -H "Authorization: Bearer <token>

    在此範例中，標頭路徑不會作為要求的一部分傳送。因此，JavaScript 政策中的變數路徑值為 null。

    舉例來說：

    • url = https://mocktarget.apigee.net + path
    • url = https://mocktarget.apigee.net + null
    • target.url = https://mocktarget.apigee.netnull

    請注意，target.url 包含下列元件：

    • 配置： https://mocktarget.apigee.netnull
    • path：空白

    範例 #3

    範例 #3：AssignMessage 政策透過其他變數更新 target.url 變數

    <AssignMessage async="false" continueOnError="false" enabled="true" name=">AM-SetTargetURL">
    <DisplayName>AM-SetTargetURL</DisplayName>
    <AssignVariable>
         <Name>target.url</Name>
         <Value>https://mocktarget.apigee.net</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

    請注意，target.url 包含下列元件：

    • 配置： https://mocktarget.apigee.net
    • path：空白

    在上述所有範例中，後端伺服器網址 (target.url) 中的路徑為空白，因此 Apigee Edge 會傳回 500 Internal Server Error 錯誤代碼 protocol.http.EmptyPath。

解析度

根據 RFC 3986 的第 2 節：語法元件規格，path 元件是必要項目，且「必須」一律使用正斜線 (/)，即使 path 中沒有其他字元也一樣。如要修正這個問題，請按照下列步驟操作：

  1. 確認以流程變數 target.url 表示的後端伺服器網址一律有非空白路徑。
    1. 在某些情況下，路徑中可能沒有資源名稱，因此請確保路徑至少包含正斜線 (/)。
    2. 如果您使用任何其他變數來判斷資料流變數 target.url 的值，請確定其他變數沒有空白路徑。
    3. 如果您執行任何字串作業來決定資料流變數 target.url 的值，請確保字串運算的結果或結果不會包含空白路徑。
  2. 在診斷中所述的範例中，您可以修正這項問題，如下所述：

    範例 #1

    示例 1：JavaScript 政策更新 target.url 變數

    為解決這個問題，請在變數 url 中加入正斜線 (/)，如下所示：

    var url = "https://mocktarget.apigee.net/"
context.setVariable("target.url", url);

    範例 #2

    示例 2：JavaScript 政策更新 target.url 變數

    var path = context.getVariable("request.header.Path");
var url = "https://mocktarget.apigee.net" + path
context.setVariable("target.url", url);

    請務必傳遞有效路徑 (例如，將 /iloveapis 當做要求標頭 Path 的一部分) 來修正這個問題，如下所示：

    要求示例：

    curl -v https://HOST_ALIAS/v1/myproxy -H "Authorization: Bearer <token> -H "Path: /iloveapis"

    範例 #3

    範例 #3：AssignMessage 政策透過另一個變數更新 target.url 變數

    請在 AssignMessage 政策的 <Value> 元素中加入有效路徑。舉例來說，您可以將 /json 做為 MockTarget API 的路徑。也就是說，請將 <Value> 元素修改為 https://mocktarget.apigee.net/json，如下所示：

    <AssignMessage async="false" continueOnError="false" enabled="true" name="AM-SetTargetURL">
    <DisplayName>AM-SetTargetURL</DisplayName>
    <AssignVariable>
         <Name>target.url</Name>
         <Value>https://mocktarget.apigee.net/json</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

規格

Apigee Edge 預期根據下列規格，後端伺服器網址 沒有空白路徑：

規格
RFC 3986 第 3 節：語法元件
RFC 3986 第 3.3 節：路徑

如果仍需要 Apigee 支援團隊的任何協助，請參閱「必須收集診斷資訊」。

必須收集診斷資訊

如果按照上述指示操作後仍無法解決問題，請收集下列診斷資訊，然後與 Apigee Edge 支援團隊聯絡。

如果您是公開雲端使用者，請提供下列資訊：

  • 機構組織名稱
  • 環境名稱
  • API Proxy 名稱
  • 完成 curl 指令，用來重現 500 Internal Server Error 錯誤代碼 protocol.http.EmptyPath
  • API 要求的追蹤檔

如果您是 Private Cloud 使用者，請提供下列資訊：

  • 觀察失敗要求的完整錯誤訊息
  • 環境名稱
  • API Proxy 套裝組合
  • API 要求的追蹤檔

  • NGINX 存取記錄檔：

    /opt/apigee/var/log/edge-router/nginx/ORG~ENV.PORT#_access_log

    其中：將 ORG、ENV 和 PORT# 替換為實際值。

  • 訊息處理器系統記錄 /opt/apigee/var/log/edge-message- processor/logs/system.log

參考資料

流程變數 - 目標