편집기 작업

Action 객체를 사용하여 대화형 빌드 Google Workspace 부가기능에 적용될 예정입니다.

사용자가 위젯과 상호작용할 때 발생하는 작업을 정의하는 작업 객체 (예: 버튼)

위젯에 작업 추가

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

예: 버튼을 클릭하면 새 카드 표시

부가기능에 새 카드를 빌드하고 표시하는 버튼을 추가하려는 경우 클릭하여 다음 단계를 따르세요.

1. 버튼 widget을 만듭니다.
2. 카드 빌드 작업을 설정하려면 버튼 위젯 핸들러 함수를 추가합니다. setOnClickAction(action)
3. 실행할 Apps Script 콜백 함수를 만들고 이를 (action) 드림 필요합니다. 이 경우 콜백 함수는 원하는 카드를 빌드하고 ActionResponse 객체를 반환해야 합니다. 응답 객체는 콜백 함수가 빌드한 카드를 표시하도록 부가기능에 지시합니다.

다음 예는 버튼 위젯을 만드는 방법을 보여줍니다. 작업은 부가기능을 대신하여 현재 파일의 drive.file 범위입니다.

/**
 * Adds a section to the Card Builder that displays a "REQUEST PERMISSION" button.
 * When it's clicked, the callback triggers file scope permission flow. This is used in
 * the add-on when the home-page displays basic data.
 */
function addRequestFileScopeButtonToBuilder(cardBuilder) {
    var buttonSection = CardService.newCardSection();
    // 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.
    var buttonAction = CardService.newAction()
      .setFunctionName("onRequestFileScopeButtonClickedInEditor");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setBackgroundColor("#4285f4")
      .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
      .setOnClickAction(buttonAction);

    buttonSection.addWidget(button);
    cardBuilder.addSection(buttonSection);
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the 
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClickedInEditor(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();

REST API의 파일 액세스 상호작용

편집기를 확장하고 REST API를 사용하는 Google Workspace 부가기능에는 파일 액세스를 요청하는 추가 위젯 작업입니다. 이 작업을 수행하려면 연결된 작업 콜백 함수를 사용하여 특수 응답 객체를 반환합니다.

시도한 작업	콜백 함수가 반환해야 함
current_document 파일 액세스 요청	EditorFileScopeActionResponse

이 위젯 작업 및 응답 객체를 사용하려면 다음 사항이 모두 충족되어야 합니다. true여야 합니다.

• 이 부가기능은 REST API를 사용합니다.
• 부가기능은 요청 파일 범위 대화상자를 표시합니다. CardService.newEditorFileScopeActionResponseBuilder().requestFileScopeForActiveDocument().build(); 메서드 사용
• 부가기능에는 https://www.googleapis.com/auth/drive.file 편집기 범위 및 매니페스트에서 onFileScopeGranted 트리거를 사용합니다.

현재 문서의 파일 액세스 요청

현재 문서의 파일 액세스 권한을 요청하려면 다음 단계를 따르세요.

1. 부가기능에 drive.file 범위가 있는지 확인하는 홈페이지 카드를 빌드합니다.
2. 부가기능에 drive.file 범위가 부여되지 않은 경우 다음을 빌드합니다. 사용자에게 현재 문서의 drive.file 범위를 부여하도록 요청하는 방법입니다.

예: Google Docs에서 현재 문서에 대한 액세스 권한 얻기

다음 예제에서는 크기를 표시하는 Google Docs용 인터페이스를 할 수 있습니다. 부가기능에 drive.file 승인이 없는 경우 파일 범위 승인을 시작하는 버튼이 표시됩니다.

/**
 * 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 information about the
 *   current document.
 * @return {Card}
 */
function onDocsHomepage(e) {
  return createAddOnView(e);
}

function onFileScopeGranted(e) {
  return createAddOnView(e);
}

/**
 * For the current document, display either its quota information or
 * a button that allows the user to provide permission to access that
 * file to retrieve its quota details.
 *
 * @param e The event containing information about the current document
 * @return {Card}
 */
function createAddOnView(e) {
  var docsEventObject = e['docs'];
  var builder =  CardService.newCardBuilder();

  var cardSection = CardService.newCardSection();
  if (docsEventObject['addonHasFileScopePermission']) {
    cardSection.setHeader(docsEventObject['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 the add-on has access permission, read and display its quota.
    cardSection.addWidget(
      CardService.newTextParagraph().setText(
          "This file takes up: " + getQuotaBytesUsed(docsEventObject['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");

    var button = CardService.newTextButton()
      .setText("Request permission")
      .setOnClickAction(buttonAction);

    cardSection.addWidget(button);
  }
  return builder.addSection(cardSection).build();
}

/**
 * Callback function for a button action. Instructs Docs to display a
 * permissions dialog to the user, requesting `drive.file` scope for the
 * current file on behalf of this add-on.
 *
 * @param {Object} e The parameters object that contains the document’s ID
 * @return {editorFileScopeActionResponse}
 */
function onRequestFileScopeButtonClicked(e) {
  return CardService.newEditorFileScopeActionResponseBuilder()
      .requestFileScopeForActiveDocument().build();
}