Déclencher des fonctions Cloud Functions à l'aide de Cloud Tasks

Ce tutoriel explique comment utiliser Cloud Tasks dans une application App Engine pour déclencher une fonction Cloud et envoyer un e-mail programmé.

Objectifs

Comprendre le code de chacun des composants
Créer un compte SendGrid
Téléchargez le code source.
Déployez une fonction Cloud pour recevoir des requêtes Cloud Tasks et envoyer un e-mail via l'API SendGrid.
Créez une file d'attente Cloud Tasks.
Créez un compte de service pour authentifier vos requêtes Cloud Tasks.
Déployez le code client permettant à un utilisateur d'envoyer un e-mail.

Coûts

Cloud Tasks, Cloud Functions et App Engine disposent d'une version gratuite. Par conséquent, si vous exécutez le didacticiel dans cette version gratuite des produits concernés, cela ne devrait pas entraîner de coûts supplémentaires. Pour en savoir plus, reportez-vous à la section Tarification.

Avant de commencer

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 à la page App Engine
Initialisez une application App Engine dans votre projet :
1. Sur la page Bienvenue dans App Engine, cliquez sur Créer une application.
2. Sélectionnez une région pour votre application. Cet emplacement servira de paramètre LOCATION_ID pour vos requêtes Cloud Tasks. Notez-le donc. Notez que deux sites appelés europe-west et us-central dans les commandes App Engine sont appelés respectivement europe-west1 et us-central1 dans les commandes Cloud Tasks.
3. Sélectionnez Node.js pour le langage et Standard pour l'environnement.
4. Si la fenêtre pop-up Activer la facturation s'affiche, sélectionnez votre compte de facturation. Si vous ne possédez pas de compte de facturation, cliquez sur Créer un compte de facturation et suivez les instructions de l'assistant.
5. Sur la page Premiers pas, cliquez sur Suivant. Vous vous en occuperez plus tard.
Activez les API Cloud Functions et Cloud Tasks.

Activer les API
Installez et initialisez gcloud CLI.

Comprendre le code

Cette section décrit le code de l'application et son fonctionnement.

Créer la tâche

La page d'index est diffusée à l'aide de gestionnaires dans app.yaml. Les variables nécessaires à la création de tâches sont transmises en tant que variables d'environnement.

runtime: nodejs16

env_variables:
  QUEUE_NAME: "my-queue"
  QUEUE_LOCATION: "us-central1"
  FUNCTION_URL: "https://<region>-<project_id>.cloudfunctions.net/sendEmail"
  SERVICE_ACCOUNT_EMAIL: "<member>@<project_id>.iam.gserviceaccount.com"

# Handlers for serving the index page.
handlers:
  - url: /static
    static_dir: static
  - url: /
    static_files: index.html
    upload: index.html

Ce code crée le point de terminaison /send-email. Ce point de terminaison gère les envois de formulaires depuis la page d'index et transmet ces données au code de création de tâche.

app.post('/send-email', (req, res) => {
  // Set the task payload to the form submission.
  const {to_name, from_name, to_email, date} = req.body;
  const payload = {to_name, from_name, to_email};

  createHttpTaskWithToken(
    process.env.GOOGLE_CLOUD_PROJECT,
    QUEUE_NAME,
    QUEUE_LOCATION,
    FUNCTION_URL,
    SERVICE_ACCOUNT_EMAIL,
    payload,
    date
  );

  res.status(202).send('📫 Your postcard is in the mail! 💌');
});

Ce code crée la tâche et l'envoie à la file d'attente Cloud Tasks. Le code crée la tâche en effectuant ce qui suit :

Spécifier le type de cible comme HTTP Request.
Spécifier la méthode HTTP method à utiliser et la valeur URL de la cible.
Définir l'en-tête Content-Type sur application/json pour que les applications en aval puissent analyser la charge utile structurée.
Ajout d'une adresse e-mail de compte de service afin que Cloud Tasks puisse fournir des identifiants à la cible de la requête, ce qui nécessite une authentification. Le compte de service est créé séparément.
Vérifier que la date saisie par l'utilisateur est comprise dans la limite de 30 jours et l'ajouter à la requête en tant que champ scheduleTime.

const MAX_SCHEDULE_LIMIT = 30 * 60 * 60 * 24; // Represents 30 days in seconds.

const createHttpTaskWithToken = async function (
  project = 'my-project-id', // Your GCP Project id
  queue = 'my-queue', // Name of your Queue
  location = 'us-central1', // The GCP region of your queue
  url = 'https://example.com/taskhandler', // The full url path that the request will be sent to
  email = '<member>@<project-id>.iam.gserviceaccount.com', // Cloud IAM service account
  payload = 'Hello, World!', // The task HTTP request body
  date = new Date() // Intended date to schedule task
) {
  // Imports the Google Cloud Tasks library.
  const {v2beta3} = require('@google-cloud/tasks');

  // Instantiates a client.
  const client = new v2beta3.CloudTasksClient();

  // Construct the fully qualified queue name.
  const parent = client.queuePath(project, location, queue);

  // Convert message to buffer.
  const convertedPayload = JSON.stringify(payload);
  const body = Buffer.from(convertedPayload).toString('base64');

  const task = {
    httpRequest: {
      httpMethod: 'POST',
      url,
      oidcToken: {
        serviceAccountEmail: email,
        audience: url,
      },
      headers: {
        'Content-Type': 'application/json',
      },
      body,
    },
  };

  const convertedDate = new Date(date);
  const currentDate = new Date();

  // Schedule time can not be in the past.
  if (convertedDate < currentDate) {
    console.error('Scheduled date in the past.');
  } else if (convertedDate > currentDate) {
    const date_diff_in_seconds = (convertedDate - currentDate) / 1000;
    // Restrict schedule time to the 30 day maximum.
    if (date_diff_in_seconds > MAX_SCHEDULE_LIMIT) {
      console.error('Schedule time is over 30 day maximum.');
    }
    // Construct future date in Unix time.
    const date_in_seconds =
      Math.min(date_diff_in_seconds, MAX_SCHEDULE_LIMIT) + Date.now() / 1000;
    // Add schedule time to request in Unix time using Timestamp structure.
    // https://googleapis.dev/nodejs/tasks/latest/google.protobuf.html#.Timestamp
    task.scheduleTime = {
      seconds: date_in_seconds,
    };
  }

  try {
    // Send create task request.
    const [response] = await client.createTask({parent, task});
    console.log(`Created task ${response.name}`);
    return response.name;
  } catch (error) {
    // Construct error for Stackdriver Error Reporting
    console.error(Error(error.message));
  }
};

module.exports = createHttpTaskWithToken;

Création de l'e-mail

Ce code crée la fonction Cloud qui est la cible de la requête Cloud Tasks. Il utilise le corps de la requête pour créer un e-mail et l'envoyer via l'API SendGrid.

const sendgrid = require('@sendgrid/mail');

/**
 * Responds to an HTTP request from Cloud Tasks and sends an email using data
 * from the request body.
 *
 * @param {object} req Cloud Function request context.
 * @param {object} req.body The request payload.
 * @param {string} req.body.to_email Email address of the recipient.
 * @param {string} req.body.to_name Name of the recipient.
 * @param {string} req.body.from_name Name of the sender.
 * @param {object} res Cloud Function response context.
 */
exports.sendEmail = async (req, res) => {
  // Get the SendGrid API key from the environment variable.
  const key = process.env.SENDGRID_API_KEY;
  if (!key) {
    const error = new Error(
      'SENDGRID_API_KEY was not provided as environment variable.'
    );
    error.code = 401;
    throw error;
  }
  sendgrid.setApiKey(key);

  // Get the body from the Cloud Task request.
  const {to_email, to_name, from_name} = req.body;
  if (!to_email) {
    const error = new Error('Email address not provided.');
    error.code = 400;
    throw error;
  } else if (!to_name) {
    const error = new Error('Recipient name not provided.');
    error.code = 400;
    throw error;
  } else if (!from_name) {
    const error = new Error('Sender name not provided.');
    error.code = 400;
    throw error;
  }

  // Construct the email request.
  const msg = {
    to: to_email,
    from: 'postcard@example.com',
    subject: 'A Postcard Just for You!',
    html: postcardHTML(to_name, from_name),
  };

  try {
    await sendgrid.send(msg);
    // Send OK to Cloud Task queue to delete task.
    res.status(200).send('Postcard Sent!');
  } catch (error) {
    // Any status code other than 2xx or 503 will trigger the task to retry.
    res.status(error.code).send(error.message);
  }
};

Préparer l'application

Configurer SendGrid

Créer un compte SendGrid
- Vous pouvez le faire manuellement via le site Web SendGrid.
- Vous pouvez également utiliser Google Cloud Launcher, qui vous permet de créer un compte et d'intégrer la facturation. Consultez la section Créer un compte SendGrid en utilisant Cloud Launcher.
Créez une clé API SendGrid :
1. Connectez-vous à votre compte SendGrid.
2. Dans le panneau de navigation de gauche, ouvrez Paramètres et cliquez sur Clés API.
3. Cliquez sur Créer une clé API, puis sélectionnez l'accès restreint. Sous l'en-tête Mail Send (Envoi de courrier), sélectionnez Full Access (Accès complet).
4. Copiez la clé API lorsqu'elle est affichée (vous ne la verrez qu'une seule fois, assurez-vous de la coller quelque part pour pouvoir l'utiliser ultérieurement).

Télécharger le code source

Clonez le dépôt de l'exemple d'application sur votre machine locale :

git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

Accédez au répertoire qui contient l'exemple de code :
```
cd cloud-tasks/
```

Déployer la fonction Cloud Functions

Accédez au répertoire function/ :
```
cd function/
```
Déployez la fonction :
```
gcloud functions deploy sendEmail --runtime nodejs14 --trigger-http \
  --no-allow-unauthenticated \
  --set-env-vars SENDGRID_API_KEY=SENDGRID_API_KEY \
```
Remplacez SENDGRID_API_KEY par votre clé API.

Cette commande utilise des options :
- --trigger-http pour spécifier le type de déclencheur Cloud Functions.
- --no-allow-unauthenticated pour spécifier que l'appel de fonction nécessite une authentification.
- --set-env-var pour définir vos identifiants SendGrid
Remarque :Vous pouvez gérer Cloud Functions à la fois à partir de la console Firebase et de la console Google Cloud. L'écriture et le déploiement à partir de FirebaseUI peuvent être répliqués. Toutefois, le code de la fonction doit correspondre au framework Firebase Functions. Découvrez comment commencer à utiliser les fonctions Firebase et les déclencheurs HTTP.
Définissez le contrôle d'accès de la fonction pour autoriser uniquement les utilisateurs authentifiés.
1. Sélectionnez la fonction sendEmail dans l'interface utilisateur de Cloud Functions.
2. Si vous ne voyez pas les informations d'autorisation pour sendEmail, cliquez sur AFFICHER LE PANNEAU D'INFORMATIONS dans l'angle supérieur droit.
3. Cliquez sur le bouton Ajouter des comptes principaux.
4. Définissez le champ Nouveaux comptes principaux sur allAuthenticatedUsers.
5. Définissez le rôle.
  - Fonctions de première génération (1re génération):définissez le rôle sur Cloud Function Invoker.
  - Fonctions de deuxième génération (2e génération):définissez le rôle sur Cloud Run Invoker.
6. Cliquez sur SAVE (Enregistrer).

Créer une file d'attente Cloud Tasks

Créez une file d'attente à l'aide de la commande gcloud suivante :
```
gcloud tasks queues create my-queue --location=LOCATION
```
Remplacez LOCATION par l'emplacement de votre choix pour la file d'attente, par exemple us-west2. Si vous ne spécifiez pas d'emplacement, la gcloud CLI sélectionne la valeur par défaut.
Vérifiez qu'elle a bien été créée :
```
gcloud tasks queues describe my-queue --location=LOCATION
```
Remplacez LOCATION par l'emplacement de la file d'attente.

Créer un compte de service

La requête Cloud Tasks doit fournir des identifiants dans l'en-tête Authorization pour que la fonction Cloud puisse authentifier la requête. Ce compte de service permet à Cloud Tasks de créer et d'ajouter un jeton OIDC à cette fin.

Dans l'interface utilisateur des comptes de service, cliquez sur + CRÉER UN COMPTE DE SERVICE.
Ajoutez un nom de compte de service (nom à afficher convivial) et sélectionnez créer.
Définissez le rôle et cliquez sur Continuer.
- Fonctions de première génération (1re génération):définissez le rôle sur Cloud Function Invoker.
- Fonctions de deuxième génération (2e génération):définissez le rôle sur Cloud Run Invoker.
Sélectionnez OK.

Déployer le point de terminaison et le créateur de tâches dans App Engine

Accédez au répertoire app/ :
```
cd ../app/
```

Mettez à jour les variables dans app.yaml avec vos valeurs :

env_variables:
  QUEUE_NAME: "my-queue"
  QUEUE_LOCATION: "us-central1"
  FUNCTION_URL: "https://<region>-<project_id>.cloudfunctions.net/sendEmail"
  SERVICE_ACCOUNT_EMAIL: "<member>@<project_id>.iam.gserviceaccount.com"

Pour trouver l'emplacement de la file d'attente, utilisez la commande suivante :

gcloud tasks queues describe my-queue --location=LOCATION

Remplacez LOCATION par l'emplacement de la file d'attente.

Pour trouver l'URL de votre fonction, utilisez la commande suivante :

gcloud functions describe sendEmail

Déployez l'application dans l'environnement standard App Engine à l'aide de la commande suivante :
```
gcloud app deploy
```
Ouvrez l'application pour envoyer un courrier de validation par e-mail :
```
gcloud app browse
```

Effectuer un nettoyage

Une fois le tutoriel terminé, vous pouvez procéder au nettoyage des ressources que vous avez créées afin qu'elles ne soient plus comptabilisées dans votre quota et qu'elles ne vous soient plus facturées. Dans les sections suivantes, nous allons voir comment supprimer ou désactiver ces ressources.

Supprimer des ressources

Vous pouvez nettoyer les ressources que vous avez créées sur Google Cloud afin qu'elles ne soient plus comptabilisées dans votre quota et qu'elles ne vous soient plus facturées. Dans les sections suivantes, nous allons voir comment supprimer ou désactiver ces ressources.

Supprimer la fonction Cloud

Accédez à la page de présentation de Cloud Functions dans la console Google Cloud.

Accéder à la page Cloud Functions
Cochez les cases situées en regard de vos fonctions.
Cliquez sur le bouton Supprimer en haut de la page et confirmez la suppression.

Supprimer la file d'attente Cloud Tasks

Ouvrez la page des files d'attente Cloud Tasks dans la console.

Accéder à la page des files d'attente Cloud Tasks
Sélectionnez le nom de la file d'attente que vous souhaitez supprimer, puis cliquez sur Supprimer la file d'attente.
Confirmez l'opération.

Remarque :Si vous supprimez une file d'attente depuis la console Google Cloud, vous devez attendre sept jours avant de pouvoir recréer une file d'attente portant le même nom.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

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.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Dans la console Google Cloud, accédez à la page Gérer les ressources.
Accéder à la page Gérer les ressources
Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour supprimer le projet.

Étapes suivantes

En savoir plus sur la création de tâches cibles HTTP.
Découvrez comment configurer votre file d'attente Cloud Tasks.