Créer un module complémentaire Google Workspace avec Apps Script

Ce guide de démarrage rapide permet de créer un module complémentaire Google Workspace simple qui illustre pages d'accueil, déclencheurs contextuels et connexion à des API tierces.

Le module complémentaire crée des éléments contextuels et non contextuels dans Gmail, Agenda et Drive. Le module complémentaire affiche une image aléatoire d'un chat avec en superposition sur l'image. Le texte est soit statique pour les pages d'accueil, soit issu de le contexte de l'application hôte pour les déclencheurs contextuels.

Objectifs

  • configurer votre environnement ;
  • Configurez le script.
  • Exécutez le script.

Prérequis

Pour utiliser cet exemple, vous devez remplir les conditions préalables suivantes:

  • Un compte Google (les comptes Google Workspace peuvent nécessitent l'approbation d'un administrateur).

  • Un navigateur Web ayant accès à Internet

  • un projet Google Cloud ;

Configurer votre environnement

Ouvrir votre projet Cloud dans la console Google Cloud

S'il n'est pas déjà ouvert, ouvrez le projet Cloud que vous prévoyez d'utiliser. pour cet exemple:

  1. Dans la console Google Cloud, accédez à la page Sélectionner un projet.

    Sélectionner un projet Cloud

  2. Sélectionnez le projet Google Cloud que vous souhaitez utiliser. Vous pouvez également cliquer sur Créer un projet et suivre les instructions à l'écran. Si vous créez un projet Google Cloud, vous devrez peut-être activer la facturation pour le projet.

Vous devez configurer un écran de consentement pour les modules complémentaires Google Workspace. Configurer l'écran d'autorisation OAuth du module complémentaire définit s'affiche pour les utilisateurs.

  1. Dans la console Google Cloud, accédez au menu . > API et Services > Écran de consentement OAuth.

    Accéder à l'écran de consentement OAuth

  2. Pour Type d'utilisateur, sélectionnez Interne, puis cliquez sur Créer.
  3. Remplissez le formulaire d'inscription de l'application, puis cliquez sur Enregistrer et continuer.

  4. Pour l'instant, vous pouvez ignorer l'ajout de champs d'application et cliquer sur Enregistrer et continuer. Par la suite, lorsque vous créerez une application à utiliser en dehors de votre d'une organisation Google Workspace, vous devez remplacer le Type d'utilisateur par Externe, puis : ajouter les niveaux d'autorisation requis par votre application.

  5. Consultez le récapitulatif d'enregistrement de votre application. Pour y apporter des modifications, cliquez sur Modifier. Si l'application l'inscription vous semble correcte, cliquez sur Retour au tableau de bord.

Configurer le script

Créer le projet Apps Script

  1. Pour créer un projet Apps Script, accédez à script.new.
  2. Cliquez sur Projet sans titre.
  3. Renommez le projet Apps Script Cats, puis cliquez sur Renommer.
  4. À côté du fichier Code.gs, cliquez sur Plus . > Renommer. Nommez le fichier Common.
  5. Cliquez sur Ajouter un fichier . > Script. Nommez le fichier Gmail.
  6. Répétez l'étape 5 pour créer deux autres fichiers de script nommés Calendar et Drive. Lorsque vous avez terminé, vous devez disposer de quatre fichiers de script distincts.

  7. Remplacez le contenu de chaque fichier par le code correspondant suivant:

    Common.gs

      /**
 * This simple Google Workspace Add-on shows a random image of a cat in the
 * sidebar. When opened manually (the homepage card), some static text is
 * overlayed on the image, but when contextual cards are opened a new cat image
 * is shown with the text taken from that context (such as a message's subject
 * line) overlaying the image. There is also a button that updates the card with
 * a new random cat image.
 *
 * Click "File > Make a copy..." to copy the script, and "Publish > Deploy from
 * manifest > Install add-on" to install it.
 */

/**
 * The maximum number of characters that can fit in the cat image.
 */
var MAX_MESSAGE_LENGTH = 40;

/**
 * Callback for rendering the homepage card.
 * @return {CardService.Card} The card to show to the user.
 */
function onHomepage(e) {
  console.log(e);
  var hour = Number(Utilities.formatDate(new Date(), e.userTimezone.id, 'H'));
  var message;
  if (hour >= 6 && hour < 12) {
    message = 'Good morning';
  } else if (hour >= 12 && hour < 18) {
    message = 'Good afternoon';
  } else {
    message = 'Good night';
  }
  message += ' ' + e.hostApp;
  return createCatCard(message, true);
}

/**
 * Creates a card with an image of a cat, overlayed with the text.
 * @param {String} text The text to overlay on the image.
 * @param {Boolean} isHomepage True if the card created here is a homepage;
 *      false otherwise. Defaults to false.
 * @return {CardService.Card} The assembled card.
 */
function createCatCard(text, isHomepage) {
  // Explicitly set the value of isHomepage as false if null or undefined.
  if (!isHomepage) {
    isHomepage = false;
  }

  // Use the "Cat as a service" API to get the cat image. Add a "time" URL
  // parameter to act as a cache buster.
  var now = new Date();
  // Replace forward slashes in the text, as they break the CataaS API.
  var caption = text.replace(/\//g, ' ');
  var imageUrl =
      Utilities.formatString('https://cataas.com/cat/says/%s?time=%s',
          encodeURIComponent(caption), now.getTime());
  var image = CardService.newImage()
      .setImageUrl(imageUrl)
      .setAltText('Meow')

  // Create a button that changes the cat image when pressed.
  // Note: Action parameter keys and values must be strings.
  var action = CardService.newAction()
      .setFunctionName('onChangeCat')
      .setParameters({text: text, isHomepage: isHomepage.toString()});
  var button = CardService.newTextButton()
      .setText('Change cat')
      .setOnClickAction(action)
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED);
  var buttonSet = CardService.newButtonSet()
      .addButton(button);

  // Create a footer to be shown at the bottom.
  var footer = CardService.newFixedFooter()
      .setPrimaryButton(CardService.newTextButton()
          .setText('Powered by cataas.com')
          .setOpenLink(CardService.newOpenLink()
              .setUrl('https://cataas.com')));

  // Assemble the widgets and return the card.
  var section = CardService.newCardSection()
      .addWidget(image)
      .addWidget(buttonSet);
  var card = CardService.newCardBuilder()
      .addSection(section)
      .setFixedFooter(footer);

  if (!isHomepage) {
    // Create the header shown when the card is minimized,
    // but only when this card is a contextual card. Peek headers
    // are never used by non-contexual cards like homepages.
    var peekHeader = CardService.newCardHeader()
      .setTitle('Contextual Cat')
      .setImageUrl('https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png')
      .setSubtitle(text);
    card.setPeekCardHeader(peekHeader)
  }

  return card.build();
}

/**
 * Callback for the "Change cat" button.
 * @param {Object} e The event object, documented {@link
 *     https://developers.google.com/gmail/add-ons/concepts/actions#action_event_objects
 *     here}.
 * @return {CardService.ActionResponse} The action response to apply.
 */
function onChangeCat(e) {
  console.log(e);
  // Get the text that was shown in the current cat image. This was passed as a
  // parameter on the Action set for the button.
  var text = e.parameters.text;

  // The isHomepage parameter is passed as a string, so convert to a Boolean.
  var isHomepage = e.parameters.isHomepage === 'true';

  // Create a new card with the same text.
  var card = createCatCard(text, isHomepage);

  // Create an action response that instructs the add-on to replace
  // the current card with the new one.
  var navigation = CardService.newNavigation()
      .updateCard(card);
  var actionResponse = CardService.newActionResponseBuilder()
      .setNavigation(navigation);
  return actionResponse.build();
}

/**
 * Truncate a message to fit in the cat image.
 * @param {string} message The message to truncate.
 * @return {string} The truncated message.
 */
function truncate(message) {
  if (message.length > MAX_MESSAGE_LENGTH) {
    message = message.slice(0, MAX_MESSAGE_LENGTH);
    message = message.slice(0, message.lastIndexOf(' ')) + '...';
  }
  return message;
}

    Gmail.gs

      /**
 * Callback for rendering the card for a specific Gmail message.
 * @param {Object} e The event object.
 * @return {CardService.Card} The card to show to the user.
 */
function onGmailMessage(e) {
  console.log(e);
  // Get the ID of the message the user has open.
  var messageId = e.gmail.messageId;

  // Get an access token scoped to the current message and use it for GmailApp
  // calls.
  var accessToken = e.gmail.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  // Get the subject of the email.
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getThread().getFirstMessageSubject();

  // Remove labels and prefixes.
  subject = subject
      .replace(/^([rR][eE]|[fF][wW][dD])\:\s*/, '')
      .replace(/^\[.*?\]\s*/, '');

  // If neccessary, truncate the subject to fit in the image.
  subject = truncate(subject);

  return createCatCard(subject);
}

/**
 * Callback for rendering the card for the compose action dialog.
 * @param {Object} e The event object.
 * @return {CardService.Card} The card to show to the user.
 */
function onGmailCompose(e) {
  console.log(e);
  var header = CardService.newCardHeader()
      .setTitle('Insert cat')
      .setSubtitle('Add a custom cat image to your email message.');
  // Create text input for entering the cat's message.
  var input = CardService.newTextInput()
      .setFieldName('text')
      .setTitle('Caption')
      .setHint('What do you want the cat to say?');
  // Create a button that inserts the cat image when pressed.
  var action = CardService.newAction()
      .setFunctionName('onGmailInsertCat');
  var button = CardService.newTextButton()
      .setText('Insert cat')
      .setOnClickAction(action)
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED);
  var buttonSet = CardService.newButtonSet()
      .addButton(button);
  // Assemble the widgets and return the card.
  var section = CardService.newCardSection()
      .addWidget(input)
      .addWidget(buttonSet);
  var card = CardService.newCardBuilder()
      .setHeader(header)
      .addSection(section);
  return card.build();
}

/**
 * Callback for inserting a cat into the Gmail draft.
 * @param {Object} e The event object.
 * @return {CardService.UpdateDraftActionResponse} The draft update response.
 */
function onGmailInsertCat(e) {
  console.log(e);
  // Get the text that was entered by the user.
  var text = e.formInput.text;
  // Use the "Cat as a service" API to get the cat image. Add a "time" URL
  // parameter to act as a cache buster.
  var now = new Date();
  var imageUrl = 'https://cataas.com/cat';
  if (text) {
    // Replace forward slashes in the text, as they break the CataaS API.
    var caption = text.replace(/\//g, ' ');
    imageUrl += Utilities.formatString('/says/%s?time=%s',
        encodeURIComponent(caption), now.getTime());
  }
  var imageHtmlContent = '<img style="display: block; max-height: 300px;" src="'
      + imageUrl + '"/>';
  var response = CardService.newUpdateDraftActionResponseBuilder()
      .setUpdateDraftBodyAction(CardService.newUpdateDraftBodyAction()
          .addUpdateContent(imageHtmlContent,CardService.ContentType.MUTABLE_HTML)
          .setUpdateType(CardService.UpdateDraftBodyType.IN_PLACE_INSERT))
      .build();
  return response;
}

    Calendar.gs

      /**
 * Callback for rendering the card for a specific Calendar event.
 * @param {Object} e The event object.
 * @return {CardService.Card} The card to show to the user.
 */
function onCalendarEventOpen(e) {
  console.log(e);
  var calendar = CalendarApp.getCalendarById(e.calendar.calendarId);
  // The event metadata doesn't include the event's title, so using the
  // calendar.readonly scope and fetching the event by it's ID.
  var event = calendar.getEventById(e.calendar.id);
  if (!event) {
    // This is a new event still being created.
    return createCatCard('A new event! Am I invited?');
  }
  var title = event.getTitle();
  // If necessary, truncate the title to fit in the image.
  title = truncate(title);
  return createCatCard(title);
}

    Drive.gs

      /**
 * Callback for rendering the card for specific Drive items.
 * @param {Object} e The event object.
 * @return {CardService.Card} The card to show to the user.
 */
function onDriveItemsSelected(e) {
  console.log(e);
  var items = e.drive.selectedItems;
  // Include at most 5 items in the text.
  items = items.slice(0, 5);
  var text = items.map(function(item) {
    var title = item.title;
    // If neccessary, truncate the title to fit in the image.
    title = truncate(title);
    return title;
  }).join('\n');
  return createCatCard(text);
}

  8. Cliquez sur Paramètres du projet Icône des paramètres du projet.

  9. Cochez la case Afficher "appsscript.json" dans la zone de l'éditeur.

  10. Cliquez sur Éditeur .

  11. Ouvrez le fichier appsscript.json et remplacez le contenu par ce qui suit puis cliquez sur Enregistrer Icône Enregistrer.

    appsscript.json

       {
  "timeZone": "America/New_York",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "oauthScopes": [
    "https://www.googleapis.com/auth/calendar.addons.execute",
    "https://www.googleapis.com/auth/calendar.readonly",
    "https://www.googleapis.com/auth/drive.addons.metadata.readonly",
    "https://www.googleapis.com/auth/gmail.addons.current.action.compose",
    "https://www.googleapis.com/auth/gmail.addons.current.message.readonly",
    "https://www.googleapis.com/auth/gmail.addons.execute",
    "https://www.googleapis.com/auth/script.locale"],
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Cats",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true,
      "homepageTrigger": {
        "runFunction": "onHomepage",
        "enabled": true
      },
      "universalActions": [{
        "label": "Learn more about Cataas",
        "openLink": "https://cataas.com"
      }]
    },
    "gmail": {
      "contextualTriggers": [{
        "unconditional": {
        },
        "onTriggerFunction": "onGmailMessage"
      }],
      "composeTrigger": {
        "selectActions": [{
          "text": "Insert cat",
          "runFunction": "onGmailCompose"
        }],
        "draftAccess": "NONE"
      }
    },
    "drive": {
      "onItemsSelectedTrigger": {
        "runFunction": "onDriveItemsSelected"
      }
    },
    "calendar": {
      "eventOpenTrigger": {
        "runFunction": "onCalendarEventOpen"
      }
    }
  }
}

Copier le numéro du projet Cloud

  1. Dans la console Google Cloud, accédez au menu . &gt; IAM et Administrateur &gt; Paramètres.

    Accéder à la page Paramètres de la section IAM et administration

  2. Dans le champ Numéro du projet, copiez la valeur.

Définir le projet Cloud du projet Apps Script

  1. Dans votre projet Apps Script, Cliquez sur Paramètres du projet Icône des paramètres du projet.
  2. Sous Projet Google Cloud Platform (GCP), cliquez sur Changer de projet.
  3. Dans Numéro de projet GCP, collez le numéro de projet Google Cloud.
  4. Cliquez sur Définir un projet.

Installer un déploiement test

  1. Dans votre projet Apps Script, cliquez sur Éditeur.
  2. Cliquez sur Déployer &gt; Tester les déploiements.
  3. Cliquez sur Installer &gt; OK.

Exécuter le script

  1. Accédez à Gmail.
  2. Pour ouvrir le module complémentaire, cliquez sur Chats .
  3. Si vous y êtes invité, autorisez le module complémentaire.
  4. Le module complémentaire affiche une image et du texte de chat. Pour modifier cliquez sur Changer de chat.
  5. Si vous ouvrez un e-mail alors que le module complémentaire est ouvert, le L'image est actualisée et le texte affiché dans l'objet de l'e-mail (tronquée s'il est trop long).

Vous pouvez voir des fonctionnalités similaires dans Agenda et Drive. Vous n'avez pas besoin d'autoriser à nouveau un module complémentaire pour l'utiliser dans ces applications hôtes.

Étapes suivantes