Các thao tác trên Google Drive

Các đối tượng Action cho phép bạn tạo hành vi tương tác trong các tiện ích bổ sung của Google Workspace. Chúng xác định những gì xảy ra khi người dùng tương tác với một tiện ích (ví dụ: nút) trong giao diện người dùng của tiện ích bổ sung.

Một thao tác được đính kèm vào một tiện ích nhất định bằng cách sử dụng hàm trình xử lý tiện ích, hàm này cũng xác định điều kiện kích hoạt thao tác. Khi được kích hoạt, thao tác này sẽ thực thi một hàm callback được chỉ định. Hàm callback được truyền một đối tượng sự kiện mang thông tin về các hoạt động tương tác phía máy khách của người dùng. Bạn phải triển khai hàm callback và yêu cầu hàm này trả về một đối tượng phản hồi cụ thể.

Ví dụ: giả sử bạn muốn một nút tạo và hiển thị thẻ mới khi được nhấp vào. Để làm được điều này, bạn phải tạo một tiện ích nút mới và sử dụng hàm trình xử lý tiện ích nút setOnClickAction(action) để đặt Action tạo thẻ. Action mà bạn xác định sẽ chỉ định một hàm callback Apps Script thực thi khi người dùng nhấp vào nút. Trong trường hợp này, bạn sẽ triển khai hàm callback để tạo thẻ mà bạn muốn và trả về một đối tượng ActionResponse. Đối tượng phản hồi yêu cầu tiện ích bổ sung hiển thị thẻ mà hàm gọi lại đã tạo.

Trang này mô tả các thao tác cụ thể của tiện ích trên Google Drive mà bạn có thể đưa vào tiện ích bổ sung.

Lượt tương tác trên Drive

Các tiện ích bổ sung của Google Workspace mở rộng Drive có thể bao gồm một thao tác tiện ích bổ sung dành riêng cho Drive. Thao tác này yêu cầu hàm callback của thao tác được liên kết trả về một đối tượng phản hồi chuyên biệt:

Hành động đã thực hiện Hàm callback sẽ trả về
Yêu cầu quyền truy cập vào tệp đối với các tệp đã chọn DriveItemsSelectedActionResponse

Để sử dụng các thao tác tiện ích và đối tượng phản hồi này, tất cả các điều kiện sau đây đều phải đúng:

  • Thao tác này được kích hoạt khi người dùng chọn một hoặc nhiều mục trên Drive.
  • Tiện ích bổ sung này có https://www.googleapis.com/auth/drive.file phạm vi Drive trong tệp kê khai.

Yêu cầu quyền truy cập vào các tệp đã chọn

Ví dụ sau đây cho thấy cách tạo một giao diện theo ngữ cảnh cho Drive được kích hoạt khi người dùng chọn một hoặc nhiều mục trên Drive. Ví dụ này kiểm tra từng mục để xem liệu tiện ích bổ sung đã được cấp quyền truy cập hay chưa; nếu chưa, tiện ích bổ sung sẽ sử dụng đối tượng DriveItemsSelectedActionResponse để yêu cầu người dùng cấp quyền đó. Sau khi bạn cấp quyền cho một mục, tiện ích bổ sung sẽ hiển thị mức sử dụng hạn mức Drive của mục đó.

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