편집기 작업

작업 객체를 사용하여 Google Workspace 부가기능에 대화형 동작을 빌드합니다.

작업 객체는 사용자가 부가기능 UI에서 위젯(예: 버튼)과 상호작용할 때 발생하는 상황을 정의합니다.

위젯에 작업 추가

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

예: 버튼을 클릭할 때 새 카드 표시

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

  1. 버튼 위젯을 만듭니다.
  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

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

  • 부가기능은 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();
}