액션 독려

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