遷移到 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 連結)
  • 針對產生的用戶端的用戶端程式庫支援
  • CORS (適用於不使用 Google JavaScript 用戶端程式庫的 JavaScript 呼叫端)
  • API 瀏覽器

流量拆分功能已無法使用。

目前排除的功能

下列功能已無法使用。如果您需要下列任一項功能，請提交功能要求。

  • 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 路徑中。例如，API 呼叫含有版本 2.1.0 的 echo 時，路徑會類似於 /echo/v2。如果將您的 echo API 更新為版本 2.2.0，並部署具回溯相容性的變更，路徑仍然為 /echo/v2。這樣一來，您可以在進行具回溯相容性的變更時更新 API 版本編號，而不會破壞用戶端的現有路徑。但如果您將 echo API 更新為 3.0.0 版 (因為您要部署破壞性變更)，路徑就會變更為 /echo/v3。

  8. 重新部署 Endpoints Frameworks 應用程式。

驗證新的部署

如要驗證新的架構是否正在提供流量：

  1. 傳送一些要求到新的部署。
  2. 前往專案的 Cloud Logging 頁面。

    前往「Logs Explorer」頁面

  3. 如果要求顯示的路徑以 /_ah/api 做為開頭，則 Endpoints Frameworks 2.0 版現在正為您的 API 提供流量。記錄不應顯示任何以 /_ah/spi 做為路徑開頭的要求，這些要求指出 Endpoints 1.0 版 proxy 仍在處理要求。

新增 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 版時，您需要移除舊的 Endpoints 1.0 版設定。如果舊的設定仍存在於應用程式設定中，則 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 程式庫版本，就會發生這個錯誤。請參閱已知問題。