將 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 來產生探索文件。

此版本指令碼使用的是用戶端外掛程式 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

部署後端模組

目前是使用新的 Gradle App Engine Plugin，以 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 說明。