Migrer des projets Android vers Cloud Endpoints Frameworks 2.0

Cette page décrit la migration d'une application Android Cloud Endpoints version 1.0 existante vers Endpoints Frameworks pour App Engine. Notez que cette page fait référence à Endpoints version 1.0 en tant qu'Endpoints Frameworks version 1.0, et au nouveau framework Endpoints Frameworks pour App Engine en tant qu'Endpoints Frameworks version 2.0.

Avantages

Le nouveau framework présente de nombreux avantages, par exemple :

  • Latence réduite des requêtes
  • Meilleure intégration aux fonctionnalités d'App Engine, telles que les domaines personnalisés
  • Compatibilité officielle avec les configurations Guice
  • En option, de nouvelles fonctionnalités de gestion de l'API

Endpoints Frameworks version 2.0 n'a aucune incidence sur les interfaces avec votre API. Les clients existants continuent de fonctionner après la migration sans aucune modification du code côté client.

Migrer des projets multimodules Android vers Endpoints Frameworks version 2.0

Les étapes suivantes vous guident lors du passage de projets Android Studio d'Endpoints Frameworks version 1.0 à Endpoints Frameworks version 2.0. Ici, nous migrons un projet Android Studio avec un module Endpoints.

Liste de tâches

Reportez-vous à la liste détaillée des tâches présentée ci-dessous tout au long du tutoriel. Dans ce guide de migration, nous supposons que vous disposez d'un projet Android utilisant un module Google Cloud.

  1. Avant de commencer
  2. Configurez la Google Cloud CLI.
  3. Facultatif : Télécharger l'exemple de code
  4. Effectuer la migration vers Endpoints Frameworks version 2.0
  5. Déployer votre module backend
  6. Générer des bibliothèques clientes

Avant de commencer

  1. Installez Android Studio.
  2. Installez le SDK Android 26+.
  3. Installer gcloud CLI

Configurer la CLI gcloud

Pour configurer la gcloud CLI:

  1. Initialisez la gcloud CLI :

     gcloud init

  2. Utilisez les identifiants par défaut de l'application :

     gcloud auth application-default login

  3. Installez le composant app-engine-java :

     gcloud components install app-engine-java

Facultatif : Télécharger l'exemple de code

Pour cloner les exemples de projets legacy et v2 à partir de GitHub, procédez comme suit :

  1. Clonez l'exemple de dépôt sur votre ordinateur local :

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

  2. Accédez au répertoire contenant l'exemple de code pour legacy et v2 :

     cd android-docs-samples/endpoints-frameworks/

Effectuer la migration vers Endpoints Frameworks version 2.0

Mettre à jour le fichier build.gradle

Les dépendances Endpoints Frameworks version 2.0 utilisent Guava 19, et le plug-in de compilation Android Gradle com.android.tools.build:gradle:2.3.3 utilise Guava 18. Ajoutez Guava 19 à la fermeture des dépendances de script de compilation de build.gradle pour remplacer cette dépendance transitive.

Ancienne

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'
    }
}

Mettre à jour le fichier app/build.gradle

Dans Endpoints version 1.0, vous avez généré un document de découverte d'API à l'aide du plug-in Gradle (gradle-appengine-plugin). Dans Endpoints Frameworks version 2.0, vous le générez au moyen du plug-in endpoints-framework-gradle-plugin.

Ce script de compilation utilise le plug-in côté client com.google.cloud.tools.endpoints-framework-client.

Ancienne

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'
}

Mettre à jour le fichier backend/build.gradle

Les outils Gradle de l'environnement standard App Engine ont été mis à jour. Les projets Endpoints Frameworks version 1.0 utilisaient le plug-in gradle-appengine-plugin fourni dans com.google.appengine, tandis que les projets Endpoints Frameworks version 2.0 utilisent appengine-gradle-plugin.

Ce script de compilation utilise le plug-in côté serveur com.google.cloud.tools.endpoints-framework-server.

Ancienne

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)
        }
    }
}

Mettre à jour le fichier web.xml

Dans Endpoints Frameworks version 2.0, la classe de servlet est passée de SystemServiceServlet à EndpointsServlet.

Le format d'URL est passé de /_ah/spi/* à /_ah/api/*.

Ancienne

<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>

Recréez le projet

Enfin, utilisez la liste de compilation d'Android Studio pour nettoyer et recompiler le projet Android Studio avec les nouvelles dépendances.

Reconstruction dans Android Studio

Déployer votre module backend

Le nouveau plug-in Gradle App Engine Plugin est maintenant utilisé pour déployer le module backend à l'aide de la tâche Gradle suivante dans le module backend :

gradle appengineDeploy

Générer des bibliothèques clientes

Pour générer des bibliothèques clientes, utilisez la tâche Gradle suivante dans le module backend, procédez comme suit :

gradle endpointsClientLibs

Obtenez plus d'informations sur les tâches disponibles pour le plug-in Gradle Endpoint Frameworks.

Ajouter la gestion des API Endpoints

Endpoints Frameworks version 2.0 vous permet également d'activer les fonctionnalités de gestion des API, par exemple :

  • Gestion des clés API
  • Partage de l'API
  • Authentification des utilisateurs
  • Métriques de l'API
  • Journaux de l'API

Pour vous familiariser avec ces fonctionnalités et d'autres fonctionnalités de Cloud Endpoints Frameworks 2.0, consultez la page Java concernant Endpoints Frameworks pour App Engine.