Traitement en arrière-plan avec Node.js

De nombreuses applications doivent exécuter un traitement en arrière-plan dans d'autres contextes que celui d'une requête Web. Ce tutoriel indique comment créer une application Web qui permet aux utilisateurs de saisir du texte à traduire, puis qui affiche la liste des traductions précédentes. La traduction est effectuée dans un traitement en arrière-plan pour éviter de bloquer la requête de l'utilisateur.

Le schéma suivant illustre le processus de requête de traduction.

Schéma de l'architecture

Voici, dans l'ordre, les étapes du fonctionnement de l'application du tutoriel :

  1. L'application accède à la page Web pour consulter la liste des traductions précédentes stockées dans Firestore.
  2. Elle demande la traduction d'un texte en saisissant un formulaire HTML.
  3. La requête de traduction est publiée dans Pub/Sub.
  4. Une fonction Cloud abonnée à ce sujet Pub/Sub est déclenchée.
  5. Cette fonction Cloud utilise Cloud Translation pour traduire le texte.
  6. La fonction Cloud stocke le résultat dans Firestore.

Ce tutoriel est destiné à toute personne intéressée par le traitement en arrière-plan avec Google Cloud. Il ne nécessite aucune connaissance particulière de Pub/Sub, Firestore, App Engine ou Cloud Functions. Cependant, pour comprendre l'intégralité du code, il peut être utile de se familiariser avec Node.js, JavaScript et HTML.

Objectifs

  • Comprendre et déployer une fonction Cloud
  • Comprendre et déployer une application App Engine
  • Tester l'application

Coûts

Ce tutoriel utilise les composants facturables de Google Cloud Platform répertoriés ici :

Vous pouvez vous servir du simulateur de coût pour générer une estimation des coûts en fonction de votre utilisation prévue. Les nouveaux utilisateurs de GCP 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 la page de sélection du projet de la console GCP, sélectionnez ou créez un projet GCP.

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

  3. Assurez-vous que la facturation est activée pour votre projet Google Cloud Platform. Découvrez comment confirmer que la facturation est activée pour votre projet.

  4. Activez les Firestore, Cloud Functions, Pub/Sub, and Cloud Translation API requises.

    Activer les API

  5. Dans Google Cloud Console, ouvrez l'application dans Cloud Shell.

    Accéder à Cloud Shell

    Cloud Shell vous permet d'accéder en ligne de commande à vos ressources cloud, directement depuis votre navigateur. Ouvrez Cloud Shell dans votre navigateur et cliquez sur Proceed (Continuer) pour télécharger l'exemple de code et le modifier dans le répertoire de l'application.

  6. Dans Cloud Shell, configurez l'outil gcloud pour qu'il utilise votre projet Google Cloud :
    # Configure gcloud for your project
    gcloud config set project YOUR_PROJECT_ID

Comprendre la fonction Cloud

  • La fonction commence par importer plusieurs dépendances telles que Firestore et Translation. Les clients Firestore et Translation internationaux sont initialisés afin qu'ils puissent être réutilisés pour les appels de fonction. De cette manière, vous n'avez pas besoin d'initialiser de nouveaux clients à chaque appel de fonction, ce qui ralentirait l'exécution.

    const {Firestore} = require('@google-cloud/firestore');
    const {Translate} = require('@google-cloud/translate');
    
    const firestore = new Firestore();
    const translate = new Translate();
  • L'API Translation traduit la chaîne dans la langue que vous avez sélectionnée.

    const [
      translated,
      {
        data: {translations},
      },
    ] = await translate.translate(original, language);
    const originalLanguage = translations[0].detectedSourceLanguage;
    console.log(
      `Translated ${original} in ${originalLanguage} to ${translated} in ${language}.`
    );
  • La fonction Cloud analyse le message Pub/Sub pour obtenir le texte à traduire et la langue cible souhaitée.

    L'application envoie ensuite une requête de traduction et stocke le résultat dans Firestore.

    // translate translates the given message and stores the result in Firestore.
    // Triggered by Pub/Sub message.
    exports.translate = async pubSubEvent => {
      const {language, original} = JSON.parse(
        Buffer.from(pubSubEvent.data, 'base64').toString()
      );
    
      const [
        translated,
        {
          data: {translations},
        },
      ] = await translate.translate(original, language);
      const originalLanguage = translations[0].detectedSourceLanguage;
      console.log(
        `Translated ${original} in ${originalLanguage} to ${translated} in ${language}.`
      );
    
      // Store translation in firestore.
      await firestore
        .collection('translations')
        .doc()
        .set({
          language,
          original,
          translated,
          originalLanguage,
        });
    };

Déployer la fonction Cloud Functions

  • Déployez la fonction Cloud avec un déclencheur Pub/Sub dans le répertoire où se trouve le fichier translate.js :

    gcloud functions deploy translate --runtime nodejs10 --trigger-topic translate

Comprendre l'application

L'application Web comporte deux composants principaux :

  • Un serveur HTTP Node.js pour gérer les requêtes Web. Il comporte les deux points de terminaison suivants :
    • / : répertorie toutes les traductions existantes et affiche un formulaire que les utilisateurs peuvent envoyer pour demander de nouvelles traductions.
    • /request-translation : point de terminaison auquel sont envoyés les formulaires. Il publie la requête sur Pub/Sub pour qu'elle soit traduite de manière asynchrone.
  • Un modèle HTML que le serveur Node.js remplit à l'aide des traductions existantes.

Le serveur HTTP

  • Dans le répertoire server, app.js commence par configurer l'application et enregistrer les gestionnaires HTTP :

    
    // This app is an HTTP app that displays all previous translations
    // (stored in Firestore) and has a form to request new translations. On form
    // submission, the request is sent to Pub/Sub to be processed in the background.
    
    // TOPIC_NAME is the Pub/Sub topic to publish requests to. The Cloud Function to
    // process translation requests should be subscribed to this topic.
    const TOPIC_NAME = 'translate';
    
    const express = require('express');
    const bodyParser = require('body-parser');
    const {PubSub} = require('@google-cloud/pubsub');
    const {Firestore} = require('@google-cloud/firestore');
    
    const app = express();
    const port = process.env.PORT || 8080;
    
    const firestore = new Firestore();
    
    const pubsub = new PubSub();
    const topic = pubsub.topic(TOPIC_NAME);
    
    // Use handlebars.js for templating.
    app.set('views', __dirname);
    app.set('view engine', 'html');
    app.engine('html', require('hbs').__express);
    
    app.use(bodyParser.urlencoded({extended: true}));
    
    app.get('/', index);
    app.post('/request-translation', requestTranslation);
    app.listen(port, () => console.log(`Listening on port ${port}!`));
    
  • Le gestionnaire d'index (/) récupère toutes les traductions existantes dans Firestore et renseigne un modèle HTML à l'aide de la liste suivante :

    
    // index lists the current translations.
    async function index(req, res) {
      const translations = [];
      const querySnapshot = await firestore.collection('translations').get();
      querySnapshot.forEach(doc => {
        console.log(doc.id, ' => ', doc.data());
        translations.push(doc.data());
      });
    
      res.render('index', {translations});
    }
    
  • Pour demander de nouvelles traductions, envoyez un formulaire HTML. Le gestionnaire des requêtes de traduction, enregistré sur /request-translation, analyse le formulaire envoyé, valide la requête, puis publie un message dans Pub/Sub :

    
    // requestTranslation parses the request, validates it, and sends it to Pub/Sub.
    function requestTranslation(req, res) {
      const language = req.body.lang;
      const original = req.body.v;
    
      const acceptableLanguages = ['de', 'en', 'es', 'fr', 'ja', 'sw'];
      if (!acceptableLanguages.includes(language)) {
        throw new Error(`Invalid language ${language}`);
      }
    
      console.log(`Translation requested: ${original} -> ${language}`);
    
      const buffer = Buffer.from(JSON.stringify({language, original}));
      topic.publish(buffer);
      res.sendStatus(200);
    }

Le modèle HTML

Le modèle HTML représente la base de la page HTML affichée à l'utilisateur afin qu'il puisse consulter les traductions précédentes et en demander de nouvelles. Ce modèle est rempli par le serveur HTTP à l'aide de la liste des traductions existantes.

  • L'élément <head> du modèle HTML inclut des métadonnées, des feuilles de style et le code JavaScript de la page :
    <html>
    
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>Translations</title>
    
        <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons">
        <link rel="stylesheet" href="https://code.getmdl.io/1.3.0/material.indigo-pink.min.css">
        <script defer src="https://code.getmdl.io/1.3.0/material.min.js"></script>
        <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
        <script>
            $(document).ready(function() {
                $("#translate-form").submit(function(e) {
                    e.preventDefault();
                    // Get value, make sure it's not empty.
                    if ($("#v").val() == "") {
                        return;
                    }
                    $.ajax({
                        type: "POST",
                        url: "/request-translation",
                        data: $(this).serialize(),
                        success: function(data) {
                            // Show snackbar.
                            console.log(data);
                            var notification = document.querySelector('.mdl-js-snackbar');
                            $("#snackbar").removeClass("mdl-color--red-100");
                            $("#snackbar").addClass("mdl-color--green-100");
                            notification.MaterialSnackbar.showSnackbar({
                                message: 'Translation requested'
                            });
                        },
                        error: function(data) {
                            // Show snackbar.
                            console.log("Error requesting translation");
                            var notification = document.querySelector('.mdl-js-snackbar');
                            $("#snackbar").removeClass("mdl-color--green-100");
                            $("#snackbar").addClass("mdl-color--red-100");
                            notification.MaterialSnackbar.showSnackbar({
                                message: 'Translation request failed'
                            });
                        }
                    });
                });
            });
        </script>
        <style>
            .lang {
                width: 50px;
            }
            .translate-form {
                display: inline;
            }
        </style>
    </head>

    Cette page intègre des éléments Material Design Lite (MDL) CSS et JavaScript. MDL vous permet d'apporter un aspect Material Design à vos sites Web.

    JQuery permet d'attendre la fin de chargement du document et de définir un gestionnaire d'envoi de formulaires. Chaque fois que le formulaire de requête de traduction est envoyé, la page effectue une validation minimale du formulaire pour vérifier que la valeur n'est pas vide, puis envoie une requête asynchrone au point de terminaison /request-translation.

    Enfin, un snackbar MDL apparaît pour indiquer si la requête a abouti ou si une erreur s'est produite.

  • Le corps HTML de la page utilise une mise en page MDL et plusieurs composants MDL pour afficher la liste des traductions ainsi qu'un formulaire de requête de traductions supplémentaires :
    <body>
        <div class="mdl-layout mdl-js-layout mdl-layout--fixed-header">
            <header class="mdl-layout__header">
                <div class="mdl-layout__header-row">
                    <!-- Title -->
                    <span class="mdl-layout-title">Translate with Background Processing</span>
                </div>
            </header>
            <main class="mdl-layout__content">
                <div class="page-content">
                    <div class="mdl-grid">
                    <div class="mdl-cell mdl-cell--1-col"></div>
                        <div class="mdl-cell mdl-cell--3-col">
                            <form id="translate-form" class="translate-form">
                                <div class="mdl-textfield mdl-js-textfield mdl-textfield--floating-label">
                                    <input class="mdl-textfield__input" type="text" id="v" name="v">
                                    <label class="mdl-textfield__label" for="v">Text to translate...</label>
                                </div>
                                <select class="mdl-textfield__input lang" name="lang">
                                    <option value="de">de</option>
                                    <option value="en">en</option>
                                    <option value="es">es</option>
                                    <option value="fr">fr</option>
                                    <option value="ja">ja</option>
                                    <option value="sw">sw</option>
                                </select>
                                <button class="mdl-button mdl-js-button mdl-button--raised mdl-button--accent" type="submit"
                                    name="submit">Submit</button>
                            </form>
                        </div>
                        <div class="mdl-cell mdl-cell--8-col">
                            <table class="mdl-data-table mdl-js-data-table mdl-shadow--2dp">
                                <thead>
                                    <tr>
                                        <th class="mdl-data-table__cell--non-numeric"><strong>Original</strong></th>
                                        <th class="mdl-data-table__cell--non-numeric"><strong>Translation</strong></th>
                                    </tr>
                                </thead>
                                <tbody>
                                    {{#each translations}}
                                    <tr>
                                        <td class="mdl-data-table__cell--non-numeric">
                                            <span class="mdl-chip mdl-color--primary">
                                                <span class="mdl-chip__text mdl-color-text--white">{{ originalLanguage }} </span>
                                            </span>
                                        {{ original }}
                                        </td>
                                        <td class="mdl-data-table__cell--non-numeric">
                                            <span class="mdl-chip mdl-color--accent">
                                                <span class="mdl-chip__text mdl-color-text--white">{{ language }} </span>
                                            </span>
                                            {{ translated }}
                                        </td>
                                    </tr>
                                    {{/each}}
                                </tbody>
                            </table>
                            <br/>
                            <button class="mdl-button mdl-js-button mdl-button--raised" type="button" onClick="window.location.reload();">
                                Refresh
                            </button>
                        </div>
                    </div>
                </div>
                <div aria-live="assertive" aria-atomic="true" aria-relevant="text" class="mdl-snackbar mdl-js-snackbar" id="snackbar">
                    <div class="mdl-snackbar__text mdl-color-text--black"></div>
                    <button type="button" class="mdl-snackbar__action"></button>
                </div>
            </main>
        </div>
    </body>
    
    </html>

Déployer l'application Web

Vous pouvez utiliser l'environnement standard App Engine pour créer et déployer une application qui s'exécute de manière fiable, même lorsqu'elle est soumise à une charge importante et doit gérer de grandes quantités de données.

Dans ce tutoriel, l'interface HTTP est déployée dans l'environnement standard App Engine.

Le fichier app.yaml configure l'application App Engine :

runtime: nodejs10
  • Déployez l'application dans l'environnement standard App Engine à partir du répertoire où se trouve le fichier app.yaml :
    gcloud app deploy

Tester l'application

Après avoir déployé la fonction Cloud et l'application App Engine, essayez d'envoyer une requête de traduction.

  1. Pour afficher l'application dans votre navigateur, accédez à l'adresse https://YOUR_GOOGLE_CLOUD_PROJECT.appspot.com.

    Il s'agit d'une page affichant une liste de traductions vide ainsi qu'un formulaire de requête de nouvelles traductions.

  2. Dans le champ Texte à traduire, saisissez un texte à traduire. Exemple : Hello, World.
  3. Dans la liste déroulante, sélectionnez la langue dans laquelle vous souhaitez traduire le texte.
  4. Cliquez sur Envoyer.
  5. Pour actualiser la page, cliquez sur Actualiser . Une nouvelle ligne s'affiche dans la liste de traduction. Si vous ne voyez pas de traduction, attendez encore quelques secondes, puis réessayez. Si vous ne voyez toujours pas de traduction, consultez la section suivante sur le débogage de l'application.

Déboguer l'application

Si vous ne parvenez pas à vous connecter à votre application App Engine ou que vous ne voyez pas de nouvelle traduction, vérifiez les éléments suivants :

  1. Vérifiez que les commandes de déploiement gcloud ont bien abouti et n'ont généré aucune erreur. Si des erreurs se sont produites, corrigez-les, puis essayez de redéployer la fonction Cloud et l'application App Engine.
  2. Dans Google Cloud Console, accédez à la page Visionneuse de journaux.

    Accéder à la page "Visionneuse de journaux"
    1. Dans la liste déroulante Ressources sélectionnées récemment, cliquez sur Application GAE , puis sur Tous les ID de module. La liste des requêtes correspondant à votre accès à l'application s'affiche. Si cette liste n'apparaît pas, vérifiez que vous avez bien sélectionné Tous les ID de module dans la liste déroulante. Si des messages d'erreur s'affichent dans Cloud Console, vérifiez que le code de votre application correspond au code décrit dans la section sur la compréhension de l'application.
    2. Dans la liste déroulante Ressources sélectionnées récemment, cliquez sur Fonction Cloud, puis sur Tous les noms de fonction. Une fonction est répertoriée pour chaque traduction demandée. Si ce n'est pas le cas, vérifiez que la fonction Cloud et l'application App Engine utilisent le même sujet Pub/Sub :
      • Dans le fichier background/server/app.js, vérifiez que la valeur de la constante TOPIC_NAME est "translate".
      • Lorsque vous déployez la fonction Cloud, veillez à inclure l'option --trigger-topic=translate.

Nettoyer

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

Supprimer le projet Google Cloud

  1. Dans la console GCP, 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.

Supprimer l'instance App Engine

  1. Dans la console GCP, accédez à la page Versions d'App Engine.

    Accéder à la page Versions

  2. Cochez la case à côté de la version de l'application (autre que celle par défaut) que vous souhaitez supprimer.
  3. Cliquez sur le bouton Supprimer delete situé en haut de la page pour supprimer la version de l'application.

Supprimer la fonction Cloud

  • Supprimez la fonction Cloud que vous avez créée dans ce tutoriel :
    gcloud functions delete Translate

Étapes suivantes