从 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 产品列表。您可以根据客户端 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 表达式未返回数组对象

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

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

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”方法设置了零 (“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 X 会强制执行 Apigee Edge 上记录但未强制执行的某些产品限制。

否

解决方法：超出商品限额

在迁移到 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

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