4.15.07.00 - 适用于私有云的 Apigee Edge 版本说明

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档。 信息

2015 年 9 月 8 日（星期二），我们发布了适用于私有云的 Apigee Edge 的重要功能版本。

自上一个 Edge Private Cloud 季度版本 (4.15.04.00) 发布以来，我们发布了以下版本，这些版本也包含在本季度版本中：

• Cloud：15.04.15、15.04.29、15.05.27、15.06.10 和 15.06.24
• 私有云：4.15.04.01

您可以升级到哪些 Edge 版本 4.15.07.00

根据您当前的 Edge 版本，您可以执行以下操作：

• 直接升级到 4.15.07.00
• 增量升级，即您必须先从当前版本升级到其他版本的 Edge，然后再升级到 4.15.07.00。

如需了解详情，请参阅哪些 Edge for Private Cloud 版本可以升级到 4.15.07.00。

从 4.15.01.x 或更低版本升级之前

1. 检查 Cassandra SSTable 版本：
   1. 将目录更改为 /<install-root>/apigee4/data/cassandra/data。
   2. 运行 find 命令，
      > find。-name *-ic-*
      如果您运行的是 Cassandra 1.2 SSTable，则结果应返回一组 .db 文件。
   3. 运行以下 find 命令：
      > find . -name *-hf-*
      结果应为空，即没有任何 .db 文件采用 hf 格式。如果您没有看到任何 hf 格式的文件，则说明已完成，可以升级到 4.15.07.00。
      
      hf 格式适用于 Cassandra 1.0 SSTable。如果您有任何采用 hf 格式的 *.db 文件，则必须按照本过程的其余部分所述升级 SSTable。
2. 如果您发现任何 *.db 文件采用 hf 格式，请在每个 Cassandra 节点上运行以下命令，直到升级所有 Cassandra 节点为止，以升级 SSTable：
   > /<install-root>/apigee4/share/apache-cassandra/bin/nodetool -h localhost upgradesstables -a
3. 重复第 1 步，检查所有 *.db 文件是否均采用 Cassandra 1.2 版的 ic 格式。
4. 对 Edge 安装中的每个 Cassandra 节点重复第 1 步到第 3 步。
5. 升级到 Edge 4.15.07.00。
6. 在 4.15.07.00 升级后，请检查 *.db 文件，确保它们都已升级到 C* 2.0 样式的 sstable：
   > cd /<install-root>/apigee4/data/cassandra/data
   > find . -name *-jb-*
   如果您运行的是 Cassandra 2.0，此命令应返回一组 .db 文件。

新功能和增强功能

以下是此版本中的新功能和增强功能：

安装和升级

选择性组件升级和卸载

现在，您可以使用 apigee-upgrade.sh 和 apigee-uninstall.sh 脚本选择要升级或卸载的 Edge 组件。以前，它会升级或卸载节点上的所有组件。 (OPDK-1377、OPDK-1175)

升级回滚

如果 apigee-upgrade.sh 在升级过程中失败，您现在可以使用 apigee-rollback.sh 脚本回滚升级。解决所有升级问题后，您可以重试升级。 (OPDK-1275)

简短的安装程序脚本选项

安装脚本不再采用长格式选项，例如 --help。现在，它们只接受单个字母选项，例如 -h。(OPDK-1356)

SmartDocs 安装

使用 setup-smartdocs.sh 脚本安装 SmartDocs 时，系统会提示您输入组织、环境和虚拟主机，以确保 SmartDocs 安装在预期位置。以前，这些值在脚本中采用硬编码格式。(OPDK-1310)

无需提示即可运行 update-cass-pwd-in-config.sh

如果您设置了 ENABLE_CASS_AUTH、CASS_USERNAME 和 CASS_PASSWORD 环境变量，update-cass-pwd-in-config.sh 脚本便可在无提示的情况下运行。(OPDK-1309)

Edge 平台

以下是此版本中包含的新 Edge 平台功能。

Edge Private Cloud 支持 OpenJDK 1.7

此版本的 Edge 支持 Oracle JDK 1.7 和 OpenJDK 7，并移除了对 JDK 1.6 的支持。 (OPDK-1187)

操作系统支持

Apigee Edge for Private Cloud 扩大了操作系统支持范围，新增了 Red Hat Enterprise Linux 6.6 和 7.0（64 位）、CentOS 6.5、6.6 和 7.0（64 位）以及 Oracle Linux 6.5。

OPDK 15.07 中包含 Cassandra 2.0.15

此版本会安装 Cassandra 2.0.15。如果您要升级到之前的版本，您的 Cassandra 版本将会更新。(OPDK-1197)

对 OAuth 令牌哈希的 SHA2 支持

为了在发生数据库安全问题时更好地保护 OAuth 令牌，Edge 支持使用 SHA2 算法（除了 SHA1 之外）对 OAuth 令牌进行哈希处理。借助新的组织级属性，您可以为新令牌启用和配置哈希处理，还可以保留此新功能之前存在的所有令牌的旧版哈希处理。以前，在 Edge for Private Cloud 中，keymanagement.properties 文件（在管理服务器和消息处理器上）中名为 hash.oauth.tokens.enabled 的属性可启用对 OAuth 令牌的自动 SHA1 哈希处理。此属性现已废弃。

如果您之前使用 hash.oauth.tokens.enabled 属性启用了 SHA1 哈希，此版本的升级脚本会自动为您生成新的组织级属性。如需在升级后进行验证，请使用以下 API 以系统管理员身份执行 GET 请求：https://{host}:{port}/v1/o/{your_org}。

• 如需了解如何使用新属性在组织中启用令牌哈希处理，请参阅请求访问令牌主题中的“在数据库中对令牌进行哈希处理”。
• 如需了解如何对现有令牌进行批量哈希处理，请参阅 Edge for Private Cloud 操作指南。(APIRT-1389)

日志文件的扁平目录结构

您可以通过在 message-logging.properties 文件中将新的 enable.flat.directory.structure 属性设置为 true，将 Edge 配置为将日志文件存储在扁平目录结构中。如需了解详情，请参阅“消息日志记录”政策。 (APIRT-1394)

环境缓存性能

为了更好地管理和利用内存缓存，我们已废弃环境缓存资源的“内存中元素的数量上限”设置。所有缓存资源（包括默认缓存）中存在的元素总数取决于分配给缓存的总内存。默认情况下，为给定消息处理器的内存中缓存分配的内存总量为可用内存总量的 40%，具体取决于消息处理器 cache.properties 文件中的缓存属性设置。只有在缓存内存不足或元素过期时，系统才会从内存缓存中驱逐元素。

如需恢复使用“内存中元素的数量上限”属性进行缓存管理的旧行为，请在 cache.properties 文件中设置属性 overrideMaxElementsInCacheResource=false。(APIRT-1140)

API 服务

以下是此版本中包含的新 API 服务功能。

将新版代理编辑器设为默认

管理界面中默认启用新的 API 代理编辑器。新版编辑器在易用性方面进行了诸多改进，包括在“概览”页面上更全面地查看条件流和端点、在“开发”页面上进行所有配置、更直观地添加条件流、端点和政策、提供更完整的 XML 视图（而非小段代码）、搜索抓取文件名和文本等。(MGMT-2279)

新增了“删除 OAuth v2.0 信息”政策

借助新的“删除 OAuth v2.0 信息”政策，您可以删除 OAuth v2 访问令牌和授权代码。该政策取代了之前由 Management API 提供的功能。如需了解详情，请参阅 DeleteOAuthV2Info 政策。(MGMT-2257)

新增了“删除 OAuth v1.0 信息”政策

借助新的“删除 OAuth v1.0 信息”政策，您可以删除 OAuth v1.0 请求令牌、访问令牌和验证器代码。该政策取代了之前由 Management API 提供的功能。如需了解详情，请参阅“删除 OAuth V1 信息”政策。 (APIRT-1351)

AccessControl 政策

访问控制政策已得到增强，以便在 X-FORWARDED-FOR HTTP 标头中包含 IP 地址时，对 IP 地址进行更精细的评估，以便将其列入许可名单或拒绝名单。

在标头上启用多 IP 地址检查（请与支持团队联系以设置 feature.enableMultipleXForwardCheckForACL）后，您可以使用政策中的新 <ValidateBasedOn> 元素检查标头中的第一个 IP、最后一个 IP 或所有 IP。如需了解详情，请参阅“访问权限控制”政策。

“访问实体”政策中的新实体

“访问实体”政策可提供对以下新实体的访问权限：consumerkey-scopes、authorizationcode、requesttoken 和 verifier。如需了解详情，请参阅 Access Entity 政策。

Statistics Collector 政策：自动将统计名称转换为小写

在 API 代理编辑器（“开发”页面 >“工具”>“自定义分析集合”）中创建自定义分析集合时，收集器变量（统计信息）“名称”必须采用小写形式。 如果您输入的是全大写的名称，该工具会在 Statistics Collector 政策中自动将统计名称转换为小写。(MGMT-740)

移除了 API 代理编辑器中的“传统轨迹”

API 代理编辑器中最新版的 Trace 功能已从 Beta 版升级为正式版。您无法再通过“访问传统版轨迹”链接访问“传统轨迹”。

通过管理界面“帮助”菜单访问 Apigee 社区

您可以通过管理界面“帮助”菜单访问 Apigee 社区。

管理界面中的错误消息

以下是管理界面中增强的错误消息功能：

• 管理界面用于在整个登录会话期间对界面上的所有错误消息进行分组和显示，除非您关闭了这些消息。此次更新后，当您离开出现错误消息的页面时，系统会自动清除这些错误消息。(MGMT-2254)
• 管理界面不再抑制重复的错误消息。(MGMT-2242)

改进了界面性能和错误

对管理界面的不同方面进行了常规增强，包括页面显示性能和错误消息清理。

管理界面“组织用户”页面上的角色超链接

在管理界面（“管理”>“组织用户”）的“组织用户”页面上，角色名称现在是超链接，可让您快速导航到角色页面。(MGMT-1055)

消息流中的新目标变量

消息流中的新变量可为目标端点和目标服务器提供更完整的网址信息：

• TargetEndpoint：request.url 取代了 target.basepath.with.query。
• TargetServer：loadbalancing.targetserver 取代了 targetserver.name。 此外，只有在 TargetEndpoint 的 HTTPTargetConnection <LoadBalancer> 元素中使用 <Path> 元素时，才会填充 target.basepath。

服务器名称指示 (SNI) 支持

Edge 支持使用服务器名称指示南向（从消息处理器到目标端点）。如果您想使用 SNI，请与 Apigee 支持团队联系。

必须使用 Java 1.7。

SNI 是 TLS/SSL 的扩展，可通过同一 IP 地址和端口提供多个 HTTPS 目标，而无需所有这些目标都使用相同的证书。

无需进行任何 Edge 专用配置。如果您的环境配置为南向 SNI（默认为 Edge Cloud），Edge 支持该配置。

Edge 会自动从请求网址中提取主机名，并将其添加到 SSL 握手请求中。例如，如果目标主机是 https://example.com/request/path，则 Edge 会添加 server_name 扩展，如下所示：

如需详细了解 SNI，请参阅 http://en.wikipedia.org/wiki/Server_Name_Indication。

SSL 证书详情中的“签名算法”

SSL 证书详情中新增了“签名算法”字段，可在管理界面（“管理”>“SSL 证书”）和管理 API（从密钥库或信任库获取证书详情）中查看。该字段显示“sha1WithRSAEncryption”或“sha256WithRSAEncryption”，具体取决于用于生成证书的哈希算法类型。

显示即将过期的 SSL 证书

管理界面中的“SSL 证书”页面（“管理”>“SSL 证书”）会指明 SSL 证书在 10、15、30 或 90 天内即将过期，具体取决于您在新建的“到期时间”下拉字段中所做的选择。

威胁防范错误配置

默认情况下，如果消息未通过 JSON 或 XML 威胁防范限制，Edge 会抛出 HTTP 500 内部服务器错误状态代码和 ExecutionFailed 错误。您可以使用新的组织级属性更改错误行为。将组织属性 features.isPolicyHttpStatusEnabled 设置为 true 时，将发生以下行为：

• 请求：将威胁防范政策附加到任何请求流后，无效消息将返回 400 状态代码，以及对应的政策错误消息。
• 响应：将威胁防范政策附加到任何响应流后，无效消息仍会返回 500 状态代码，并会抛出其中一个对应的政策错误消息（而不仅仅是 ExecutionFailed）。

Cloud 客户必须联系 Apigee 支持来设置组织属性。在 Private Cloud 的下一季度版本中，Edge Private Cloud 客户将可以使用此功能。

更新了端点、代理和其他实体的架构

更新了 TargetEndpoint、ProxyEndpoint、APIProxy 等非政策实体的参考架构。请参阅 https://github.com/apigee/api-platform-samples/tree/master/schemas。 (APIRT-1249)

开发者服务

以下是此版本中包含的开发者服务新功能。

SmartDocs 正式版

SmartDocs 已从 Beta 版阶段过渡至正式版阶段。更新和新功能包括：

• 支持 Swagger 2.0，包括通过文件或网址导入，以及支持自定义命名的安全对象。
• 改进了用于生成 SmartDocs 的模板的视觉设计。
• 开发者门户中的易用性和工作流增强功能，可通过 Drupal 中的“Content”>“SmartDocs”菜单使用。
• 以前称为“自定义令牌”的身份验证方式现已更名为“API 密钥”。
• 在修订级别定义的身份验证“安全”对象。
• 在模板级别配置客户端身份验证。新修订版不再重置任何预配置的 SmartDocs 客户端凭据。

如需了解更多功能说明，请参阅这篇博文。

如需查看 SmartDocs 文档，请参阅使用 SmartDocs 记录 API。

管理界面中显示的开发者应用名称

Edge 中的开发者应用既有不会更改的内部名称，也有可更改的显示名称。在管理界面中的“开发者应用”页面（“发布”>“开发者应用”>应用名称）上，系统会将应用的内部“名称”与“显示名称”一起显示，以便您更轻松地通过内部名称直观地识别应用，从而进行问题排查和 API 管理。

分析服务

以下是此版本中包含的新 Google Analytics 服务功能。

保留的数据时限

使用管理界面或 API 生成分析报告时，默认情况下无法获得从当前日期起 6 个月之前的数据。如果您需要访问 6 个月之前的数据，请与 Apigee 支持团队联系。

经典版自定义报告将从管理界面中移除

管理界面中不再提供可选的经典版自定义 Google Analytics 报告。

“开发者互动”微件效果

我们改进了主要分析信息中心（“开发者互动”部分）的漏斗微件，以提供更好的性能。

创收

以下是此版本中包含的新创收功能。

费率方案电子邮件通知

借助新的费率方案电子邮件通知类型，您可以在开发者达到其所购买的按交易量或套餐费率方案的特定交易次数或金额上限时通知他们。如需了解详情，请参阅使用通知模板设置通知。

周期性费用和汇总依据周期的同步

在费率方案中，可能有两个不同的有效时间段：

• 在费率方案的“费用”标签页中配置的周期性费用周期，用于确定向开发者收取周期性费用的时机。
• 汇总依据期，在按量分级或套餐方案的费率卡上定义，用于确定为开发者重置套餐使用情况的时间。

这两个时间段现在已同步。如果费率方案中同时包含非零周期性费用和“按流量分段”或“套餐”费率卡，则这两项都采用相同的周期性费用周期。例如，如果存在按月周期性收费，则费率卡套餐也会按月重置（默认情况下在月初重置）。

如果没有周期性费用，系统会根据费率卡上定义的汇总依据重置套餐。例如，如果开发者在当月 19 日开始使用费率卡，且汇总依据为每月，则套装使用次数会在 19 日之后的一个月重置。

“汇总依据”功能即将弃用，并将在未来的版本中从创收功能中移除。如需了解详情，请参阅指定费率卡方案详细信息。

汇总收入报告中的自定义属性

借助事务记录政策，您可以选择捕获交易中的自定义属性数据，并且现在可以将这些自定义交易属性添加到摘要收入报告中。通过向贵组织添加 MINT.SUMMARY_CUSTOM_ATTRIBUTES 属性，您可以指明要添加到数据库表中以在报告中使用的自定义属性。

Apigee Edge for Private Cloud 客户可以使用以下 API 调用和系统管理员凭据设置此标志。

curl -u email:password -X PUT -H "Content-type:application/xml" http://host:8080/v1/o/myorg -d \
"<Organization type="trial" name="MyOrganization">
    <Properties>
        <Property name="features.isMonetizationEnabled">true</Property>
        <Property name="MINT.SUMMARY_CUSTOM_ATTRIBUTES">[&quot;my_attribute_1&quot;,&quot;my_attribute_2&quot;]</Property>
        <Property name="features.topLevelDevelopersAreCompanies">false</Property>
    </Properties>
</Organization>"

请注意，API 调用中的自定义属性数组已进行网址编码。

SmartDocs 升级流程

如果您在 Beta 版期间就已在使用 SmartDocs，则需要在开发者门户中升级 SmartDocs，才能使用正式版中的新功能和特性。

在开发者门户中已发布的所有 SmartDocs 页面都将继续正常运行，但您必须先按照更新流程操作，然后才能修改或发布对现有或新页面所做的任何更改。

请注意，虽然您可以在开发者门户中呈现和发布 SmartDocs，但 SmartDocs 是根据 Apigee Edge API 管理服务中 API 模型生成的。您对 Edge 中的 API 模型所做的任何更改都会在您的所有 Pantheon 环境中生效（类似于开发者在 Pantheon 环境中的存在方式）。

如何从 SmartDocs Beta 版升级到正式版

1. 在 Pantheon 上的开发或测试环境中更新并测试 15.05.27 版。
2. 创建一个新模型来替换您一直在使用的任何现有 API 模型。
   • 如果您之前导入了 Swagger 或 WADL 文档，请将其重新导入到新修订版中。
   • 如果您一直在通过 SmartDocs 模块维护 API 模型，请导出为 SmartDocs JSON，然后使用文件附件导入到新模型。
3. 设置模型修订版的安全属性。在内容 > SmartDocs > 模型页面上，选择安全设置。
   
4. 在“模型设置”页面（内容 > SmartDocs）中，点击“操作”列中的设置，查看是否有任何预配置的身份验证。
   
5. 更新所有自定义模板以使用 v6 版 CSS 和 JS 资源，并进行更改以反映所有新对象名称（例如 authSchemes 和 apiSchema）。如需了解如何更新 SmartDocs 模板，请参阅使用 SmartDocs 为 API 编写文档。
6. 重新渲染并发布模型修订版。
7. 验证新文档后，请将生产门户更新为 15.05.27 版。

如果您是 Edge 企业版客户，并且对升级流程有疑问或顾虑，请发送电子邮件至 marsh@apigee.com 和 cnovak@apigee.com。否则，请使用 Apigee 社区，以获得最妥善的回复。

未来的功能变更和增强功能

本部分预览了未来可能发生的功能变更和增强功能：

对 ResponseCache 政策行为的更改

在未来的版本（待定）中，响应缓存政策的 <ExcludeErrorResponse> 元素的默认行为将发生变化。

当前行为：响应缓存政策中的 <ExcludeErrorResponse> 元素默认为 false。这意味着，默认情况下，ResponseCache 政策会缓存具有任何可能 HTTP 状态代码（包括 3xx）的响应。

未来行为：响应缓存政策中的 <ExcludeErrorResponse> 元素将默认设为 true。这意味着，默认情况下，系统只会缓存具有 HTTP 状态代码 200 到 205 的响应。如需替换此行为并缓存所有状态代码的响应，您需要将元素 <ExcludeErrorResponse> 显式设置为 true。

当前的权宜解决方法： 对于私有云 4.15.07.00 及更低版本，如果您想仅缓存状态代码为 200 到 205 的响应，则必须将元素 <ExcludeErrorResponse> 明确设置为 true。

已修复 Bug

此版本中修复了以下 bug。

已知问题

此版本存在以下已知问题。

> source /{install-dir}/apigee4/bin/apigee-env.sh 

> VER=`basename $(find $SHARE_DIR/installer/monetization -name "mint-*.zip") | cut -d "-" -f 2,3,4` 

> sed -i "s/^MONETIZATION_VERSION=.*/MONETIZATION_VERSION=$VER/" /install-dir/apigee4/bin/apigee-env.sh 

> rm /install-dir/apigee4/share/monetization 

************************************** 
In order to complete the monetization upgrade please run: 
sudo /opt/apigee4/share/monetization/schema/migration/MOPDK4.15.04.00/
365-create-notification-condition.sh 
************************************** 

connect.ranges.denied=10.0.0.0/8,192.168.0.0/16,127.0.0.1/32

<install_dir>/apigge4/bin/apigee-service message-processor restart