Ações do Google Drive

Com os objetos Action, é possível criar um comportamento interativo em complementos do Google Workspace. Eles definem o que acontece quando um usuário interage com um widget (por exemplo, um botão) na interface do complemento.

Uma ação é anexada a um determinado widget usando uma função de manipulador de widget, que também define a condição que aciona a ação. Quando acionada, a ação executa uma função de callback designada. A função de callback recebe um objeto de evento que contém informações sobre as interações do usuário no lado do cliente. Você precisa implementar a função de callback e fazer com que ela retorne um objeto de resposta específico.

Por exemplo, digamos que você queira um botão que crie e mostre um novo card quando clicado. Para isso, crie um novo widget de botão e use a função setOnClickAction(action) do gerenciador de widget de botão para definir um Action de criação de ficha de informações. O Action que você define especifica uma função de callback do Apps Script que é executada quando o botão é clicado. Nesse caso, você implementa a função de callback para criar o card desejado e retorna um objeto ActionResponse. O objeto de resposta informa ao complemento para mostrar o card criado pela função de callback.

Esta página descreve ações de widgets específicas do Google Drive que você pode incluir no seu complemento.

Incentivar interações

Os complementos do Google Workspace que estendem o Drive podem incluir uma ação de widget específica do Drive. Essa ação exige que a função de callback associada retorne um objeto de resposta especializado:

Ação tentada A função de callback precisa retornar
Solicitar acesso a arquivos selecionados DriveItemsSelectedActionResponse

Para usar essas ações de widget e objetos de resposta, todas as condições a seguir precisam ser verdadeiras:

  • A ação é acionada enquanto o usuário tem um ou mais itens do Drive selecionados.
  • O complemento inclui o https://www.googleapis.com/auth/drive.file escopo do Drive no manifesto.

Solicitar acesso a arquivos selecionados

O exemplo a seguir mostra como criar uma interface contextual para o Drive que é acionada quando o usuário seleciona um ou mais itens do Drive. O exemplo testa cada item para ver se o complemento recebeu permissão de acesso. Caso contrário, ele usa um objeto DriveItemsSelectedActionResponse para solicitar essa permissão ao usuário. Depois que a permissão é concedida para um item, o complemento mostra o uso da cota do Drive desse item.

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