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

Ce tutoriel utilise les composants facturables suivants de Google Cloud :

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é ce tutoriel, vous pouvez éviter de continuer à payer des frais en supprimant les ressources que vous avez créées. Consultez la page Effectuer un nettoyage pour en savoir plus.

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 Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

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

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

  4. Notez l'ID du projet, 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. 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.
  3. 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.

  4. 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.
  5. Téléchargez et initialisez le SDK Cloud.
  6. 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
  7. 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 du SDK Cloud.

    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 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 Endpoints, accédez à la page Endpoints de Cloud Console. 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 la commande curl ci-dessus :

  • 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 la commande curl ci-dessus :

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

Suivre l'activité de l'API

  1. Affichez les graphiques d'activité de votre API dans Cloud Console, 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 la visionneuse de journaux.

    Accéder à la page Visionneuse 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.

Nettoyer

Pour éviter que les ressources utilisées dans ce tutoriel soient facturées sur votre compte Google Cloud Platform :

  1. Dans Cloud Console, 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.

Étape suivante