從 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 和 Apigee Edge 中,含有不存在索引的 JSONPath 運算式會產生不同的行為。如果找不到路徑,Apigee X 會傳回 PathNotFoundException 錯誤。

Apigee Edge 和 Apigee X 的差異:

瀏覽這個範例結構時,

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

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

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

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

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

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

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

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

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 金鑰庫名稱只能包含英文字母、數字和連字號。Edge 金鑰存放區名稱不會設有這些限制。

解決方法:Keystore 名稱限制

檢查 KeyStore 名稱,並視需要更新名稱,移除不支援的字元。

為 API Proxy 部署多個基礎路徑

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

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

Apigee Edge 和 Apigee X 的差異:

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

解決方法:為 API Proxy 部署多個基礎路徑

更新所有套件,這樣無論 basepath 為何,都只會將一個套件修訂版本部署至環境。

不符合規定的 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 要求使用 1.1 以外的 HTTP 版本,系統不支援這類版本。
ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT 為「POST」或「PUT」方法設定零 (「0」) 的 Content-Length 標頭欄位值。
UNSUPPORTED_RESPONSE_PREFIX 回應標頭中出現不支援的「X-Apigee-」標頭前置字串。
是的,可能會。

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

您必須先修正 HTTP 通訊協定中的所有錯誤,才能遷移至 Apigee X。如果錯誤來自用戶端應用程式,您必須請用戶端應用程式的開發人員修正問題。

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 目標伺服器名稱只能包含英文字母、數字、連字號和半形句號。 Edge 目標伺服器名稱不會設有這些限制。

解決方法:指定目標伺服器名稱限制

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

虛擬主機中的試用憑證

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

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

Apigee Edge 和 Apigee X 的差異:

Apigee Edge Apigee X
自動設定「預設」虛擬主機,以支援 ORG-ENV.apigee.net 格式的網域名稱。有一個萬用字元憑證 (稱為「免費試用憑證」),可在這些網域上啟用 TLS。 ORG-ENV.apigee.net 格式的舊版 Apigee 網域不適用於 Apigee X。您必須自行設定網域名稱,並適當地提供憑證。

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

您必須設定自己的網域,並適當地提供憑證。

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

未解析的 DNS

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

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

Apigee Edge 和 Apigee X 的差異:

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

解決方法:未解析 DNS

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