Google ドライブの操作

Action オブジェクトを使用すると、Google Workspace アドオンにインタラクティブな動作を組み込むことができます。アドオンの UI でユーザーがウィジェット（ボタンなど）を操作したときに何が起こるかを定義します。

アクションは、 ウィジェット ハンドラ関数を使用して特定のウィジェットにアタッチされます。 この関数は、アクションをトリガーする条件も定義します。トリガーされると、 アクションは指定された コールバック関数を実行します。 コールバック関数には、ユーザーのクライアントサイドの操作に関する情報を含む イベント オブジェクトが渡されます。コールバック関数を実装して、特定のレスポンス オブジェクトを返す必要があります。

たとえば、クリックすると新しいカードを作成して表示するボタンが必要だとします。これを行うには、新しいボタン ウィジェットを作成し、ボタン ウィジェット ハンドラ関数 setOnClickAction(action) を使用して、カード作成の Actionを設定する必要があります。定義する Action は、ボタンがクリックされたときに実行される Apps Script コールバック関数を指定します。この場合、必要なカードを作成するためにコールバック関数を実装し、 オブジェクトを返します。ActionResponseレスポンス オブジェクトは、コールバック関数で作成されたカードを表示するようにアドオンに指示します。

このページでは、アドオンに含めることができる Google ドライブ固有のウィジェット アクションについて説明します。

ドライブのインタラクション

ドライブを拡張する Google Workspace アドオンには、ドライブ固有のウィジェット アクションを追加できます。このアクションでは、関連する アクション コールバック関数が 特殊なレスポンス オブジェクトを返す必要があります。

試行されたアクション	コールバック関数が返す必要があるもの
選択したファイルのファイル アクセスをリクエストする	DriveItemsSelectedActionResponse

これらのウィジェット アクションとレスポンス オブジェクトを使用するには、次のすべてが当てはまる必要があります。

• ユーザーが 1 つ以上のドライブ アイテムを選択しているときに、アクションがトリガーされる。
• アドオンのマニフェストに https://www.googleapis.com/auth/drive.file ドライブ スコープ が含まれている。

選択したファイルのファイル アクセスをリクエストする

次の例は、ユーザーが 1 つ以上のドライブ アイテムを選択したときにトリガーされるドライブのコンテキスト インターフェースを構築する方法を示しています。この例では、各アイテムをテストして、 アドオンにアクセス権が付与されているかどうかを確認します。付与されていない場合は、 DriveItemsSelectedActionResponse オブジェクトを使用して、ユーザーに権限をリクエストします。アイテムの権限が付与されると、アドオンはそのアイテムのドライブの割り当て使用量を表示します。

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