遷移至 App Engine 適用的 Cloud Endpoints Frameworks 2.0 版

本頁面說明如何使用 Java，將現有的 Cloud Endpoints 1.0 版應用程式遷移至 App Engine 適用的 Endpoints Frameworks。

優點

新架構能發揮許多優點，包括：

  • 縮短要求的延遲時間。
  • 更能與 App Engine 功能完善整合 (例如自訂網域)。
  • 正式支援 Guice 設定。
  • 新的 API 管理功能 (可選)。

Endpoints Frameworks 2.0 版不影響 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 版適用的 Android Studio 支援目前不支援 2.0 版

遷移至 Endpoints Frameworks 2.0 版

Endpoints Frameworks 2.0 版已遷移至 com.google.endpoints 群組中的 Maven 構件。基本所需的 JAR 位於 endpoints-framework 構件中。如果您想要使用 Guice 設定，請新增 endpoints-framework-guice 構件。

以下提供示例，說明如何使用「探索文件」從 Endpoints Frameworks 1.0 版遷移至 Endpoints Frameworks 2.0 版：

  1. 下載並初始化 Google Cloud CLI。
  2. 執行下列指令：
    1. 確認 gcloud CLI 已獲授權，可在 Google Cloud上存取您的資料與服務：
      gcloud auth login
    2. 使用應用程式預設憑證：
      gcloud auth application-default login
    3. 安裝 Google Cloud SDK app-engine-java 元件： 
      gcloud components install app-engine-java
    4. 將 Google Cloud SDK 和所有元件更新至最新版本：
      gcloud components update

使用 Maven 或 Gradle 進行遷移

Maven

  1. 移除舊版的相依項目，即 appengine-endpoints 構件： 
    <dependency>
      <groupId>com.google.appengine</groupId>
      <artifactId>appengine-endpoints</artifactId>
      <version>1.9.53</version>
</dependency>
  2. 新增新的 Endpoints Frameworks 相依項目： 
    <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.1</version>
</dependency>
  3. 新增 Endpoints Frameworks 外掛程式，並定義生成之探索文件的主機名稱： 
    <plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>endpoints-framework-maven-plugin</artifactId>
    <version>1.0.2</version>
    <configuration>
        <!-- plugin configuration -->
        <hostname>YOUR-PROJECT-ID.appspot.com</hostname>
    </configuration>
</plugin>
  4. 新增 App Engine Maven 外掛程式： 
    <plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>appengine-maven-plugin</artifactId>
    <version>1.3.2</version>
    <configuration>
        <!-- deploy configuration -->
    </configuration>
</plugin>
  5. 更新專案 web.xml 檔案中的 API 進入點：
    • 將所有出現的 SystemServiceServlet 重新命名為 EndpointsServlet
    • 將所有出現的 /_ah/spi/ 路徑替換成「新的必要 /_ah/api/ 路徑」

    以下顯示遷移之前與之後的 web.xml 內容：

    遷移之前

    Endpoints Frameworks 1.0 版 web.xml： 
    <servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

    遷移之後

    Endpoints Frameworks 2.0 版 web.xml： 
    <servlet>
    <servlet-name>EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

  6. 修改相依項目之後，請清理專案：
    mvn clean
  7. 您可以產生導覽文件：
    mvn endpoints-framework:discoveryDocs
     進一步瞭解 Maven Endpoints Frameworks 的外掛程式目標。
  8. 您可以部署專案：
    mvn appengine:deploy

    進一步瞭解 Maven App Engine 的外掛程式目標。

Gradle

  1. 移除舊版的相依項目，即 appengine-endpoints 構件：
    compile group: 'com.google.appengine', name: 'appengine-endpoints', version: '+'
  2. 新增新的 Endpoints Frameworks 相依項目： 
    compile group: 'com.google.endpoints', name: 'endpoints-framework', version: '2.0.8'
  3. 新增新的 App Engine 和 Endpoints Frameworks 外掛程式： 
    buildscript {    // Configuration for building
  repositories {
    mavenCentral()
    jcenter()    // Bintray's repository - a fast Maven Central mirror & more
  }
  dependencies {
    // App Engine Gradle plugin
    classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.3.3'

    // Endpoints Frameworks Gradle plugin
    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
  }
}
  4. 使用新的 App Engine 和 Endpoints Frameworks 外掛程式： 
    apply plugin: 'com.google.cloud.tools.appengine'
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
  5. 為生成的探索文件定義主機名稱端點： 
    endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "YOUR-PROJECT-ID.appspot.com"
}
  6. 更新專案 web.xml 檔案中的 API 進入點：
    • 將所有出現的 SystemServiceServlet 重新命名為 EndpointsServlet
    • 將所有出現的 /_ah/spi/ 路徑替換成「新的必要 /_ah/api/ 路徑」

    以下顯示遷移之前與之後的 web.xml 內容：

    遷移之前

    Endpoints Frameworks 1.0 版 web.xml： 
    <servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
</servlet-mapping>

    遷移之後

    Endpoints Frameworks 2.0 版 web.xml： 
    <servlet>
    <servlet-name>EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.helloendpoints.Greetings</param-value>
    </init-param>
    <init-param>
        <param-name>restricted</param-name>
        <param-value>false</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
</servlet-mapping>

  7. 修改相依項目之後，使用以下方法清理專案：
    gradle clean
  8. 您可以使用以下方法產生導覽文件：
    gradle endpointsDiscoveryDocs
     進一步瞭解 Gradle Endpoints Frameworks 的外掛程式工作
  9. 您可以使用以下方法部署專案： 
    gradle appengineDeploy

    進一步瞭解 Gradle App Engine 的外掛程式工作。

使用 Guice 設定 Java 的 Endpoints Frameworks

若要使用 Guice：

  1. 加入新的 Endpoints Frameworks Guice 依附元件：

    Maven

    <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework-guice</artifactId>
    <version>2.2.1</version>
</dependency>

    Gradle

    compile 'com.google.endpoints:endpoints-framework-guice:2.0.9'
  2. 宣告一個擴充 EndpointsModule 的新模組，並對其進行設定，如下所示： 
    public class EchoEndpointModule extends EndpointsModule {
  @Override
  public void configureServlets() {
    super.configureServlets();

    bind(ServiceManagementConfigFilter.class).in(Singleton.class);
    filter("/_ah/api/*").through(ServiceManagementConfigFilter.class);

    Map<String, String> apiController = new HashMap<String, String>();
    apiController.put("endpoints.projectId", "YOUR-PROJECT-ID");
    apiController.put("endpoints.serviceName", "YOUR-PROJECT-ID.appspot.com");

    bind(GoogleAppEngineControlFilter.class).in(Singleton.class);
    filter("/_ah/api/*").through(GoogleAppEngineControlFilter.class, apiController);

    bind(Echo.class).toInstance(new Echo());
    configureEndpoints("/_ah/api/*", ImmutableList.of(Echo.class));
  }
}

驗證新的部署

您可以執行以下方法，驗證新的框架是否正在提供流量：

  1. 傳送一些要求到新的部署。

  2. 前往 Google Cloud 控制台的「Logging」 >「Logs Explorer」頁面。

    前往「Logs Explorer」(記錄檔探索工具) 頁面

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

新增 Endpoints API 管理

Endpoints Frameworks 2.0 版也可讓您開啟 API 管理功能，其中包括：

  • API 金鑰管理
  • API 共用
  • 使用者驗證
  • API 指標
  • API 記錄

如要開始使用這些功能，請參閱新增 API 管理一文。

疑難排解

本節說明遷移到 Endpoints Frameworks 2.0 版時系統常有的不穩定反應，以及建議的解決方案。

API 傳回 404錯誤，但是 API Explorer 仍正確地列出 API

遷移至 Endpoints Frameworks 2.0 版本時，您需要刪除舊的 Endpoints Frameworks 1.0 版本設定。如果舊的設定仍存於應用程式的設定中，則 Endpoints 服務會繼續把應用程式視為 1.0 版本。您可能會看到 App Engine 記錄檔中的要求被傳送至 /_ah/spi，這會導致將 HTTP 404 錯誤發送至用戶端。

  1. 如果 web.xml 檔案中存在下列各行，請將其移除：

    <servlet>
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-