Configurer un environnement de développement

Cette page explique comment configurer un environnement de développement pour créer et déployer votre API backend à l'aide de l'environnement standard Cloud Endpoints Frameworks pour App Engine. Cette page utilise l'exemple de code squelette de Endpoints Frameworks version 2.0 pour présenter les logiciels et les composants de base dont vous avez besoin pour commencer.

Vous souhaiterez peut-être utiliser les archétypes endpoints-skeleton-archetype ou hello-endpoints-archetype décrits sur la page Utiliser Apache Maven et le plug-in App Engine (basé sur le SDK Cloud) pour créer un projet Endpoints Frameworks version 2.0.

Pour mieux comprendre la procédure nécessaire au déploiement d'un exemple d'API à l'aide de Endpoints Frameworks, consultez le tutoriel Premiers pas avec Endpoints Frameworks pour App Engine.

Avant de commencer

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  2. Dans Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Cloud.

    Accéder à la page de sélection du projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud. Découvrez comment vérifier que la facturation est activée pour votre projet.

  4. Notez l'ID du projet Google Cloud, car vous en aurez besoin ultérieurement.

Installer et configurer les logiciels requis

  1. Si vous n'avez pas encore installé Java 8, téléchargez le kit de développement Java (JDK) sur le site d'Oracle et installez-le.
  2. Installez Maven ou Gradle :

    Maven

    1. Téléchargez Apache Maven version 3.3.9 ou supérieure.
    2. Installez et configurez Maven pour votre environnement de développement local.

    Gradle

  3. Téléchargez et initialisez le SDK Cloud.
  4. Exécutez les commandes suivantes :
    1. Assurez-vous que le SDK Cloud est autorisé à accéder à vos données et services sur Google Cloud :
      gcloud auth login
    2. Utilisez les identifiants par défaut de l'application : 
      gcloud auth application-default login
    3. Installez le composant app-engine-java du SDK Cloud :
      gcloud components install app-engine-java
    4. Installez la dernière version du SDK Cloud et de tous ses composants : 
      gcloud components update
  5. Créez une application App Engine :
    1. Définissez le projet par défaut sur l'ID de votre projet Google Cloud :
      gcloud config set project YOUR_PROJECT_ID

      Remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud. Si vous avez d'autres projets Google Cloud et que vous voulez les gérer à l'aide de gcloud, consultez la page Gérer les configurations du SDK Cloud.

    2. Sélectionnez la région dans laquelle vous souhaitez créer votre application App Engine. Consultez la page Emplacements App Engine pour obtenir une liste des régions.
    3. Créez une application App Engine. Remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud et YOUR_REGION par la région dans laquelle vous souhaitez créer l'application App Engine. 
        gcloud app create \
  --project=YOUR_PROJECT_ID \
  --region=YOUR_REGION

Obtenir l'exemple de squelette Endpoints Frameworks

L'exemple de squelette Endpoints Frameworks version 2.0 contient les scripts de build nécessaires pour Maven et Gradle. Il contient également les fichiers requis pour commencer à créer votre première API.

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

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

  2. Accédez au répertoire contenant l'exemple de squelette Endpoints Frameworks :

     cd java-docs-samples/appengine-java8/endpoints-v2-skeleton/

    L'exemple présente la structure de répertoire suivante :

    Structure de l'exemple de squelette Endpoints Frameworks

    • MyApi.java contient une classe vide que vous pouvez utiliser pour commencer à écrire votre API. Consultez l'exemple Echo afin d'obtenir un exemple de code pour vous aider à démarrer.

    • web.xml est un fichier standard permettant de configurer un servlet.

    • appengine-web.xml définit les informations requises pour déployer l'API dans l'environnement standard App Engine à l'aide de Java 8.

    • pom.xml contient les informations sur le projet et la configuration au moyen desquelles Maven crée le projet et déploie l'API sur App Engine.

    • build.gradle contient les informations sur le projet et la configuration au moyen desquelles Gradle crée le projet et déploie l'API sur App Engine.

Configurer les fichiers de compilation

Cette section décrit les fichiers pom.xml de Maven et build.gradle de Gradle inclus dans l'exemple de code. Les fichiers de compilation sont prêts pour la création de votre API, vous n'avez rien à faire d'autre que de saisir l'ID de votre projet Google Cloud afin qu'il puisse être utilisé dans le nom d'hôte.

À propos de la configuration minimale

Cette section décrit la configuration minimale requise dans votre fichier de construction.

Maven

Dépendances minimales

Vous trouverez ci-dessous les dépendances minimales que doit comporter votre fichier pom.xml pour que vous puissiez commencer :

appengine-java8/endpoints-v2-skeleton/pom.xml
<dependencies>
  <!-- Compile/runtime dependencies -->
  <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.1</version>
  </dependency>
  <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>1.9.82</version>
  </dependency>
  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>3.1.0</version>
    <type>jar</type>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>javax.inject</groupId>
    <artifactId>javax.inject</artifactId>
    <version>1</version>
  </dependency>
</dependencies>

Appliquer des plug-ins

Les plug-ins suivants sont appliqués afin d'être activés :

<build>
  <!-- for hot reload of the web application-->
  <outputDirectory>${project.build.directory}/${project.build.finalName}/WEB-INF/classes</outputDirectory>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-war-plugin</artifactId>
      <version>3.3.1</version>
      <configuration>
        <webResources>
          <resources>
            <directory>${basedir}/src/main/webapp/WEB-INF</directory>
            <filtering>true</filtering>
            <targetPath>WEB-INF</targetPath>
          </resources>
        </webResources>
      </configuration>
    </plugin>
    <plugin>
      <groupId>com.google.cloud.tools</groupId>
      <artifactId>appengine-maven-plugin</artifactId>
      <version>2.4.0</version>
      <configuration>
        <!-- deploy configuration -->
        <projectId>GCLOUD_CONFIG</projectId>
        <version>GCLOUD_CONFIG</version>
      </configuration>
    </plugin>
    <plugin>
      <groupId>com.google.cloud.tools</groupId>
      <artifactId>endpoints-framework-maven-plugin</artifactId>
      <version>2.0.1</version>
      <configuration>
        <!-- plugin configuration -->
        <!--
        You must replace YOUR_PROJECT_ID with your
        Google Cloud Project Id
      -->
      <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
    </configuration>
  </plugin>
</plugins>
</build>
  • Le plug-in maven-war-plugin étend le plug-in java afin de permettre l'assemblage d'une application Web.
  • Le plug-in appengine-maven-plugin est requis pour exécuter l'API sur App Engine.
  • Le plug-in endpoints-framework-maven-plugin fournit des tâches et des configurations permettant de créer des projets Endpoints Frameworks.

Gradle

Dépendances de plug-ins

Les plug-ins nécessaires pour construire votre API sont présentés ci-dessous :

appengine-java8/endpoints-v2-skeleton/build.gradle
buildscript {
  repositories {
    mavenCentral()
  }

  dependencies {
    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.2'
    classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.2.0'
  }
}

Appliquer des plug-ins

Les plug-ins suivants sont appliqués afin d'être activés dans votre script de compilation Gradle :

apply plugin: 'java'
apply plugin: 'war'
apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
apply plugin: 'com.google.cloud.tools.appengine'

  • Le plug-in java ajoute des étapes de compilation et de création propres à Java dans votre projet.
  • Le plug-in war étend le plug-in java afin de permettre l'assemblage d'une application Web.
  • Le plug-in endpoints-framework-server permet la compatibilité côté serveur du plug-in Gradle Endpoints Frameworks.
  • Le plug-in appengine est requis pour exécuter l'API sur App Engine.

Dépendances du projet

Les dépendances suivantes sont utilisées par le projet :

dependencies {
    compile 'com.google.endpoints:endpoints-framework:2.0.9'
    compile 'com.google.appengine:appengine-api-1.0-sdk:1.9.59'

    compile 'javax.inject:javax.inject:1'
    compileOnly 'javax.servlet:javax.servlet-api:3.1.0'
}

Définir le nom d'hôte de votre service

Endpoints Frameworks utilise des noms compatibles avec DNS pour identifier de manière unique les services. Étant donné que les ID de projet Google Cloud sont uniques, vous devez utiliser votre ID de projet Google Cloud dans le nom de service de votre API.

Vous devez ajouter votre ID de projet Google Cloud aux fichiers de compilation pour configurer le nom d'hôte de votre service. Le nom d'hôte doit respecter le format suivant :

YOUR_PROJECT_ID.appspot.com

Lorsque vous déployez l'API sur App Engine, une entrée DNS portant un nom au format YOUR_PROJECT_ID.appspot.com est créée automatiquement. Le nom d'hôte est à la fois le nom du service Cloud Endpoints et le nom de domaine que vous utilisez pour envoyer des requêtes à votre API.

Maven

appengine-java8/endpoints-v2-skeleton/pom.xml
  <plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>endpoints-framework-maven-plugin</artifactId>
    <version>2.0.1</version>
    <configuration>
      <!-- plugin configuration -->
      <!--
      You must replace YOUR_PROJECT_ID with your
      Google Cloud Project Id
    -->
    <hostname>YOUR_PROJECT_ID.appspot.com</hostname>
  </configuration>
</plugin>

Dans le champ hostname, remplacez YOUR_PROJECT_ID par votre ID de projet Google Cloud.

Gradle

appengine-java8/endpoints-v2-skeleton/build.gradle
// You must replace YOUR_PROJECT_ID with your Google Cloud Project Id
def projectId = 'YOUR_PROJECT_ID'

endpointsServer {
  // Endpoints Framework Plugin server-side configuration
  hostname = "${projectId}.appspot.com"
}

Définissez la variable projectID sur votre ID de projet Google Cloud. Par exemple : def projectId = 'example-project-12345'

Configurer le servlet Endpoints

Le servlet Endpoints traite les requêtes entrantes et les transmet au service principal exécuté sur App Engine. Le servlet Endpoints est requis pour que votre API soit gérée par Cloud Endpoints.

Pour en savoir plus sur le fichier web.xml, consultez la page Descripteur de déploiement : web.xml.

appengine-java8/endpoints-v2-skeleton/src/main/webapp/WEB-INF/web.xml
<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <!-- Wrap the backend with Endpoints Frameworks v2. -->
    <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.skeleton.MyApi</param-value>
        </init-param>
    </servlet>
    <!-- Route API method requests to the backend. -->
    <servlet-mapping>
        <servlet-name>EndpointsServlet</servlet-name>
        <url-pattern>/_ah/api/*</url-pattern>
    </servlet-mapping>
</web-app>

Configurer votre déploiement App Engine

Le fichier appengine-web.xml permet de définir la configuration de l'environnement standard App Engine lors du déploiement de l'API. Pour en savoir plus, consultez la page Documentation de référence sur appengine-web.xml.

appengine-java8/endpoints-v2-skeleton/src/main/webapp/WEB-INF/appengine-web.xml
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
    <runtime>java8</runtime>
    <threadsafe>true</threadsafe>

    <system-properties>
        <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
    </system-properties>
</appengine-web-app>

Étapes suivantes