迁移到 Cloud Endpoints Frameworks 2.0

Cloud Endpoints Frameworks 以前称为 Endpoints。为了区分这两个版本，本页的 Endpoints Frameworks 2.0 是指新版本，而 Endpoints 1.0 是指旧版。本页面介绍如何将 Cloud Endpoints 1.0 应用迁移到 Endpoints Frameworks 2.0。 此迁移包括库更改和应用配置更改，但您不必对代码做任何更改。

优势

Endpoints 2.0 具有诸多优势，具体如下所示：

  • 缩短了请求延迟时间。
  • 可更好地与 App Engine 功能（例如自定义网域）集成。
  • 提供多种新的 API 管理功能。

Endpoints Frameworks 2.0 不会影响 API 的接口。迁移后，现有客户端仍可继续运行，且无需更改任何客户端代码。

功能概览

下列功能向后兼容 Endpoints 1.0：

  • JSON-REST 协议，可供所有 Google 客户端库使用。
  • 发现服务
  • 所有现有的身份验证功能 (OAuth2/OpenID Connect)
  • 对所生成客户端的客户端库支持
  • CORS（适用于不使用 Google JavaScript 客户端库的 JavaScript 调用者）
  • API Explorer

流量拆分功能无法使用。

目前不包含的功能

以下功能无法使用。如果您需要使用其中任何功能，请提交功能请求。

  • JSON-RPC 协议，这是旧版 iOS 客户端所需的功能。要为您的 Endpoints Frameworks 2.0 API 创建 iOS 客户端，我们建议您使用适用于 REST API 的 Google API Objective-C 客户端库。
  • 自动 ETag
  • 自动 kind 字段
  • IDE 集成
  • fields 部分响应
  • 自动创建 PATCH API 方法

从 Endpoints 1.0 版迁移

要从 1.0 版迁移，请执行以下操作：

  1. 在应用的主目录中创建名为 /lib 的子文件夹。

  2. 从应用的主目录安装库：

     pip install -t lib google-endpoints --ignore-installed

  3. 从应用的 app.yaml 文件的 libraries 部分下移除条目 - name: endpoints 和 version 1.0。例如：

    libraries:
- name: endpoints   #Remove
  version: 1.0      #Remove

  4. 在 app.yaml 文件的 libraries 部分，添加以下内容：

    libraries:
- name: pycrypto
  version: 2.6
- name: ssl
  version: 2.7.11

    Endpoints Frameworks 需要上述版本的 pycrypto 和 ssl 库。

  5. 在 app.yaml 文件的 handlers 部分，将 url 指令从 - url: /_ah/spi/.* 改为 - url: /_ah/api/.*。

  6. 在应用的根目录中，创建或修改文件 appengine_config.py，以包含以下内容：

    from google.appengine.ext import vendor

vendor.add('lib')

  7. 检查您的 API 版本字符串。您的版本字符串（在 @endpoints.api(version='v1', ...) 修饰器中指定）出现在您的 API 路径中。如果您指定的版本字符串与 SemVer 标准兼容，则在部署您的 API 时，只有主要版本号会显示在该 API 的路径中。例如，一个名为 echo 且版本为 2.1.0 的 API 将具有 /echo/v2 这样的路径。如果您将 echo API 更新到版本 2.2.0 并部署向后兼容的更改，则路径仍为 /echo/v2。这样一来，您可以在进行向后兼容的更改时更新 API 版本号，而不会破坏客户端的现有路径。 但是，如果您将 echo API 更新到版本 3.0.0（因为要部署重大更改），路径将更改为 /echo/v3。

  8. 重新部署您的 Endpoints Frameworks 应用。

验证新的部署

要验证新框架是否正在处理流量，请执行以下操作：

  1. 向新部署发送一些请求。
  2. 访问项目的 Stackdriver Logging 页面。

    转到“日志浏览器”页面

  3. 如果其中显示的请求包含以 /_ah/api 开头的路径，则说明 Endpoints Frameworks 2.0 当前正在为您的 API 提供服务。日志不应显示任何路径以 /_ah/spi 开头的请求。这些请求表明 Endpoints 1.0 代理仍在处理请求。

添加 API 管理

使用 Endpoints Frameworks 2.0 可以添加 API 管理功能，其中包括：

  • API 密钥管理
  • API 共享
  • 用户身份验证
  • API 指标
  • API 日志

如需开始使用，请参阅 Python 版 Endpoints Frameworks 使用入门页面。

问题排查

本部分介绍迁移到 Endpoints Frameworks 2.0 时一些常见的异常行为以及建议的解决方案。

API 返回 404 错误，但 API Explorer 仍会正确列出 API

迁移到 Endpoints Frameworks 2.0 时，您需要移除旧版 1.0 Endpoints 配置。如果应用配置中仍然存在旧版配置，则 Endpoints 服务会继续将该应用视为 1.0 版应用。您可能会在 App Engine 日志中看到发送到 /_ah/spi 的请求，这些请求会导致系统向客户端发送 HTTP 404 错误。

  1. 如果文件 app.yaml 中存在以下行，请将其移除：

    handlers:
- url: /_ah/spi/.*
  script: ...

  2. 确保 app.yaml 文件中的 handlers 部分具有正确的路径：

    handlers:
# The endpoints handler must be mapped to /_ah/api.
- url: /_ah/api/.*
  script: ...

错误消息：ImportError: cannot import name locked_file

如果您的依赖项包含与 App Engine 不兼容的 oauth2client 库版本，就会出现此错误消息。请参阅已知问题。