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 pas d'incidence sur les interfaces avec l'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. Configurer le SDK Cloud
  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. Installez le SDK Cloud.

Configurer le SDK Cloud

Pour configurer le SDK Cloud :

  1. Initialisez le SDK Cloud :

     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.

Ancien

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

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

Ancien

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

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

Ancien

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

Projets 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/*.

Anciens projets

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

Projets 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éer 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 Endpoints 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.