Configurer un environnement de développement

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

Vous pouvez utiliser le endpoints-skeleton-archetype ou le hello-endpoints-archetype décrit dans la section Utiliser Apache Maven et le plug-in App Engine (basé sur la CLI Google Cloud) pour créer un projet Endpoints Frameworks version 2.0.

Pour mieux comprendre les étapes requises pour déployer un exemple d'API à l'aide de Endpoints Frameworks, consultez le tutoriel Premiers pas avec Endpoints Frameworks sur App Engine.

Avant de commencer

  1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

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

    Accéder au sélecteur de projet

  3. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

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

    Accéder au sélecteur de projet

  5. Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.

  6. 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 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 ultérieure.
    2. Installez et configurez Maven pour votre environnement de développement local.

    Gradle

  3. Téléchargez et initialisez la CLI Google Cloud.
  4. Exécutez les commandes suivantes :
    1. Assurez-vous que la CLI gcloud est autorisée à 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 Google Cloud: 
      gcloud components install app-engine-java
    4. Installez la dernière version du SDK Google Cloud et de tous les composants: 
      gcloud components update
  5. Créez une application App Engine :
    1. Définissez le projet par défaut sur votre ID de 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 souhaitez les gérer à l'aide de gcloud, consultez la page Gérer les configurations de CLI gcloud.

    2. Sélectionnez la région dans laquelle vous souhaitez créer votre application App Engine. Consultez la page Emplacements App Engine pour obtenir la liste des régions.
    3. Créer 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 le squelette Endpoints Frameworks

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

  1. Clonez l'exemple de dépôt 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épertoires suivante:

    Exemple de mise en page de squelette Endpoints Frameworks

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

    • web.xml est un fichier standard utilisé pour 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 de projet et de configuration utilisées par Maven pour créer le projet et déployer l'API sur App Engine.

    • build.gradle contient les informations de projet et de configuration utilisées par Gradle pour créer le projet et déployer l'API sur App Engine.

Configurer les fichiers de compilation

Cette section décrit les fichiers Maven pom.xml et Gradle build.gradle inclus dans l'exemple de code. Les fichiers de compilation sont prêts à être utilisés pour la création de votre API, sauf lorsque vous saisissez 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 compilation.

Maven

Dépendances minimales

Vous trouverez ci-dessous la liste des dépendances minimales requises dans votre fichier pom.xml pour commencer:

appengine-java8/endpoints-v2-autrement dit/pom.xml 
<dependencies>
  <!-- Compile/runtime dependencies -->
  <dependency>
    <groupId>com.google.endpoints</groupId>
    <artifactId>endpoints-framework</artifactId>
    <version>2.2.2</version>
  </dependency>
  <dependency>
    <groupId>com.google.appengine</groupId>
    <artifactId>appengine-api-1.0-sdk</artifactId>
    <version>2.0.3</version>
  </dependency>
  <dependency>
    <groupId>javax.servlet</groupId>
    <artifactId>javax.servlet-api</artifactId>
    <version>4.0.1</version>
    <type>jar</type>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>javax.inject</groupId>
    <artifactId>javax.inject</artifactId>
    <version>1</version>
  </dependency>
</dependencies>

  • La dépendance endpoints-framework contient les classes nécessaires pour créer votre API.
  • Vous avez besoin de la fonctionnalité, qui effectue le suivi des tâches suivantes :
  • Le package javax.servlet standard est requis pour créer un servlet.
  • Le package javax.inject standard est requis pour l'injection de dépendances.

Appliquer des plug-ins

Les plug-ins suivants sont appliqués pour les activer:

<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.2</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.1</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.1.0</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 appengine-maven-plugin est requis pour exécuter l'API sur App Engine.
  • Le endpoints-framework-maven-plugin fournit des tâches et des configurations permettant de créer des projets Endpoints Frameworks.

Gradle

Dépendances des plug-ins

Voici les plug-ins requis pour créer votre API:

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

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

Appliquer des plug-ins

Les plug-ins suivants sont appliqués pour les activer 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 compilation spécifiques à Java pour 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 fournit une assistance côté serveur au 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.2.2'
    compile 'com.google.appengine:appengine-api-1.0-sdk:2.0.3'

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

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

Endpoints Frameworks utilise des noms compatibles avec DNS pour identifier les services de manière unique. É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 l'ID de votre 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-autrement dit/pom.xml 
  <plugin>
    <groupId>com.google.cloud.tools</groupId>
    <artifactId>endpoints-framework-maven-plugin</artifactId>
    <version>2.1.0</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 l'ID de votre projet Google Cloud.

Gradle

appengine-java8/endpoints-v2-autrement dit/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 l'ID de votre projet Google Cloud. Par exemple, def projectId = 'example-project-12345'.

Configurer le servlet Endpoints

Le servlet Endpoints gère les requêtes entrantes et les transfère au service de backend 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 web.xml, consultez la page Descripteur de déploiement: web.xml.

appengine-java8/endpoints-v2-squelette/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 documentation de référence de appengine-web.xml.

appengine-java8/endpoints-v2-autrement dit/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>

Étape suivante