Google Drive-Aktionen

Action-Objekten können Sie interaktives Verhalten 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-UI interagiert.

Eine Aktion wird mit einer Widget-Handler-Funktion an ein bestimmtes Widget angehängt, die auch die Bedingung definiert, die die Aktion auslöst. Wenn die Aktion ausgelöst wird, führt sie eine bestimmte Callback-Funktionaus. Der 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, mit der beim Klicken eine neue Karte erstellt und angezeigt wird. Dazu müssen Sie ein neues Schaltflächen-Widget erstellen und mit der Schaltflächen-Widget Handler-Funktion setOnClickAction(action) eine Karte erstellende Action festlegen. Die Action von Ihnen definierte gibt eine Apps Script Callback-Funktion an, 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 ein ActionResponse Objekt zurückzugeben. Das Antwortobjekt weist das Add‑on an, die von der Callback-Funktion erstellte Karte anzuzeigen.

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

Drive-Interaktionen

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 Aktions-Callback-Funktion ein spezielles Antwortobjekt zurückgeben:

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

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

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

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 mindestens ein Drive-Element auswählt. Im Beispiel wird für jedes Element geprüft, ob dem Add‑on die Zugriffsberechtigung gewährt wurde. Wenn nicht, wird mit einem DriveItemsSelectedActionResponse Objekt die Berechtigung vom Nutzer angefordert. Sobald die Berechtigung für ein Element gewährt wurde, zeigt das Add‑on die Drive-Kontingentnutzung für dieses Element 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;
  }
}