Copier des macros dans d'autres feuilles de calcul

Niveau de codage: intermédiaire
Durée: 30 minutes
Type de projet: module complémentaire Google Workspace

Objectifs

• Comprendre ce que la solution fait
• Comprendre ce que font les services Apps Script dans la solution
• Configurez l'environnement.
• Configurez le script.
• Exécutez le script.

À propos de cette solution

Copier manuellement des macros Google Sheets d'une feuille de calcul à une autre peut être chronophage et source d'erreurs. Ce module complémentaire Google Workspace copie automatiquement un projet de script et l'associe à une feuille de calcul spécifiée par l'utilisateur. Bien que cette solution soit axée sur les macros Sheets, vous pouvez l'utiliser pour copier et partager n'importe quel script lié à un conteneur.

Fonctionnement

Le script copie le projet Apps Script lié à la feuille de calcul d'origine et crée un projet Apps Script en double lié à la feuille de calcul spécifiée par l'utilisateur.

Services Apps Script

Cette solution utilise les services suivants:

• Service de récupération d'URL : se connecte à l'API Apps Script pour copier le projet source et en créer une copie.
• Service de script : autorise l'API Apps Script à éviter une deuxième invite d'autorisation.
• Service Spreadsheet : ouvre la feuille de calcul cible pour ajouter le projet Apps Script copié.
• Service de carte : crée l'interface utilisateur du module complémentaire.

Prérequis

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

• Un compte Google (l'approbation de l'administrateur peut être nécessaire pour les comptes Google Workspace).

• Un navigateur Web avec accès à Internet

• un projet Google Cloud ;

• L'API Google Apps Script doit être activée dans les paramètres du tableau de bord Apps Script.

Configurer votre environnement

Ouvrez votre projet Cloud dans la console Google Cloud.

Si ce n'est pas déjà fait, 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 ce projet.

Activer l'API Google Apps Script

Ce guide de démarrage rapide utilise l'API Google Apps Script.

Avant d'utiliser les API Google, vous devez les activer dans un projet Google Cloud. Vous pouvez activer une ou plusieurs API dans un même projet Google Cloud.

• Dans votre projet Cloud, activez l'API Google Apps Script.

  Activer l'API

Configurer l'écran d'autorisation OAuth

Les modules complémentaires Google Workspace nécessitent une configuration de l'écran de consentement. La configuration de l'écran de consentement OAuth de votre module complémentaire définit ce que Google affiche aux utilisateurs.

1. Dans la console Google Cloud, accédez à Menu  > > Branding.

   Accéder à "Branding"

2. Si vous avez déjà configuré , vous pouvez configurer les paramètres suivants de l'écran d'autorisation OAuth dans Branding (Marquage), Audience (Audience) et Data Access (Accès aux données). Si le message Pas encore configuré s'affiche, cliquez sur Commencer:
1. Sous Informations sur l'application, dans Nom de l'application, saisissez un nom pour l'application.
2. Dans Adresse e-mail d'assistance utilisateur, choisissez une adresse e-mail d'assistance à laquelle les utilisateurs peuvent vous contacter s'ils ont des questions sur leur consentement.
3. Cliquez sur Suivant.
4. Sous Audience, sélectionnez Interne.
5. Cliquez sur Suivant.
6. Sous Coordonnées, saisissez une adresse e-mail à laquelle vous pourrez être informé de toute modification apportée à votre projet.
7. Cliquez sur Suivant.
8. Sous Terminer, consultez le Règlement sur les données utilisateur dans les services d'API Google et, si vous acceptez, sélectionnez J'accepte le Règlement sur les données utilisateur dans les services d'API Google.
9. Cliquez sur Continuer.
10. Cliquez sur Créer.
3. Pour l'instant, vous pouvez ignorer l'ajout d'autorisations. À l'avenir, lorsque vous créerez une application à utiliser en dehors de votre organisation Google Workspace, vous devrez définir le type d'utilisateur sur Externe. Ajoutez ensuite les champs d'application d'autorisation dont votre application a besoin. Pour en savoir plus, consultez le guide complet Configurer le consentement OAuth.

Configurer le script

Créer le projet Apps Script

1. Cliquez sur le bouton suivant pour ouvrir le projet Apps Script Partager une macro.
   Ouvrir le projet
2. Cliquez sur Vue d'ensemble .
3. Sur la page de présentation, cliquez sur Créer une copie .

Copiez le numéro du projet Cloud

1. Dans la console Google Cloud, accédez à Menu  > IAM et administration > 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 copié, cliquez sur 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 du projet Google Cloud.
4. Cliquez sur Définir un projet.

Installer un déploiement de test

1. Dans votre projet Apps Script copié, cliquez sur Éditeur .
2. Ouvrez le fichier UI.gs, puis cliquez sur Exécuter. Lorsque vous y êtes invité, autorisez le script.
3. Cliquez sur Déployer > Tester les déploiements.
4. Cliquez sur Installer > OK.

Obtenir le script de macro et les informations de la feuille de calcul

1. Ouvrez une feuille de calcul Sheets contenant une macro et que vous êtes autorisé à modifier. Pour utiliser un exemple de feuille de calcul, créez une copie de la feuille de calcul Exemple de macro.
2. Cliquez sur Extensions > Apps Script.
3. Dans le projet Apps Script, cliquez sur Paramètres du projet .
4. Sous l'ID du script, cliquez sur Copier.
5. Mettez l'ID du script de côté pour l'utiliser lors d'une prochaine étape.
6. Ouvrez ou créez une feuille de calcul dans laquelle vous souhaitez ajouter la macro. Vous devez être autorisé à modifier la feuille de calcul.
7. Copiez l'URL de la feuille de calcul et conservez-la pour une utilisation ultérieure.

Exécuter le script

Assurez-vous que l'API Google Apps Script est activée dans les paramètres du tableau de bord. Suivez les étapes des sections suivantes pour exécuter votre script.

Copier la macro

1. Dans Sheets, dans la barre latérale de droite, ouvrez le module complémentaire Partager une macro .
2. Sous Source macro (Macro source), collez l'ID du script.
3. Sous Feuille de calcul cible, collez l'URL de la feuille de calcul.
4. Cliquez sur Partager la macro.
5. Cliquez sur Autoriser l'accès et autorisez le module complémentaire.
6. Répétez les étapes 2 à 4.

Ouvrez la macro copiée.

1. Si ce n'est pas déjà fait, ouvrez la feuille de calcul dans laquelle vous avez copié la macro.
2. Cliquez sur Extensions > Apps Script.
3. Si vous ne voyez pas le projet Apps Script copié, assurez-vous que l'API Google Apps Script est activée dans les paramètres du tableau de bord, puis répétez les étapes indiquées sous Copier la macro.

Examiner le code

Pour consulter le code Apps Script de cette solution, cliquez sur Afficher le code source ci-dessous:

Afficher le code source

Code.gs

solutions/add-on/share-macro/Code.js

Afficher sur GitHub

// To learn how to use this script, refer to the documentation:
// https://developers.devsite.corp.google.com/apps-script/add-ons/share-macro

/*
Copyright 2022 Google LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

/**
 * Uses Apps Script API to copy source Apps Script project 
 * to destination Google Spreadsheet container.
 * 
 * @param {string} sourceScriptId - Script ID of the source project.
 * @param {string} targetSpreadsheetUrl - URL if the target spreadsheet.
 */
function shareMacro_(sourceScriptId, targetSpreadsheetUrl) {

  // Gets the source project content using the Apps Script API.
  const sourceProject = APPS_SCRIPT_API.get(sourceScriptId);
  const sourceFiles = APPS_SCRIPT_API.getContent(sourceScriptId);

  // Opens the target spreadsheet and gets its ID.
  const parentSSId = SpreadsheetApp.openByUrl(targetSpreadsheetUrl).getId();

  // Creates an Apps Script project that's bound to the target spreadsheet.
  const targetProjectObj = APPS_SCRIPT_API.create(sourceProject.title, parentSSId);

  // Updates the Apps Script project with the source project content.
  APPS_SCRIPT_API.updateContent(targetProjectObj.scriptId, sourceFiles);

}

/**
 * Function that encapsulates Apps Script API project manipulation. 
*/
const APPS_SCRIPT_API = {
  accessToken: ScriptApp.getOAuthToken(),

  /* APPS_SCRIPT_API.get
   * Gets Apps Script source project.
   * @param {string} scriptId - Script ID of the source project.
   * @return {Object} - JSON representation of source project.
   */
  get: function (scriptId) {
    const url = ('https://script.googleapis.com/v1/projects/' + scriptId);
    const options = {
      "method": 'get',
      "headers": {
        "Authorization": "Bearer " + this.accessToken
      },
      "muteHttpExceptions": true,
    };
    const res = UrlFetchApp.fetch(url, options);
    if (res.getResponseCode() == 200) {
      return JSON.parse(res);
    } else {
      console.log('An error occurred gettting the project details');
      console.log(res.getResponseCode());
      console.log(res.getContentText());
      console.log(res);
      return false;
    }
  },

  /* APPS_SCRIPT_API.create
   * Creates new Apps Script project in the target spreadsheet.
   * @param {string} title - Name of Apps Script project.
   * @param {string} parentId - Internal ID of target spreadsheet.
   * @return {Object} - JSON representation completed project creation.
   */
  create: function (title, parentId) {
    const url = 'https://script.googleapis.com/v1/projects';
    const options = {
      "headers": {
        "Authorization": "Bearer " + this.accessToken,
        "Content-Type": "application/json"
      },
      "muteHttpExceptions": true,
      "method": "POST",
      "payload": { "title": title }
    }
    if (parentId) {
      options.payload.parentId = parentId;
    }
    options.payload = JSON.stringify(options.payload);
    let res = UrlFetchApp.fetch(url, options);
    if (res.getResponseCode() == 200) {
      res = JSON.parse(res);
      return res;
    } else {
      console.log("An error occurred while creating the project");
      console.log(res.getResponseCode());
      console.log(res.getContentText());
      console.log(res);
      return false;
    }
  },
   /* APPS_SCRIPT_API.getContent
   * Gets the content of the source Apps Script project.
   * @param {string} scriptId - Script ID of the source project.
   * @return {Object} - JSON representation of Apps Script project content.
   */
   getContent: function (scriptId) {
    const url = "https://script.googleapis.com/v1/projects/" + scriptId + "/content";
    const options = {
      "method": 'get',
      "headers": {
        "Authorization": "Bearer " + this.accessToken
      },
      "muteHttpExceptions": true,
    };
    let res = UrlFetchApp.fetch(url, options);
    if (res.getResponseCode() == 200) {
      res = JSON.parse(res);
      return res['files'];
    } else {
      console.log('An error occurred obtaining the content from the source script');
      console.log(res.getResponseCode());
      console.log(res.getContentText());
      console.log(res);
      return false;
    }
  },

  /* APPS_SCRIPT_API.updateContent
   * Updates (copies) content from source to target Apps Script project.
   * @param {string} scriptId - Script ID of the source project.
   * @param {Object} files - JSON representation of Apps Script project content.
   * @return {boolean} - Result status of the function.
   */
  updateContent: function (scriptId, files) {
    const url = "https://script.googleapis.com/v1/projects/" + scriptId + "/content";
    const options = {
      "method": 'put',
      "headers": {
        "Authorization": "Bearer " + this.accessToken
      },
      "contentType": "application/json",
      "payload": JSON.stringify({ "files": files }),
      "muteHttpExceptions": true,
    };
    let res = UrlFetchApp.fetch(url, options);
    if (res.getResponseCode() == 200) {
      return true;
    } else {
      console.log(`An error occurred updating content of script ${scriptId}`);
      console.log(res.getResponseCode());
      console.log(res.getContentText());
      console.log(res);
      return false;
    }
  }
}

UI.gs

solutions/add-on/share-macro/UI.js

Afficher sur GitHub

/**
 * Copyright 2022 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// Change application logo here (and in manifest) as desired.
const ADDON_LOGO = 'https://www.gstatic.com/images/branding/product/2x/apps_script_48dp.png';

/**
 * Callback function for rendering the main card.
 * @return {CardService.Card} The card to show the user.
 */
function onHomepage(e) {
  return createSelectionCard(e);
}

/**
 * Builds the primary card interface used to collect user inputs.
 * 
 * @param {Object} e - Add-on event object.
 * @param {string} sourceScriptId - Script ID of the source project.
 * @param {string} targetSpreadsheetUrl - URL of the target spreadsheet.
 * @param {string[]} errors - Array of error messages. 
 * 
 * @return {CardService.Card} The card to show to the user for inputs.
 */
function createSelectionCard(e, sourceScriptId, targetSpreadsheetUrl, errors) {

  // Configures card header.
  let cardHeader = CardService.newCardHeader()
    .setTitle('Share macros with other spreadheets!')
    .setImageUrl(ADDON_LOGO)
    .setImageStyle(CardService.ImageStyle.SQUARE);

  // If form errors exist, configures section with error messages.
  let showErrors = false;

  if (errors && errors.length) {
    showErrors = true;
    let msg = errors.reduce((str, err) => `${str}• ${err}<br>`, '');
    msg = `<b>Form submission errors:</b><br><font color="#ba0000">${msg}</font>`;

    // Builds error message section.
    sectionErrors = CardService.newCardSection()
      .addWidget(CardService.newDecoratedText()
        .setText(msg)
        .setWrapText(true));
  }

  // Configures source project section.
  let sectionSource = CardService.newCardSection()
    .addWidget(CardService.newDecoratedText()
      .setText('<b>Source macro</b><br>The Apps Script project to copy'))

    .addWidget(CardService.newTextInput()
      .setFieldName('sourceScriptId')
      .setValue(sourceScriptId || '')
      .setTitle('Script ID of the source macro')
      .setHint('You must have at least edit permission for the source spreadsheet to access its script project'))

    .addWidget(CardService.newTextButton()
      .setText('Find the script ID')
      .setOpenLink(CardService.newOpenLink()
        .setUrl('https://developers.google.com/apps-script/api/samples/execute')
        .setOpenAs(CardService.OpenAs.FULL_SIZE)
        .setOnClose(CardService.OnClose.NOTHING)));

  // Configures target spreadsheet section.
  let sectionTarget = CardService.newCardSection()
    .addWidget(CardService.newDecoratedText()
      .setText('<b>Target spreadsheet</b>'))

    .addWidget(CardService.newTextInput()
      .setFieldName('targetSpreadsheetUrl')
      .setValue(targetSpreadsheetUrl || '')
      .setHint('You must have at least edit permission for the target spreadsheet')
      .setTitle('Target spreadsheet URL'));

  // Configures help section.
  let sectionHelp = CardService.newCardSection()
    .addWidget(CardService.newDecoratedText()
      .setText('<b><font color=#c80000>NOTE: </font></b>' +
        'The Apps Script API must be turned on.')
      .setWrapText(true))

    .addWidget(CardService.newTextButton()
      .setText('Turn on Apps Script API')
      .setOpenLink(CardService.newOpenLink()
        .setUrl('https://script.google.com/home/usersettings')
        .setOpenAs(CardService.OpenAs.FULL_SIZE)
        .setOnClose(CardService.OnClose.NOTHING)));

  // Configures card footer with action to copy the macro.
  var cardFooter = CardService.newFixedFooter()
    .setPrimaryButton(CardService.newTextButton()
      .setText('Share macro')
      .setOnClickAction(CardService.newAction()
        .setFunctionName('onClickFunction_')));

  // Begins building the card.
  let builder = CardService.newCardBuilder()
    .setHeader(cardHeader);

  // Adds error section if applicable.
  if (showErrors) {
    builder.addSection(sectionErrors)
  }

  // Adds final sections & footer.
  builder
    .addSection(sectionSource)
    .addSection(sectionTarget)
    .addSection(sectionHelp)
    .setFixedFooter(cardFooter);

  return builder.build();
}

/**
 * Action handler that validates user inputs and calls shareMacro_
 * function to copy Apps Script project to target spreadsheet.
 * 
 * @param {Object} e - Add-on event object.
 * 
 * @return {CardService.Card} Responds with either a success or error card.
 */
function onClickFunction_(e) {

  const sourceScriptId = e.formInput.sourceScriptId;
  const targetSpreadsheetUrl = e.formInput.targetSpreadsheetUrl;

  // Validates inputs for errors.
  const errors = [];

  // Pushes an error message if the Script ID parameter is missing.
  if (!sourceScriptId) {
    errors.push('Missing script ID');
  } else {

    // Gets the Apps Script project if the Script ID parameter is valid.
    const sourceProject = APPS_SCRIPT_API.get(sourceScriptId);
    if (!sourceProject) {
      // Pushes an error message if the Script ID parameter isn't valid.
      errors.push('Invalid script ID');
    }
  }

  // Pushes an error message if the spreadsheet URL is missing.
  if (!targetSpreadsheetUrl) {
    errors.push('Missing Spreadsheet URL');
  } else
    try {
      // Tests for valid spreadsheet URL to get the spreadsheet ID.
      const ssId = SpreadsheetApp.openByUrl(targetSpreadsheetUrl).getId();
    } catch (err) {
      // Pushes an error message if the spreadsheet URL parameter isn't valid.
      errors.push('Invalid spreadsheet URL');
    }

  if (errors && errors.length) {
    // Redisplays form if inputs are missing or invalid.
    return createSelectionCard(e, sourceScriptId, targetSpreadsheetUrl, errors);

  } else {
    // Calls shareMacro function to copy the project.
    shareMacro_(sourceScriptId, targetSpreadsheetUrl);

    // Creates a success card to display to users.
    return buildSuccessCard(e, targetSpreadsheetUrl);
  }
}

/**
 * Builds success card to inform user & let them open the spreadsheet.
 * 
 * @param {Object} e - Add-on event object.
 * @param {string} targetSpreadsheetUrl - URL of the target spreadsheet.
 * 
 * @return {CardService.Card} Returns success card.
 */function buildSuccessCard(e, targetSpreadsheetUrl) {

  // Configures card header.
  let cardHeader = CardService.newCardHeader()
    .setTitle('Share macros with other spreadsheets!')
    .setImageUrl(ADDON_LOGO)
    .setImageStyle(CardService.ImageStyle.SQUARE);

  // Configures card body section with success message and open button.
  let sectionBody1 = CardService.newCardSection()
    .addWidget(CardService.newTextParagraph()
      .setText('Sharing process is complete!'))
    .addWidget(CardService.newTextButton()
      .setText('Open spreadsheet')
      .setOpenLink(CardService.newOpenLink()
        .setUrl(targetSpreadsheetUrl)
        .setOpenAs(CardService.OpenAs.FULL_SIZE)
        .setOnClose(CardService.OnClose.RELOAD_ADD_ON)));
  let sectionBody2 = CardService.newCardSection()
    .addWidget(CardService.newTextParagraph()
      .setText('If you don\'t see the copied project in your target spreadsheet,' +
       ' make sure you turned on the Apps Script API in the Apps Script dashboard.'))
    .addWidget(CardService.newTextButton()
      .setText("Check API")
      .setOpenLink(CardService.newOpenLink()
        .setUrl('https://script.google.com/home/usersettings')
        .setOpenAs(CardService.OpenAs.FULL_SIZE)
        .setOnClose(CardService.OnClose.RELOAD_ADD_ON)));

  // Configures the card footer with action to start new process.
  let cardFooter = CardService.newFixedFooter()
    .setPrimaryButton(CardService.newTextButton()
      .setText('Share another')
      .setOnClickAction(CardService.newAction()
        .setFunctionName('onHomepage')));

  return builder = CardService.newCardBuilder()
    .setHeader(cardHeader)
    .addSection(sectionBody1)
    .addSection(sectionBody2)
    .setFixedFooter(cardFooter)
    .build();
 }

appsscript.json

solutions/add-on/share-macro/appsscript.json

Afficher sur GitHub

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/drive.readonly",
    "https://www.googleapis.com/auth/script.projects"
  ],
    "urlFetchWhitelist": [
    "https://script.googleapis.com/"
  ],
  "addOns": {
    "common": {
      "name": "Share Macro",
      "logoUrl": "https://www.gstatic.com/images/branding/product/2x/apps_script_48dp.png",
      "layoutProperties": {
        "primaryColor": "#188038",
        "secondaryColor": "#34a853"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "sheets": {}
  }
}

Contributeurs

Cet exemple est géré par Google avec l'aide des experts Google pour les développeurs.

Étapes suivantes

• Étendre Google Workspace avec des modules complémentaires
• Créer des modules complémentaires Google Workspace
• Publier une application