Google Drive-Aktionen

Mit Action-Objekten können Sie interaktive Funktionen in Google Workspace-Add‑ons einbauen. Sie definieren, was passiert, wenn ein Nutzer mit einem Widget (z. B. einer Schaltfläche) in der Add-on-Benutzeroberfläche interagiert.

Eine Aktion wird einem bestimmten Widget mithilfe einer Widget-Handler-Funktion zugewiesen, die auch die Bedingung definiert, die die Aktion auslöst. Wenn sie ausgelöst wird, führt die Aktion eine bestimmte Callback-Funktion aus. An die Callback-Funktion wird ein Ereignisobjekt übergeben, das Informationen zu den clientseitigen Interaktionen des Nutzers enthält. Sie müssen die Callback-Funktion implementieren und ein bestimmtes Antwortobjekt zurückgeben lassen.

Angenommen, Sie möchten eine Schaltfläche, die beim Klicken eine neue Karte erstellt und anzeigt. Dazu müssen Sie ein neues Schaltflächen-Widget erstellen und die Handler-Funktion des Schaltflächen-Widgets setOnClickAction(action) verwenden, um ein Action für das Erstellen von Karten festzulegen. Mit dem von Ihnen definierten Action wird eine Apps Script-Callback-Funktion angegeben, die ausgeführt wird, wenn auf die Schaltfläche geklickt wird. In diesem Fall implementieren Sie die Callback-Funktion, um die gewünschte Karte zu erstellen, und geben ein ActionResponse-Objekt zurück. Das Antwortobjekt weist das Add-on an, die Karte anzuzeigen, die von der Callback-Funktion erstellt wurde.

Auf dieser Seite werden Drive-spezifische Widget-Aktionen beschrieben, die Sie in Ihr Add-on einfügen können.

Interaktionen fördern

Google Workspace-Add‑ons, die Drive erweitern, können eine zusätzliche Drive-spezifische Widget-Aktion enthalten. Für diese Aktion muss die zugehörige Rückruffunktion ein spezielles Antwortobjekt zurückgeben:

Versuchte Aktion Die Callback-Funktion sollte zurückgeben
Dateizugriff für ausgewählte Dateien anfordern DriveItemsSelectedActionResponse

Damit Sie diese Widget-Aktionen und Antwortobjekte nutzen können, müssen alle folgenden Bedingungen erfüllt sein:

  • Die Aktion wird ausgelöst, wenn der Nutzer mindestens ein Drive-Element ausgewählt hat.
  • Das Add-on enthält den Drive-Bereich https://www.googleapis.com/auth/drive.file in seinem Manifest.

Dateizugriff für ausgewählte Dateien anfordern

Das folgende Beispiel zeigt, wie Sie eine kontextbezogene Benutzeroberfläche für Google Drive erstellen, die ausgelöst wird, wenn der Nutzer ein oder mehrere Drive-Elemente auswählt. Im Beispiel wird für jedes Element geprüft, ob dem Add-on die Zugriffsberechtigung erteilt wurde. Wenn nicht, wird ein DriveItemsSelectedActionResponse-Objekt verwendet, um diese Berechtigung vom Nutzer anzufordern. Sobald die Berechtigung für ein Element erteilt wurde, zeigt das Add-on die Drive-Kontingentnutzung dieses Elements an.

/**
 * Build a simple 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 allows the user to 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 does not have access permission, add a button
        // that allows the user to 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;
  }
}