Actions Google Drive

Les objets Action vous permettent d'intégrer un comportement interactif dans les modules complémentaires Google Workspace. Ils définissent ce qui se passe lorsqu'un utilisateur interagit avec un widget (par exemple, un bouton) dans l'UI du module complémentaire.

Une action est associée à un widget donné à l'aide d'une fonction de gestionnaire de widget, qui définit également la condition qui déclenche l'action. Lorsqu'elle est déclenchée, l'action exécute une fonction de rappel désignée. La fonction de rappel reçoit un objet d'événement contenant des informations sur les interactions côté client de l'utilisateur. Vous devez implémenter la fonction de rappel et la faire renvoyer un objet de réponse spécifique.

Par exemple, imaginons que vous souhaitiez un bouton qui crée et affiche une nouvelle fiche lorsqu'il est cliqué. Pour ce faire, vous devez créer un widget de bouton et utiliser la fonction de gestionnaire de widget de bouton setOnClickAction(action) pour définir un Action de création de cartes. Le Action que vous définissez spécifie une fonction de rappel Apps Script qui s'exécute lorsque l'utilisateur clique sur le bouton. Dans ce cas, vous implémentez la fonction de rappel pour créer la carte souhaitée et renvoyer un objet ActionResponse. L'objet de réponse indique au module complémentaire d'afficher la fiche créée par la fonction de rappel.

Cette page décrit les actions de widget spécifiques à Google Drive que vous pouvez inclure dans votre module complémentaire.

Générer des interactions

Les modules complémentaires Google Workspace qui étendent Drive peuvent inclure une action de widget supplémentaire spécifique à Drive. Cette action nécessite que la fonction de rappel de l'action associée renvoie un objet de réponse spécialisé :

Action tentée La fonction de rappel doit renvoyer
Demander l'accès aux fichiers sélectionnés DriveItemsSelectedActionResponse

Pour utiliser ces actions de widget et ces objets de réponse, toutes les conditions suivantes doivent être remplies :

  • L'action est déclenchée lorsque l'utilisateur a sélectionné un ou plusieurs éléments Drive.
  • Le module complémentaire inclut le https://www.googleapis.com/auth/drive.file champ d'application Drive dans son fichier manifeste.

Demander l'accès aux fichiers sélectionnés

L'exemple suivant montre comment créer une interface contextuelle pour Drive qui se déclenche lorsque l'utilisateur sélectionne un ou plusieurs éléments Drive. L'exemple teste chaque élément pour voir si l'autorisation d'accès a été accordée au module complémentaire. Si ce n'est pas le cas, il utilise un objet DriveItemsSelectedActionResponse pour demander cette autorisation à l'utilisateur. Une fois l'autorisation accordée pour un élément, le module complémentaire affiche l'utilisation du quota Drive de cet élément.

/**
 * Builds a card that checks selected items' quota usage. Checking
 * quota usage requires user-permissions, so this
 * add-on provides a button to request
 * `drive.file` scope for items the add-on
 * doesn't yet have permission to access.
 *
 * @param e The event object passed containing contextual information about
 *    the Drive items selected.
 * @return {Card}
 */
function onDriveItemsSelected(e) {
  var builder =  CardService.newCardBuilder();

  // For each item the user has selected in Drive, display
  // either its quota information or a button that lets the user provide
  // permission to access that file to retrieve its quota details.
  e['drive']['selectedItems'].forEach(
    function(item){
      var cardSection = CardService.newCardSection()
          .setHeader(item['title']);

      // This add-on uses the recommended, limited-permission `drive.file`
      // scope to get granular per-file access permissions.
      // See: https://developers.google.com/drive/api/v2/about-auth
      if (item['addonHasFileScopePermission']) {
        // If the add-on has access permission, read and display its
        // quota.
        cardSection.addWidget(
          CardService.newTextParagraph().setText(
              "This file takes up: " + getQuotaBytesUsed(item['id'])));
      } else {
        // If the add-on doesn't have access permission, add a button
        // that lets the user provide that permission on a per-file
        // basis.
        cardSection.addWidget(
          CardService.newTextParagraph().setText(
              "The add-on needs permission to access this file's quota."));

        var buttonAction = CardService.newAction()
          .setFunctionName("onRequestFileScopeButtonClicked")
          .setParameters({id: item.id});

        var button = CardService.newTextButton()
          .setText("Request permission")
          .setOnClickAction(buttonAction);

        cardSection.addWidget(button);
      }

      builder.addSection(cardSection);
    });

  return builder.build();
}

/**
 * Callback function for a button action. Instructs Drive to
 * display a permissions dialog to the user, requesting `drive.file` scope
 * for a specific item on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the item's
 *   Drive ID.
 * @return {DriveItemsSelectedActionResponse}
 */
function onRequestFileScopeButtonClicked (e) {
  var idToRequest = e.parameters.id;
  return CardService.newDriveItemsSelectedActionResponseBuilder()
      .requestFileScope(idToRequest).build();
}

/**
 * Use the Advanced Drive Service (See
 * https://developers.google.com/apps-script/advanced/drive), with
 * `drive.file` scope permissions to request the quota usage of a specific
 * Drive item.
 *
 * @param {string} itemId The ID of the item to check.
 * @return {string} A description of the item's quota usage, in bytes.
 */
function getQuotaBytesUsed(itemId) {
  try {
    return Drive.Files.get(itemId,{fields: "quotaBytesUsed"})
        .quotaBytesUsed + " bytes";
  } catch (e) {
    return "Error fetching how much quota this item uses. Error: " + e;
  }
}