פעולות ב-Google Drive

אובייקטים של Action מאפשרים לכם ליצור התנהגות אינטראקטיבית בתוספים ל-Google Workspace. הם מגדירים מה קורה כשמשתמש מבצע אינטראקציה עם ווידג'ט (לדוגמה, לחצן) בממשק המשתמש של התוסף.

פעולה מצורפת לווידג'ט מסוים באמצעות פונקציית handler של הווידג'ט, שמגדירה גם את התנאי שמפעיל את הפעולה. כשמופעלת פעולה, היא מפעילה פונקציית קריאה חוזרת ייעודית. פונקציית הקריאה החוזרת מקבלת אובייקט אירוע שמכיל מידע על האינטראקציות של המשתמש בצד הלקוח. צריך להטמיע את פונקציית הקריאה החוזרת ולגרום לה להחזיר אובייקט תגובה ספציפי.

לדוגמה, נניח שאתם רוצים לחצן שיוצר ומציג כרטיס חדש כשלוחצים עליו. לשם כך, צריך ליצור ווידג'ט חדש של לחצן ולהשתמש בפונקציית הטיפול של ווידג'ט הלחצן setOnClickAction(action) כדי להגדיר Action לבניית כרטיס. הערך של Action שאתם מגדירים מציין פונקציית קריאה חוזרת של Apps Script שמופעלת כשלוחצים על הלחצן. במקרה כזה, צריך להטמיע את פונקציית הקריאה החוזרת כדי ליצור את הכרטיס הרצוי ולהחזיר אובייקט ActionResponse. אובייקט התגובה אומר לתוסף להציג את הכרטיס שפונקציית הקריאה החוזרת יצרה.

בדף הזה מוסבר על פעולות ספציפיות של ווידג'טים ב-Google Drive שאפשר לכלול בתוסף.

אינטראקציות ב-Drive

תוספים ל-Google Workspace שמרחיבים את Drive יכולים לכלול פעולת ווידג'ט נוספת שספציפית ל-Drive. כדי לבצע את הפעולה הזו, פונקציית הקריאה החוזרת של הפעולה המשויכת צריכה להחזיר אובייקט תגובה מיוחד:

הפעולה שניסית לבצע	פונקציית הקריאה החוזרת צריכה להחזיר
בקשת גישה לקבצים שנבחרו	DriveItemsSelectedActionResponse

כדי להשתמש בפעולות הווידג'ט ובאובייקטים של התגובה, צריך לעמוד בכל התנאים הבאים:

• הפעולה מופעלת כשהמשתמש בוחר פריט אחד או יותר ב-Drive.
• התוסף כולל את https://www.googleapis.com/auth/drive.file היקף הגישה ל-Drive במניפסט שלו.

בקשת גישה לקבצים שנבחרו

בדוגמה הבאה אפשר לראות איך ליצור ממשק לפי הקשר ל-Drive שמופעל כשמשתמש בוחר פריט אחד או יותר ב-Drive. בדוגמה הזו, כל פריט נבדק כדי לראות אם לתוסף ניתנה הרשאת גישה. אם לא, נעשה שימוש באובייקט DriveItemsSelectedActionResponse כדי לבקש את ההרשאה מהמשתמש. אחרי שניתנת הרשאה לפריט, התוסף מציג את השימוש במכסת Drive של הפריט הזה.

/**
 * 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;
  }
}