從 Apigee Edge 到 Apigee X 的遷移反模式

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

如果您是 Apigee Edge 的現有客戶,可能會選擇將安裝項目遷移至 Apigee X,以便運用新功能或不同的區域可用性。

本頁說明設定中的反模式,以及遷移至 Apigee X 前需要注意的其他行為變更。

更廣泛的 Apigee Edge 反模式清單說明瞭在任何情況下都應避免的使用做法。本頁說明不建議使用的特定做法,這些做法會導致遷移作業遭到封鎖。請立即解決這些問題,以免遷移至 Apigee X 時發生問題。

沒有 API 產品的應用程式

摘要 需要變更用戶端嗎? 解決方法

部分應用程式沒有 API 產品。

Apigee Edge 和 Apigee X 的差異:

Apigee Edge Apigee X
您可以設定與任何 API 產品無關的應用程式和憑證。這個應用程式實際上可以存取所有 API 產品。 每個應用程式都必須設定為存取至少一項 API 產品。 無法以隱含方式授予所有 API 產品的存取權。 您可以設定應用程式存取所有 API 產品,但必須明確設定。
否。

解決方法:沒有 API 產品的應用程式

將每個應用程式憑證與至少一項 API 產品建立關聯。如要進一步瞭解如何執行這項操作,請參閱「註冊應用程式及管理 API 金鑰」。

最簡單的方法是為每個應用程式指派所有 API 產品的存取權。 這相當於 Apigee Edge 的功能。 如果您想採用「最低權限」做法,就必須判斷每個應用程式憑證必須存取的 API 產品最低清單。您可以根據用戶端 ID,使用 Apigee Edge Analytics 報表分析這項資料。

沒有到期時間的快取

摘要 需要變更用戶端嗎? 解決方法

快取沒有到期時間。

Apigee Edge 和 Apigee X 的差異:

Apigee Edge Apigee X
支援建立、更新及刪除快取資源描述元。 不支援建立、更新或刪除快取資源描述元。

解決方式:快取沒有到期時間

為所有快取設定到期時間。

非明確路徑的 JSONPath 篩選運算式

摘要 需要變更用戶端嗎? 解決方法

對於非明確路徑,查詢篩選運算式的結果並非 JSONPath 規格的一部分。請參閱 https://goessner.net/articles/JsonPath/

Apigee Edge 和 Apigee X 的差異:

瀏覽這個範例結構時,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

使用 $..books[?(@.name == 'A')][0] 運算式,

Apigee Edge Apigee X
輸出 ‘{"name": "A"}’ 輸出 []

使用 $..books[?(@.name == 'A')][0].name 運算式,

Apigee Edge Apigee X
輸出 "A" 輸出 []

解決方法:非明確路徑的 JSONPath 篩選器運算式

尋找並取代受影響的查詢。

不存在的索引的 JSONPath 運算式

摘要 需要變更用戶端嗎? 解決方法

在 Apigee X 中,如果 JSONPath 運算式含有不存在的索引,行為會與 Apigee Edge 不同。如果找不到路徑,Apigee X 會傳回 PathNotFoundException 錯誤。

Apigee Edge 和 Apigee X 的差異:

瀏覽這個範例結構時,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

使用 $.books[3] 運算式,

Apigee Edge Apigee X
輸出 null 輸出 PathNotFoundException 錯誤

解決方法:針對不存在的索引使用 JSONPath 運算式

尋找並取代受影響的查詢。

JSONPath 運算式 (含陣列索引) 未傳回陣列物件

摘要 需要變更用戶端嗎? 解決方法

在 Apigee X 中,含有陣列索引或切片的 JSONPath 運算式會傳回陣列物件。

Apigee Edge 和 Apigee X 的差異:

瀏覽這個範例結構時,

{
    "books": [
      {
        "name": "A",
      },
      {
        "name": "B",
      }
    ]
}

使用 $.books 運算式,

Apigee Edge Apigee X
輸出 {“name”:”A”, “name”: “B”} 輸出 [{“name”:”A”, “name”: “B”}]

使用 $.books[-1] 運算式,

Apigee Edge Apigee X
輸出 {“name”: “B”} 輸出 [{“name”: “B”}]

使用 $.books[-2:] 運算式,

Apigee Edge Apigee X
輸出 {“name”:”A”, “name”: “B”} 輸出 [{“name”:”A”, “name”: “B”}]

解決方式:含有陣列索引的 JSONPath 運算式未傳回陣列物件

找出並取代升級後可能傳回不同結果的運算式。

KeyStore 名稱限制

摘要 需要變更用戶端嗎? 解決方法

Apigee X 金鑰儲存區名稱只能包含英文字母、數字和連字號。 邊緣金鑰儲存區名稱不受這些限制。

解決方案:Keystore 名稱限制

檢查金鑰儲存區名稱,並視需要更新名稱,移除不支援的字元。

為 API Proxy 部署多個基本路徑

摘要 需要變更用戶端嗎? 解決方法

API Proxy 的多個修訂版本部署在環境中,且每個修訂版本都有不同的基本路徑。

Apigee Edge 和 Apigee X 的差異:

Apigee Edge Apigee X
支援部署 API Proxy 的多個修訂版本,每個修訂版本可以有不同的基本路徑。 即使 API Proxy 有不同的基本路徑,也不支援部署多個修訂版本。

解決方案:為 API Proxy 部署多個基本路徑

更新所有套件,讓環境只部署一個套件修訂版本,無論基本路徑為何都一樣。

不符規定的 HTTP 訊息

摘要 需要變更用戶端嗎? 解決方法

用戶端或 API Proxy 傳送的訊息 (要求或回應) 不符合 HTTP 標準。例如無效的標頭名稱、部分受限標頭中的重複項目等。

如果 API 執行作業發生下列一或多項錯誤,您就無法遷移至 Apigee X:

錯誤 詳細資料
INVALID_CHARACTERS_IN_HEADER 指定標題中有一或多個無效字元。有效的標頭名稱由英文字母、數字和連字號組成。
MISSING_COLON 標頭名稱和標頭值配對中缺少 : (半形冒號)。
MULTIPLE_CONTENT_LENGTH Content-Length 標頭提供多個值。
CONTENT_LENGTH_NOT_INTEGER Content-Length 標頭值不是整數。
INVALID_UPGRADE Upgrade 標頭必須僅用於啟用 WebSocket 連線,但實際並非如此。
URL_HEADER_SIZE_TOO_LONG 要求網址和標頭的總大小超過允許的上限 15 KB。
BODY_NOT_ALLOWED 「GET」、「DELETE」、「TRACE」、「OPTIONS」和「HEAD」方法不允許使用訊息內文。
UNSUPPORTED_HTTP_VERSION 要求使用的 HTTP 版本不是 1.1,因此不受支援。
ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT 為「POST」或「PUT」方法設定的 Content-Length 標頭欄位值為零 (「0」)。
UNSUPPORTED_RESPONSE_PREFIX 回應標頭中含有不受支援的「X-Apigee-」標頭前置字元。
是,可能會。

解決方案:不符規定的 HTTP 訊息

遷移至 Apigee X 前,請務必修正 HTTP 協定中的所有錯誤。如果錯誤源自於用戶端應用程式,您必須請用戶端應用程式的開發人員修正問題。

OAuth 2.0 權杖到期時間無效

摘要 需要變更用戶端嗎? 解決方法

OAuth 2.0 權杖到期限制超出規定範圍。

Apigee Edge 和 Apigee X 的差異:

Apigee Edge Apigee X
目前系統不會強制執行 OAuth 2.0 權杖到期時間的限制,但預計會實施這項措施。請參閱「限制」頁面的 OAuth 專區 您必須為 OAuth 2.0 設定存取憑證和更新憑證的到期時間。支援的範圍如下:
  • 180 秒 <= OAuth 2.0 存取權杖到期時間 <= 30 天
  • 1 天 <= OAuth 2.0 更新權杖到期時間 <= 2 年

解決方法:OAuth 2.0 權杖到期時間無效

使用 OAuthV2 政策,並在 <ExpiresIn><RefreshTokenExpiresIn> 中指定有效期限。

超過產品數量上限

摘要 需要變更用戶端嗎? 解決方法

Apigee Edge 的設定不符合定義的產品限制。Apigee Edge 上未強制執行的部分產品限制,在 Apigee X 上會強制執行。

解決方法:超出產品限制

在遷移至 Apigee X 之前,請先修正任何超出產品限制的使用情形。

同時具有端點和路徑目標連線指定項的 ServiceCallout 政策

摘要 需要變更用戶端嗎? 解決方法

在 ServiceCallout 政策中,<LocalTargetConnection> 元素應包含 <APIProxy><ProxyEndpoint> 元素,或 <Path> 元素,但不能同時包含兩者。詳情請參閱 <LocalTargetConnection> 元素。

Apigee Edge 文件會說明這項規定,但不會強制執行。如果 Apigee X 遇到同時具有這兩種設定的 <LocalTargetConnection>,就會停止處理。

解決方法:同時具有端點和路徑目標連線指定項的 ServiceCallout 政策

檢查 ServiceCallout 政策設定,並移除任何不符規定的 <LocalTargetConnection> 設定。

目標伺服器名稱限制

摘要 需要變更用戶端嗎? 解決方法

Apigee X 目標伺服器名稱只能包含英文字母、數字、連字號和半形句號。 邊緣目標伺服器名稱不受這些限制。

解決方案:目標伺服器名稱限制

檢查目標伺服器名稱,並視需要更新名稱,移除不支援的字元。

虛擬主機中的試用憑證

摘要 需要變更用戶端嗎? 解決方法

一或多個虛擬主機使用 Apigee 提供的「免費試用」憑證。這會導致虛擬主機回應 ORG-ENV.apigee.net 等網域的要求。

Apigee Edge 和 Apigee X 的差異:

Apigee Edge Apigee X
自動設定「預設」虛擬主機,支援 ORG-ENV.apigee.net 形式的網域名稱。我們提供萬用字元憑證 (又稱「免費試用憑證」),允許在這些網域上使用 TLS。 Apigee X 不支援 ORG-ENV.apigee.net 形式的舊版 Apigee 網域。您必須設定自己的網域名稱,並適當佈建憑證。

解決方案:虛擬主機中的試用憑證

您必須設定自己的網域,並適當佈建憑證。

凡是依附於表單舊版網域名稱 ORG-ENV.apigee.net 的用戶端應用程式,都必須修改為呼叫新網域。

未解析的 DNS

摘要 需要變更用戶端嗎? 解決方法

目標端點有無法解析的網域名稱。

Apigee Edge 和 Apigee X 的差異:

Apigee Edge Apigee X
如果 DNS 解析失敗,Apigee 會在網域名稱後方附加 .apigee.com,且 DNS 會成功解析,並傳回 4xx 回應代碼。 如果 DNS 解析失敗,Apigee 不會執行要求,並傳回 5xx 回應代碼。

解決方式:未解析的 DNS

使用有效的網域名稱更新目標端點。