Premiers pas avec Cloud Endpoints Frameworks pour Java

---

Cette page vous explique comment configurer, déployer et envoyer des requêtes à un exemple d'API à l'aide de Cloud Endpoints Frameworks pour Java. Endpoints Frameworks pour Java est intégré à l'environnement d'exécution standard Java 8 d'App Engine. Endpoints Frameworks comprend des outils, des bibliothèques et des fonctionnalités vous permettant de générer des API et des bibliothèques clientes à partir d'une application App Engine.

Objectifs

Tout au long du tutoriel, reportez-vous au récapitulatif des étapes présenté ci-dessous. Toutes les tâches sont nécessaires pour envoyer des requêtes à l'API.

1. Configurez un projet Google Cloud. Consultez la section Avant de commencer.
2. Installez les logiciels nécessaires et créez une application App Engine. Consultez la section Installer et configurer les logiciels requis.
3. Téléchargez l'exemple de code. Consultez la section Obtenir l'exemple de code.
4. Générez un fichier de configuration OpenAPI. Consultez la section Configurer Cloud Endpoints.
5. Déployez la configuration Endpoints pour créer un service Endpoints. Consultez la section Déployer la configuration Endpoints.
6. Exécutez l'exemple sur votre ordinateur. Consultez la section Exécuter l'exemple en local.
7. Créez un backend pour publier et déployer l'API. Consultez la section Déployer le backend de l'API.
8. Envoyez une requête à l'API. Consultez la section Envoyer une requête à l'API.
9. Suivez l'activité de l'API. Consultez la section Suivre l'activité de l'API.
10. Faites le nécessaire pour éviter que des frais ne soient facturés sur votre compte Google Cloud. Consultez la section Nettoyer.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• Points de terminaison
• App Engine

Obtenez une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût. Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai gratuit.

Une fois que vous avez terminé les tâches décrites dans ce document, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Pour en savoir plus, consultez la section Effectuer un nettoyage.

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.

   Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

   Accéder au sélecteur de projet

3. Vérifiez que la facturation est activée pour votre projet Google Cloud.

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

   Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

   Accéder au sélecteur de projet

5. Vérifiez que la facturation est activée pour votre projet Google Cloud.

6. Notez l'ID du projet, 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. Comme Endpoints Frameworks pour Java dépend de l'environnement d'exécution standard Java 8 d'App Engine, le service n'est compatible avec aucune autre version de Java.
2. Si vous n'avez pas encore installé Maven 3.3.9 ou une version ultérieure, téléchargez-le et installez-le.

Remarque pour les utilisateurs de Windows : Si vous installez le JDK et Maven sous Windows, faites-le dans un répertoire dont le chemin d'accès ne comprend aucun espace. Pour en savoir plus, consultez la page Maven on Windows.

3. Vous aurez besoin d'une application pour envoyer des requêtes à l'exemple d'API.

   • Utilisateurs Linux et macOS : ce tutoriel fournit un exemple utilisant curl, qui est généralement préinstallé sur votre système d'exploitation. Si vous ne disposez pas de curl, vous pouvez le télécharger sur la page Releases and Downloads de curl.
   • Utilisateurs Windows : ce tutoriel fournit un exemple d'utilisation de Invoke-WebRequest, compatible avec PowerShell 3.0 et versions ultérieures.
4. Téléchargez et initialisez la Google Cloud CLI.
5. Exécutez les commandes suivantes :
   1. Assurez-vous que la 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

6. Créez une application App Engine :
   1. Définissez le projet par défaut sur votre ID de projet.

      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 gcloud CLI.

   2. Sélectionnez la région dans laquelle vous souhaitez créer votre application App Engine. Exécutez la commande suivante pour obtenir la liste des régions :

      gcloud app regions list

   3. Créez une application App Engine à l'aide de la commande suivante. Remplacez YOUR_PROJECT_ID par votre ID de 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 code

Pour cloner l'exemple d'API de GitHub :

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

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

Configurer Endpoints

L'exemple inclut l'outil Endpoints Frameworks, qui génère un fichier de configuration OpenAPI décrivant l'API REST de l'exemple de code. Suivez les étapes de cette section pour configurer et créer l'exemple de projet Maven afin de pouvoir ensuite générer le fichier de configuration OpenAPI.

Ajouter l'ID de projet à l'exemple de code de l'API

Vous devez ajouter l'ID obtenu lors de la création du projet dans le fichier pom.xml de l'exemple pour pouvoir déployer le code.

Pour ajouter l'ID de projet :

1. Modifiez le fichier java-docs-samples/appengine-java8/endpoints-v2-backend/pom.xml.

2. Recherchez <endpoints.project.id>, puis remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud.

   Exemple :

   <endpoints.project.id>example-project</endpoints.project.id>
   

3. Enregistrez les modifications.

Créer l'exemple de projet

Pour créer le projet :

1. Assurez-vous que vous vous trouvez dans le répertoire java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Exécutez la commande suivante :

   mvn clean package
   

3. Attendez que le projet se crée. Un message semblable à celui-ci s'affiche alors :

   [INFO] BUILD SUCCESS
   [INFO] ------------------------------------------------------------------------
   [INFO] Total time: 14.846s
   [INFO] Finished at: Wed April 13 09:43:09 PDT 2016
   [INFO] Final Memory: 24M/331M
   

Générer le fichier de configuration OpenAPI

Vous allez utiliser un outil de la bibliothèque Endpoints Frameworks pour générer un document OpenAPI nommé openapi.json. Ce fichier décrit l'API REST de l'exemple de code.

Pour générer le fichier de configuration OpenAPI :

1. Appelez l'outil Endpoints Frameworks à l'aide de cette commande :

   mvn endpoints-framework:openApiDocs
   

2. Patientez pendant la création de la spécification de configuration. Une fois l'opération terminée, un message semblable à celui-ci s'affiche :

   OpenAPI document written to target/openapi-docs/openapi.json
   

   Ignorez les messages concernant l'échec du chargement d'une classe Logger statique.

Déployer la configuration Endpoints

Pour déployer la configuration Endpoints, vous allez utiliser Service Infrastructure, la plate-forme de services de base de Google, utilisée par Endpoints Frameworks et d'autres services pour créer et gérer des API et des services.

Pour déployer le fichier de configuration :

1. Assurez-vous que vous vous trouvez dans le répertoire java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Déployez le fichier de configuration OpenAPI généré dans la section précédente :

   gcloud endpoints services deploy target/openapi-docs/openapi.json
   

Cela crée un service Endpoints avec un nom au format YOUR_PROJECT_ID.appspot.com. Ce nom est configuré dans pom.xml et dans d'autres fichiers de configuration inclus dans l'exemple. Notez que, lorsque vous déployez l'API sur App Engine, un enregistrement DNS est créé avec un nom au format YOUR_PROJECT_ID.appspot.com. Il s'agit du nom de domaine complet que vous utilisez lorsque vous envoyez des requêtes à l'API.

Lors de la création et de la configuration du service, Service Management envoie des informations au terminal. Vous pouvez ignorer en toute sécurité les avertissements indiquant que les chemins dans openapi.json ne nécessitent pas de clé API. Si l'opération réussit, une ligne semblable à la suivante affiche l'ID de configuration du service et le nom du service :

Service Configuration [2017-02-13-r2] uploaded for service [example-project-12345.appspot.com]

Dans l'exemple ci-dessus, 2017-02-13-r2 correspond à l'ID de configuration du service et example-project-12345.appspot.com au nom du service.

Pour en savoir plus, consultez la page gcloud endpoints services deploy.

Vérifier les services requis

Pour assurer la gestion des API, Endpoints Frameworks a besoin des services suivants :

Nom	Title (Titre)
servicemanagement.googleapis.com	API Service Management
servicecontrol.googleapis.com	API Service Control
endpoints.googleapis.com	Google Cloud Endpoints

Dans la plupart des cas, la commande gcloud endpoints services deploy permet d'activer ces services requis. Toutefois, bien que la commande gcloud ait abouti, elle n'active pas les services requis dans les cas suivants :

• Vous avez utilisé une application tierce telle que Terraform et vous n'incluez pas ces services.

• Vous avez déployé la configuration Endpoints dans un projet Google Cloud existant dans lequel ces services étaient explicitement désactivés.

Utilisez la commande suivante pour vérifier que les services nécessaires sont activés :

gcloud services list

Si les services requis ne sont pas répertoriés, activez-les :

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Activez également votre service Endpoints :

gcloud services enable ENDPOINTS_SERVICE_NAME

Pour déterminer la valeur de ENDPOINTS_SERVICE_NAME, vous pouvez effectuer l'une des opérations suivantes :

• Après avoir déployé la configuration des points de terminaison, accédez à la page Points de terminaison de la console Cloud. La liste des valeurs ENDPOINTS_SERVICE_NAME possibles s'affiche dans la colonne Nom du service.

• Pour OpenAPI, ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ host de votre spécification OpenAPI. Pour gRPC, ENDPOINTS_SERVICE_NAME correspond à ce que vous avez spécifié dans le champ name de votre configuration Endpoints gRPC.

Pour en savoir plus sur les commandes gcloud, consultez la page Services gcloud.

Exécuter l'exemple en local

Après avoir déployé la configuration Endpoints, vous pouvez exécuter l'exemple en local.

1. Créez une variable d'environnement appelée ENDPOINTS_SERVICE_NAME, qui permet de définir le nom d'hôte dans le fichier appengine-web.xml de l'exemple. Dans ce qui suit, remplacez YOUR_PROJECT_ID par l'ID de votre projet Google Cloud.

   Sous Linux ou macOS :

   export ENDPOINTS_SERVICE_NAME=YOUR_PROJECT_ID.appspot.com
   

   Dans Windows PowerShell :

   $Env:ENDPOINTS_SERVICE_NAME="YOUR_PROJECT_ID.appspot.com"
   

2. Procurez-vous de nouveaux identifiants utilisateur à utiliser comme identifiants par défaut de l'application.

   gcloud auth application-default login
   

3. Exécutez le serveur de développement :

   mvn appengine:run
   

   L'instance locale est accessible à l'adresse http://localhost:8080, comme indiqué par les journaux affichés par la commande mvn appengine:run :

   [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:8080/
   

4. Envoyez une requête à l'instance locale :

Linux ou macOS

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    http://localhost:8080/_ah/api/echo/v1/echo

Dans l'élément curl précédent:

• L'option --data indique les données à publier sur l'API.
• L'option --header indique que les données sont au format JSON.

PowerShell

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} `
    -URI "http://localhost:8080/_ah/api/echo/v1/echo").Content

Dans l'exemple ci-dessus, les deux premières lignes se terminent par un accent grave. Lorsque vous collez l'exemple dans PowerShell, assurez-vous qu'il n'y a pas d'espace après les accents graves. Pour plus d'informations sur les options utilisées dans l'exemple de requête, consultez la page Invoke-WebRequest dans la documentation Microsoft.

L'API renvoie le message que vous lui avez envoyé et répond avec les éléments suivants :

{
 "message": "hello world"
}

Déployer le backend de l'API

Vous avez déployé la configuration OpenAPI dans Service Management, mais vous n'avez pas encore déployé le code qui diffuse le backend de l'API. Cette section vous guide tout au long du déploiement de l'exemple d'API dans App Engine.

Pour déployer le backend de l'API :

1. Assurez-vous que vous vous trouvez dans le répertoire java-docs-samples/appengine-java8/endpoints-v2-backend.

2. Déployez le code de mise en œuvre de l'API à l'aide de Maven :

    mvn appengine:deploy
   

   La première fois que vous importez un exemple d'application, vous pouvez être invité à autoriser le déploiement. Suivez les instructions. Lorsqu'une fenêtre de navigateur contenant un code vous est présentée, copiez-le dans la fenêtre du terminal.

3. Attendez que le téléchargement se termine.

   Nous vous recommandons d'attendre quelques minutes et la fin de l'initialisation complète d'App Engine avant d'envoyer des requêtes à votre API.

Envoyer une requête à l'API

Après avoir déployé l'API et son fichier de configuration, vous pouvez envoyer des requêtes à l'API.

Linux ou macOS

Envoyez une requête HTTP à l'aide de curl. Remplacez [YOUR_PROJECT_ID] par l'ID de votre projet Google Cloud :

curl \
    --request POST \
    --header "Content-Type: application/json" \
    --data '{"message":"hello world"}' \
    https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo

Dans l'élément curl précédent:

• L'option --data indique les données à publier sur l'API.
• L'option --header indique que les données sont au format JSON.

PowerShell

Envoyez une requête HTTP à l'aide de Invoke-WebRequest. Remplacez [YOUR_PROJECT_ID] par l'ID de votre projet Google Cloud :

(Invoke-WebRequest -Method POST -Body '{"message": "hello world"}' `
    -Headers @{"content-type"="application/json"} -URI `
     "https://[YOUR_PROJECT_ID].appspot.com/_ah/api/echo/v1/echo").Content

Dans l'exemple ci-dessus, les deux premières lignes se terminent par un accent grave. Lorsque vous collez l'exemple dans PowerShell, assurez-vous qu'il n'y a pas d'espace après les accents graves. Pour plus d'informations sur les options utilisées dans l'exemple de requête, consultez la page Invoke-WebRequest dans la documentation Microsoft.

Application tierce

Vous pouvez utiliser une application tierce telle que l'extension Postman du navigateur Chrome pour envoyer la requête :

• Sélectionnez POST comme verbe HTTP.
• Pour l'en-tête, sélectionnez la clé content-type et la valeur application/json.
• Pour le corps, saisissez ce qui suit:
  {"message":"hello world"}
• Saisissez l'URL de l'exemple d'application. Par exemple :
  https://example-project-12345.appspot.com/_ah/api/echo/v1/echo

L'API renvoie le message que vous avez envoyé et répond avec les éléments suivants :

{
 "message": "hello world"
}

Si vous ne recevez pas de réponse positive, consultez la section Dépanner des erreurs de réponse.

Vous venez de déployer et de tester une API dans Endpoints Frameworks !

Remarque : Si vous souhaitez nous donner votre avis sur ce tutoriel, n'hésitez pas à nous faire part de vos commentaires au bas de cette page. Ils nous sont utiles pour améliorer nos tutoriels.
Si vous rencontrez une erreur, rejoignez le groupe Google google-cloud-endpoints et faites-nous part de ce qui n'a pas fonctionné. Ce groupe reçoit les réponses d'autres utilisateurs Endpoints et d'ingénieurs Google qui supervisent le groupe.

Suivre l'activité de l'API

1. Affichez les graphiques d'activité de votre API dans la console Google Cloud, sur la page Endpoints > Service.

   Accédez à la page Services Endpoints

   Il peut s'écouler quelques instants avant que la requête ne soit reflétée dans les graphiques.

2. Consultez les journaux de requêtes de votre API sur la page de l'explorateur de journaux.

   Accéder à la page "Explorateur de journaux"

Créer un portail développeur pour l'API

Vous pouvez utiliser le portail Cloud Endpoints pour créer un portail des développeurs, c'est-à-dire un site Web qui vous permet d'interagir avec l'exemple d'API. Pour en savoir plus, consultez la page Présentation du portail Cloud Endpoints.

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Attention : La suppression d'un projet aura les effets suivants :
• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches de ce document, lorsque vous le supprimez, vous supprimez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.
1. Dans la console Google Cloud, accédez à la page Gérer les ressources.

   Accéder à la page Gérer les ressources

2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Étapes suivantes

• Découvrez l'architecture Endpoints Frameworks.
• Découvrez les annotations d'API disponibles.
• Découvrez comment diffuser votre API depuis un autre chemin d'accès.
• Découvrez comment surveiller votre API.
• Découvrez comment restreindre l'accès à l'aide de clés API.
• Découvrez comment gérer les versions d'API.
• Découvrez les options d'assistance de la communauté.