将 Android 项目迁移至 Cloud Endpoints Frameworks 2.0

本页面介绍如何将现有 Android Cloud Endpoints 1.0 版应用迁移至适用于 App Engine 的 Endpoints Frameworks。 请注意，在本页中，Endpoints 1.0 版是指 Endpoints Frameworks 1.0 版，适用于 App Engine 的新版 Endpoints Frameworks 是指 Endpoints Frameworks 2.0 版。

优势

新版框架具有诸多优势，具体如下所示：

  • 缩短了请求延迟时间
  • 可更好地与 App Engine 功能（例如自定义域名）集成
  • 提供对 Guice 配置的官方支持
  • 提供多种新的 API 管理功能供您选择

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

将 Android 多模块项目迁移至 Endpoints Frameworks 2.0 版

以下步骤将引导您执行将 Android Studio Endpoints Frameworks 1.0 项目移至 Endpoints Frameworks 2.0 的操作。该指南将迁移使用 Endpoints 模块的 Android Studio 项目。

任务列表

学习本迁移指南时，请使用以下概要任务列表。此迁移指南假定您现在已有使用 Google Cloud 模块的 Android 项目。

  1. 准备工作。
  2. 设置 Google Cloud CLI。
  3. 可选：下载示例代码。
  4. 迁移到 Endpoints Frameworks 2.0。
  5. 部署您的后端模块。
  6. 生成客户端库。

准备工作

  1. 安装 Android Studio。
  2. 安装 Android SDK 26+。
  3. 安装 gcloud CLI。

设置 gcloud CLI

如需设置 gcloud CLI，请执行以下操作：

  1. 初始化 gcloud CLI：

     gcloud init

  2. 使用应用默认凭据：

     gcloud auth application-default login

  3. 安装 app-engine-java 组件：

     gcloud components install app-engine-java

可选：下载示例代码

如需从 GitHub 克隆 legacy 和 v2 示例项目，请执行以下操作：

  1. 将示例代码库克隆到您的本地机器：

     git clone https://github.com/GoogleCloudPlatform/android-docs-samples

  2. 切换到包含 legacy 和 v2 的示例代码的目录：

     cd android-docs-samples/endpoints-frameworks/

迁移到 Endpoints Frameworks 2.0 版

更新 build.gradle 文件：

Endpoints Frameworks 2.0 版依赖项使用 Guava 19，而 Android Gradle 构建插件 com.android.tools.build:gradle:2.3.3 使用 Guava 18。将 Guava 19 添加到 build.gradle 的构建脚本依赖项闭包可替换此传递依赖项。

旧版

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:2.3.3'
    }
}

v2

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        // V2: Include this dependency when using Endpoints Framework v2
        classpath 'com.google.guava:guava:19.0'

        classpath 'com.android.tools.build:gradle:2.3.3'
    }
}

更新 app/build.gradle 文件

在 Endpoints 1.0 版中，您使用 Gradle 插件 gradle-appengine-plugin 来生成 API 发现文档。在 Endpoints Frameworks 2.0 版中，您使用 endpoints-framework-gradle-plugin 来生成 Discovery 文档。

此构建脚本使用客户端插件 com.google.cloud.tools.endpoints-framework-client。

旧版

apply plugin: 'com.android.application'

android {
    compileSdkVersion 26
    buildToolsVersion '26.0.1'
    defaultConfig {
        applicationId 'com.example.migration.endpoints.app'
        minSdkVersion 25
        targetSdkVersion 26
        versionCode 1
        versionName '1.0'
        testInstrumentationRunner 'android.support.test.runner.AndroidJUnitRunner'
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    configurations.all {
        resolutionStrategy.force 'com.google.code.findbugs:jsr305:2.0.1'
    }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])

    // androidTestCompile compiles instrumentation tests written using Espresso
    // used by Firebase Test Lab
    androidTestCompile('com.android.support.test.espresso:espresso-core:2.2.2', {
        exclude group: 'com.android.support', module: 'support-annotations'
    })

    compile 'com.android.support:appcompat-v7:26.+'
    compile 'com.android.support.constraint:constraint-layout:1.0.1'
    compile 'com.google.code.findbugs:jsr305:2.0.1'
    compile 'com.google.http-client:google-http-client-android:1.22.0'
    compile 'com.google.api-client:google-api-client:+'
    testCompile 'junit:junit:4.12'

    // LEGACY: Legacy compile :backend project
    compile project(path: ':backend', configuration: 'android-endpoints')
}

v2

apply plugin: 'com.android.application'

// V2: Apply the new Endpoints Framework client plugin
apply plugin: 'com.google.cloud.tools.endpoints-framework-client'

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        // V2: Add the new Endpoints Framework plugin dependencies
        classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
    }
}

android {
    compileSdkVersion 26
    buildToolsVersion '26.0.1'
    defaultConfig {
        applicationId 'com.example.migration.endpoints.app'
        minSdkVersion 25
        targetSdkVersion 26
        versionCode 1
        versionName '1.0'
        testInstrumentationRunner 'android.support.test.runner.AndroidJUnitRunner'
    }

    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    configurations.all {
        resolutionStrategy.force 'com.google.code.findbugs:jsr305:2.0.1'
    }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])

    // androidTestCompile compiles instrumentation tests written using Espresso
    // used by Firebase Test Lab
    androidTestCompile('com.android.support.test.espresso:espresso-core:2.2.2', {
        exclude group: 'com.android.support', module: 'support-annotations'
    })

    compile 'com.android.support:appcompat-v7:26.+'
    compile 'com.android.support.constraint:constraint-layout:1.0.1'
    compile 'com.google.code.findbugs:jsr305:2.0.1'
    testCompile 'junit:junit:4.12'

    // V2: Endpoints Framework v2 migration
    endpointsServer project(path: ':backend', configuration: 'endpoints')
    compile 'com.google.api-client:google-api-client:+'
    compile 'com.google.http-client:google-http-client-android:1.22.0'
}

更新 backend/build.gradle 文件

App Engine 标准环境 Gradle 工具已更新。在 Endpoints Frameworks 版本 1.0 版中，项目使用 com.google.appengine 中的 gradle-appengine-plugin，而在 Endpoints Frameworks 2.0 版中，项目使用 appengine-gradle-plugin。

此构建脚本使用服务器端插件 com.google.cloud.tools.endpoints-framework-server。

旧版

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        // LEGACY: Deprecated App Engine plugin dependency
        classpath 'com.google.appengine:gradle-appengine-plugin:1.9.59'
    }
}

repositories {
    jcenter();
}

apply plugin: 'java'
apply plugin: 'war'

// LEGACY: Deprecated Apply App Engine plugin dependency
apply plugin: 'appengine'

sourceCompatibility = JavaVersion.VERSION_1_7
targetCompatibility = JavaVersion.VERSION_1_7

dependencies {
    // LEGACY: Deprecated App Engine plugin dependency
    appengineSdk 'com.google.appengine:appengine-java-sdk:1.9.59'

    // LEGACY: Legacy Endpoints Framework dependencies
    compile 'com.google.appengine:appengine-endpoints:1.9.59'
    compile 'com.google.appengine:appengine-endpoints-deps:1.9.59'

    compile 'javax.servlet:servlet-api:2.5'
}

appengine { // LEGACY: Deprecated App Engine plugin Tasks configuration
    downloadSdk = true
    appcfg {
        oauth2 = true

        // extraOptions is used for acceptance test and
        // is not required.
        def application = findProperty("appengine.deploy.application")
        def version = findProperty("appengine.deploy.version")
        def serviceAccount = findProperty("appengine.deploy.serviceAccount")

        extraOptions = ["--application=" + application, "--version=" + version,
            '--service_account_json_key_file=' + serviceAccount]
    }
    endpoints {
        getClientLibsOnBuild = true
        getDiscoveryDocsOnBuild = true
    }
}

v2

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        // V2: Add the new App Engine and Endpoints Frameworks plugin dependencies
        classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
        classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.3.3'
    }
}

repositories {
    jcenter();
}

apply plugin: 'java'
apply plugin: 'war'

// V2: Apply new App Engine and Endpoints Framework server plugins
apply plugin: 'com.google.cloud.tools.appengine'
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'

sourceCompatibility = JavaVersion.VERSION_1_7
targetCompatibility = JavaVersion.VERSION_1_7

dependencies {
    // V2: Endpoints Framework v2 migration
    compile 'com.google.endpoints:endpoints-framework:2.0.9'
    compile 'javax.inject:javax.inject:1'

    compile 'javax.servlet:servlet-api:2.5'
}

// V2: Define deployment configuration using the new App Engine plugin
// with the appengine closure
appengine {  // App Engine tasks configuration
    deploy {   // deploy configuration

        // The following is used for acceptance tests and
        // is not required for a migration.
        project = findProperty("appengine.deploy.project")
        version = findProperty("appengine.deploy.version")
        def promoteProp = findProperty("appengine.deploy.promote")
        if (promoteProp != null) {
            promote = new Boolean(promoteProp)
        }
    }
}

更新 web.xml 文件

在 Endpoints Frameworks 2.0 版中，servlet 类已从 SystemServiceServlet 更改为 EndpointsServlet。

网址格式已从 /_ah/spi/* 更新为 /_ah/api/*。

旧版

<servlet>
    <!-- LEGACY: Start of Legacy section -->
    <servlet-name>SystemServiceServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
    <!-- LEGACY: End of Legacy section -->
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.migration.endpoints.backend.MyEndpoint</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <!-- LEGACY: Start of legacy section -->
    <servlet-name>SystemServiceServlet</servlet-name>
    <url-pattern>/_ah/spi/*</url-pattern>
    <!-- LEGACY: End of legacy section -->
</servlet-mapping>

v2

<servlet>
    <!-- V2: Start of v2 section -->
    <servlet-name>EndpointsServlet</servlet-name>
    <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
    <!-- V2: End of v2 section -->
    <init-param>
        <param-name>services</param-name>
        <param-value>com.example.migration.endpoints.backend.MyEndpoint</param-value>
    </init-param>
</servlet>
<servlet-mapping>
    <!-- V2: Start of v2 section -->
    <servlet-name>EndpointsServlet</servlet-name>
    <url-pattern>/_ah/api/*</url-pattern>
    <!-- V2: End of v2 section -->
</servlet-mapping>

重建项目

最后，使用 Android Studio 构建列表清理并重建具有新依赖项的 Android Studio 项目。

Android Studio Rebuild

部署您的后端模块

现在，使用全新的 Gradle App Engine 插件，您可以在 backend 模块中使用以下 Gradle 任务部署后端模块：

gradle appengineDeploy

生成客户端库

要生成客户端库，请在 backend 模块中使用以下 Gradle 任务：

gradle endpointsClientLibs

详细了解 Endpoints Frameworks Gradle 插件提供的任务。

添加 Endpoints API 管理

使用 Endpoints Frameworks 2.0，您还可以开启 API 管理功能，其中包括：

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

要开始使用上述功能和其他 Cloud Endpoints Frameworks 2.0 功能，请转到 Java 页面中的适用于 App Engine 的 Endpoints Frameworks。