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 einem bestimmten Widget mithilfe einer Widget-Handler-Funktion, die auch die Bedingung definiert, die die Aktion auslöst, zugewiesen. 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, die beim Klicken eine neue Karte erstellt und anzeigt. 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 Google 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 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 den https://www.googleapis.com/auth/drive.file Drive-Bereich in seinem Manifest.

Dateizugriff für ausgewählte Dateien anfordern

Das folgende Beispiel zeigt, wie Sie eine kontextbezogene Benutzeroberfläche für 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 erteilt wurde. Wenn nicht, wird mit einem DriveItemsSelectedActionResponse Objekt die Berechtigung vom Nutzer angefordert. Sobald die Berechtigung für ein Element erteilt wurde, zeigt das Add‑on die Drive-Kontingentnutzung dieses Elements an.

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