Ações do Google Drive

Os objetos Action permitem criar um comportamento interativo nos complementos do Google Workspace. Eles definem o que acontece quando um usuário interage com um widget (por exemplo, um botão) na IU de complementos.

Uma ação é anexada a um determinado widget usando uma função de gerenciador 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 transporta informações sobre as interações do lado do cliente do usuário. Implemente a função de callback e faça com que ela retorne um objeto de resposta específico.

Por exemplo, digamos que você queira um botão que gere e exiba um novo cartão quando clicado. Para isso, crie um novo widget de botão e use a função setOnClickAction(action) do gerenciador de botões para definir um Action de criação de cards. A Action definida especifica uma função de callback do Apps Script que é executada quando o botão é clicado. Nesse caso, implemente a função de callback para criar o cartão desejado e retorne um objeto ActionResponse. O objeto de resposta instrui o complemento a exibir o card que foi criado pela função de callback.

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

Interações no Drive

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

Ação realizada	A função de callback vai retornar
Solicitar acesso aos arquivos selecionados	DriveItemsSelectedActionResponse

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

• 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 aos arquivos selecionados

O exemplo a seguir mostra como criar uma interface contextual para o Google Drive que é acionada quando o usuário seleciona um ou mais itens. 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. Quando a permissão é concedida para um item, o complemento mostra o uso da cota dele no Drive.

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