액션 독려

Action 객체를 사용하면 Google Workspace 부가기능에 대화형 동작을 빌드할 수 있습니다. 이러한 핸들러는 사용자가 부가기능 UI에서 위젯 (예: 버튼)과 상호작용할 때 발생하는 작업을 정의합니다.

작업은 위젯 핸들러 함수를 사용하여 지정된 위젯에 연결되며, 이 함수는 작업을 트리거하는 조건도 정의합니다. 트리거되면 작업이 지정된 콜백 함수를 실행합니다. 콜백 함수에는 사용자의 클라이언트 측 상호작용에 관한 정보를 전달하는 이벤트 객체가 전달됩니다. 콜백 함수를 구현하고 특정 응답 객체를 반환하도록 해야 합니다.

예를 들어 클릭하면 새 카드를 빌드하고 표시하는 버튼을 원한다고 가정해 보겠습니다. 이를 위해 새 버튼 위젯을 만들고 버튼 위젯 핸들러 함수 setOnClickAction(action)를 사용하여 카드 빌드 Action를 설정해야 합니다. 정의한 Action은 버튼을 클릭할 때 실행되는 Apps Script 콜백 함수를 지정합니다. 이 경우 콜백 함수를 구현하여 원하는 카드를 빌드하고 ActionResponse 객체를 반환합니다. 응답 객체는 콜백 함수가 빌드한 카드를 표시하도록 부가기능에 지시합니다.

이 페이지에서는 부가기능에 포함할 수 있는 Drive 전용 위젯 작업을 설명합니다.

상호작용 유도

Drive를 확장하는 Google Workspace 부가기능에는 추가 Drive 전용 위젯 작업이 포함될 수 있습니다. 이 작업을 수행하려면 연결된 작업 콜백 함수가 특수 응답 객체를 반환해야 합니다.

시도된 작업 콜백 함수는 다음을 반환해야 합니다.
선택한 파일에 대한 액세스 권한 요청 DriveItemsSelectedActionResponse

이러한 위젯 작업과 응답 객체를 사용하려면 다음이 모두 충족되어야 합니다.

  • 사용자가 하나 이상의 Drive 항목을 선택한 상태에서 작업이 트리거됩니다.
  • 부가기능의 매니페스트에 https://www.googleapis.com/auth/drive.file 드라이브 범위가 포함되어 있습니다.

선택한 파일에 대한 파일 액세스 권한 요청

다음 예시에서는 사용자가 하나 이상의 Drive 항목을 선택할 때 트리거되는 Google Drive의 컨텍스트 인터페이스를 빌드하는 방법을 보여줍니다. 이 예에서는 각 항목을 테스트하여 부가기능에 액세스 권한이 부여되었는지 확인합니다. 부여되지 않은 경우 DriveItemsSelectedActionResponse 객체를 사용하여 사용자에게 권한을 요청합니다. 항목에 권한이 부여되면 부가기능에 해당 항목의 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;
  }
}