Google 云端硬盘操作

借助 Action 对象，您可以为 Google Workspace 插件构建互动行为。它们定义了当用户与插件界面中的 widget（例如按钮）互动时会发生什么。

操作通过 widget 处理函数附加到给定的 widget，该函数还定义了触发操作的条件。触发后，操作会执行指定的回调函数。系统会向回调函数传递一个事件对象，其中包含有关用户客户端互动的信息。您必须实现回调函数，并让其返回特定的响应对象。

例如，假设您想要一个按钮，当点击该按钮时，系统会构建并显示一张新卡片。为此，您必须创建一个新的按钮微件，并使用按钮微件处理程序函数 setOnClickAction(action) 设置卡片构建器 Action。您定义的 Action 用于指定在点击按钮时执行的 Apps 脚本回调函数。在这种情况下，您需要实现回调函数来构建所需的卡片，并返回 ActionResponse 对象。响应对象会告知插件显示回调函数构建的卡片。

本页介绍了您可以在插件中添加的特定于 Google 云端硬盘的 widget 操作。

促成互动

扩展云端硬盘的 Google Workspace 插件可以包含额外的云端硬盘专用 widget 操作。此操作需要关联的操作回调函数返回一个专门的响应对象：

尝试执行的操作 回调函数应返回
为所选文件申请文件访问权限 DriveItemsSelectedActionResponse

如需使用这些 widget 操作和响应对象，必须满足以下所有条件：

  • 当用户选择了一个或多个云端硬盘项目时，系统会触发该操作。
  • 该插件在其清单中包含 https://www.googleapis.com/auth/drive.file Drive 范围。

为所选文件请求文件访问权限

以下示例展示了如何为 Google 云端硬盘构建一个上下文界面，当用户选择一个或多个 Google 云端硬盘项目时，该界面会触发。该示例会测试每个项目，以查看插件是否已获得访问权限；如果未获得，则使用 DriveItemsSelectedActionResponse 对象向用户请求该权限。为某个项目授予权限后，该插件会显示该项目的云端硬盘配额使用情况。

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