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, comment fonctionne 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

Dans ce document, vous utilisez 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é 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.

    Accéder au sélecteur de projet

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

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

    Activer les API

    5.

  5. 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

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

  7. Activer les API Firestore, Cloud Functions, Pub/Sub, and Cloud Translation.

    Activer les API

    8.

  8. Dans la console Google Cloud, 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.

  9. Dans Cloud Shell, configurez l'outil gcloud pour utiliser 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.

    background/function/translate.js 
    const Firestore = require('@google-cloud/firestore');
const {Translate} = require('@google-cloud/translate').v2;

const firestore = new Firestore();
const translate = new Translate();

  • L'API Translation traduit la chaîne dans la langue que vous avez sélectionnée.

    background/function/translate.js 
    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.

    background/function/translate.js 
    // 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 : les envois de formulaire sont envoyés à ce point de terminaison, ce qui publie la requête sur Pub/Sub à traduire de manière asynchrone.
  • Un modèle HTML rempli avec les traductions existantes par le serveur Node.js.

Serveur HTTP

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

    background/server/app.js 
    
// 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 :

    background/server/app.js 
    
// 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 :

    background/server/app.js 
    
// 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);
}

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:
    background/server/index.html 
    <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 MMD 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 une liste de traductions et un formulaire pour demander des traductions supplémentaires:
    background/server/index.html 
    <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 :

background/server/app.yaml 
runtime: nodejs10
  • Depuis le même répertoire que le fichier app.yaml, déployez votre application dans l'environnement standard App Engine: 
    gcloud app deploy

Tester l'application

Après avoir déployé la fonction Cloud et l'application App Engine, essayez d'effectuer une demande de traduction.

  1. Pour afficher l'application dans votre navigateur,saisissez l'URL suivante:

    https://PROJECT_ID.REGION_ID.r.appspot.com

    Remplacez les éléments suivants :

    Une page contient une liste vide de traductions et un formulaire de demande 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 points 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 la console Google Cloud, 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 la console Google Cloud, 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.

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.

Supprimer le projet Cloud

  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.

Supprimer l'instance App Engine

  1. Dans la console Google Cloud, accédez à la page Versions pour App Engine.

    Accéder à la page "Versions"

  2. Cochez la case correspondant à la version de l'application autre que celle par défaut que vous souhaitez supprimer.
  3. Pour supprimer la version de l'application, cliquez sur  Supprimer.

Supprimer la fonction Cloud

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

Étapes suivantes