从 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 表达式未返回数组对象
摘要 是否需要进行客户端更改？ 解决方法

在 Apigee X 中，包含数组索引或 slice 的 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 表达式未返回数组对象

查找并替换升级后可能会返回不同结果的表达式。

密钥库名称限制
摘要 是否需要进行客户端更改？ 解决方法

Apigee X 密钥库名称只能包含字母、数字和连字符。 Edge 密钥库名称不受这些限制。

否

解决方案：密钥库名称限制

检查密钥库名称，并根据需要更新名称以移除不受支持的字符。

为 API 代理部署多个基本路径
摘要 是否需要进行客户端更改？ 解决方法

在一个环境中部署了 API 代理的多个修订版本，并且每个修订版本都有不同的基本路径。

Apigee Edge 与 Apigee X 之间的差异：

Apigee Edge Apigee X
支持部署 API 代理的多个修订版本，每个修订版本可以具有不同的基本路径。 不支持部署 API 代理的多个修订版本，即使代理具有不同的基本路径也是如此。
否

解决方案：为 API 代理部署多个基本路径

更新所有软件包，以便仅将软件包的一个修订版本部署到环境，无论其基路径如何。

不合规的 HTTP 消息
摘要 是否需要进行客户端更改？ 解决方法

客户端或 API 代理发送的消息（请求或响应）不符合 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”方法设置了 Content-Length 标头字段值为零（“0”）。
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。 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 未解析

使用有效的域名更新目标端点。