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

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

身為 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 產品最低數量清單。您可以透過 Apigee Edge Analytics 報表,根據用戶端 ID 進行分析。

不含到期時間的快取

摘要 需要進行用戶端變更嗎? 解析度

快取沒有到期時間。

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 KeyStore 名稱只能使用英文字母、數字和連字號。邊緣 KeyStore 名稱不會強制執行這些限制。

解決方案:KeyStore 名稱限制

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

為 API Proxy 部署的多個基本路徑

摘要 需要進行用戶端變更嗎? 解析度

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

Apigee Edge 和 Apigee X 的差異:

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

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

更新所有套件,讓系統無論基礎路徑為何,都只會將套裝組合的一個修訂版本部署至環境。

不符規定的 HTTP 訊息

摘要 需要進行用戶端變更嗎? 解析度

用戶端或 API Proxy 會傳送不符合 HTTP 標準的訊息 (要求或回應)。例如標頭名稱無效、某些受限制的標頭中有重複內容等。

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

  • INVALID_CHARACTERS_IN_HEADER
  • MISSING_COLON
  • MULTIPLE_CONTENT_LENGTH
  • CONTENT_LENGTH_NOT_INTEGER
  • INVALID_UPGRADE
  • URL_HEADER_SIZE_TOO_LONG
  • BODY_NOT_ALLOWED
  • UNSUPPORTED_HTTP_VERSION
  • ZERO_CONTENT_LENGTH_FOR_POST_OR_PUT
  • UNSUPPORTED_RESPONSE_PREFIX
有可能。

解決方案:不符規定的 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。

同時使用端點和路徑目標連線指定碼的服務呼叫政策

摘要 需要進行用戶端變更嗎? 解析度

在 Service callout 政策中,<LocalTargetConnection> 元素應包含 <APIProxy><ProxyEndpoint> 元素或 <Path> 元素,但兩者只能擇一。詳情請參閱 <LocalTargetConnection> 元素。

Apigee Edge 記錄了這項要求,但不會強制執行。如果 Apigee X 遇到兩種設定的 <LocalTargetConnection>,就會停止處理。

解決方案:同時使用端點和路徑目標連線指定碼的 Service 呼叫政策

檢查服務呼叫政策設定,並排除任何不符合規定的 <LocalTargetConnection> 設定。

目標伺服器名稱限制

摘要 需要進行用戶端變更嗎? 解析度

Apigee X 目標伺服器名稱只能使用英文字母、數字、連字號和半形句號。 邊緣目標伺服器名稱不會強制執行這些限制。

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

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

虛擬主機的試用憑證

摘要 需要進行用戶端變更嗎? 解析度

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

Apigee Edge 和 Apigee X 的差異:

Apigee Edge Apigee X
自動設定「default」vhost,支援 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

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