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 dans Utiliser Apache Maven et le plug-in App Engine (basé sur la Google Cloud CLI) 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. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

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

Installer et configurer le logiciel 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

   • Installez Gradle.
3. Téléchargez et initialisez Google Cloud CLI.
4. Exécutez les commandes suivantes :
   1. Assurez-vous que gcloud CLI 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 de Google Cloud SDK:

      gcloud components install app-engine-java

   4. Installez la dernière version de Google Cloud SDK 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 de gcloud CLI.

   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 :

   

   • 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 de projet et de configuration utilisées par Maven pour générer 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 générer le projet et déployer 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 :

<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.23</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>

• La dépendance endpoints-framework contient les classes nécessaires à la création de votre API.
• Vous avez besoin du SDK de l'API standard d'App Engine (appengine-api-sdk) pour déployer votre projet dans l'environnement standard App Engine.
• Le package javax.servlet standard est requis pour créer un servlet.
• Le package javax.inject standard est requis pour permettre l'injection de dépendances.

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.4.0</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.5.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.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 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 :

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

• Le plug-in Gradle de Endpoints Frameworks sert à générer un document OpenAPI et des bibliothèques clientes.
• Vous avez besoin du plug-in Gradle pour App Engine afin de déployer votre projet dans App Engine.

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.2.2'
    compile 'com.google.appengine:appengine-api-1.0-sdk:2.0.23'

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

• La dépendance endpoints-framework contient les classes nécessaires à la création de votre API.
• Le SDK de l'API standard d'App Engine (appengine-api-sdk) est nécessaire pour déployer votre projet dans l'environnement standard App Engine.
• Le package javax.servlet standard est requis pour créer un servlet.
• Le package javax.inject standard est requis pour permettre l'injection de dépendances.

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

<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 votre ID de projet Google Cloud.

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.

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

• Écrivez et annotez le code de votre API backend.
• Obtenez plus d'informations sur les annotations.
• Ajoutez la gestion de l'API.
• Déployez et testez votre API.
• Obtenez plus d'informations sur les types de paramètres et de renvois compatibles.