편집자 부가기능 승인

대부분의 경우 부가기능을 사용하기 전에 승인을 받아야 합니다. 웹 앱과 같은 많은 Apps Script 프로젝트의 경우 승인은 간단합니다. 스크립트 프로젝트에서는 사용하려고 할 때 필요한 모든 권한을 요청합니다. 승인되면 스크립트 프로젝트를 무료로 사용할 수 있습니다. 스크립트 프로젝트를 사용하는 모든 사용자는 이를 개별적으로 승인합니다.

에디터 부가기능의 승인 모델은 더 복잡합니다. 이러한 부가기능은 Google Drive에 있는 파일(다른 사용자와 공유할 수 있는 파일)에서 작동하므로 다른 승인 모드를 염두에 두고 편집기 부가기능을 빌드해야 합니다. Google Docs 편집기는 부가기능을 아직 승인하지 않은 경우에도 설치된 부가기능으로 채워진 부가기능 메뉴를 UI에 제공합니다. 이로 인해 승인 모델이 약간 더 복잡해집니다.

승인 모델

편집기 부가기능의 두 가지 속성을 사용하면 특히 쉽게 공유하고 사용할 수 있습니다.

  • 스토어에서 편집기 부가기능을 다운로드하면 열고 만드는 모든 문서, 양식, 프레젠테이션, 스프레드시트의 부가기능 메뉴에 부가기능이 표시됩니다. 부가기능은 실제로 사용하는 문서, 양식, 프레젠테이션 또는 스프레드시트에서만 부가기능을 볼 수 없습니다.
  • 문서, 양식, 프레젠테이션 또는 스프레드시트에서 편집자 부가기능을 사용할 때 공동작업자는 부가기능 메뉴에서도 파일에만 표시됩니다 (부가기능을 설치하지 않은 경우).

이 공유 모델은 대부분의 사용자에게 자연스러운 느낌입니다. 그러나 Google Docs 편집기가 열릴 때 편집기 부가기능이 onOpen(e) 함수를 자동으로 실행하여 메뉴 항목을 추가하므로 위의 동작은 Apps Script의 승인 규칙을 다소 복잡하게 만듭니다. 사용자는 문서, 양식, 프레젠테이션 또는 스프레드시트를 열 때마다 개인 정보에 액세스하는 부가기능에 대해 불편할 수 있습니다. 이 가이드에서는 코드가 할 수 있는 작업과 작업을 이해하는 데 도움이 됩니다.

설치됨 및 사용 설정됨

메뉴에 편집기 부가기능이 표시되면 설치 및 사용 설정이라는 두 상태 중 하나 (또는 둘 다)에 있는 것입니다. 특정 사용자가 스토어에서 부가기능을 선택하고 Google 데이터에 액세스할 수 있도록 승인한 후에는 편집자 부가기능이 설치됩니다. 반면에 부가기능을 사용하는 경우에는 특정 문서, 양식, 프레젠테이션 또는 스프레드시트에서 부가기능을 사용 설정할 수 있습니다. 두 사람이 공동작업하고 그 중 한 명이 부가기능을 사용하는 경우 사용자 한 명에게 설치되고 파일에 사용 설정됩니다.

아래 표에는 두 가지 상태가 요약되어 있습니다. 부가기능으로 스크립트를 테스트할 때 이러한 상태 중 하나 또는 둘 다에서 테스트를 실행할 수 있습니다.

설치됨 사용 설정됨
적용 대상 사용자 문서, 양식, 프레젠테이션 또는 스프레드시트
원인 스토어에서 부가기능 설치하기 해당 문서, 양식, 프레젠테이션 또는 스프레드시트를 사용하는 동안 스토어에서 부가기능 가져오기 또는
해당 문서, 양식, 프레젠테이션 또는 스프레드시트에 이전에 설치한 부가기능 사용
메뉴 공개 대상 해당 사용자, 내가 열거나 만드는 모든 문서, 양식, 프레젠테이션, 스프레드시트 해당 문서, 양식, 프레젠테이션 또는 스프레드시트의 모든 공동작업자
onOpen(e)런 필요, AuthMode.NONE (사용 설정되어 있지 않은 경우 AuthMode.LIMITED)) AuthMode.LIMITED

승인 모드

편집기 부가기능은 onOpen(e) 함수를 자동으로 실행하여 문서, 양식, 프레젠테이션 또는 스프레드시트가 열릴 때 메뉴 항목을 추가합니다. 하지만 Apps Script에서는 사용자의 데이터를 보호하기 위해 onOpen(e) 함수가 할 수 있는 작업을 제한합니다. 부가기능이 현재 문서, 양식, 프레젠테이션, 스프레드시트에 사용되지 않으면 제한사항이 더 심각해집니다.

특히 설치 및 사용 설정 상태에 따라 onOpen(e) 함수가 실행되는 승인 모드가 결정됩니다. Apps Script는 승인 모드를 Apps Script 이벤트 매개변수 e의 authMode 속성으로 전달합니다. e.authMode의 값은 Apps Script ScriptApp.AuthMode enum의 상수에 해당합니다.

현재 문서, 양식, 프레젠테이션, 스프레드시트에서 편집기 부가기능을 사용 설정하면 onOpen(e)가 AuthMode.LIMITED에서 실행됩니다. 부가기능이 사용 설정되지 않고 설치만 된 경우 onOpen(e)가 AuthMode.NONE에서 실행됩니다.

승인 모드의 개념은 스크립트 편집기, 메뉴 항목 또는 Apps Script google.script.run 호출에서 실행과 같은 모든 Apps Script 실행에 적용됩니다. 그러나 e.authMode 속성은 스크립트가 onOpen(e), onEdit(e) 또는 onInstall(e)와 같은 트리거의 결과로 실행되는 경우에만 검사할 수 있습니다. Google Sheets의 커스텀 함수는 자체 승인 모드인 AuthMode.CUSTOM_FUNCTION를 사용합니다. 이 모드는 LIMITED와 비슷하지만 제한이 약간 다릅니다. 나머지 시간은 아래 표에 설명된 대로 스크립트가 AuthMode.FULL에서 실행됩니다.

NONE LIMITED CUSTOM_FUNCTION FULL
발생 시간 onOpen(e) (사용자가 부가기능을 설치했지만 문서, 양식, 프레젠테이션 또는 스프레드시트에서 사용 설정하지 않은 경우) onOpen(e) (다른 모든 시간)
onEdit(e) (Sheets에서만)		 커스텀 함수 그 외 모든 경우:
설치 가능한 트리거
onInstall(e)
google.script.run
사용자 데이터에 액세스 언어만 언어만 언어만 예
문서, 양식, 프레젠테이션 또는 스프레드시트 액세스 아니요 예 예 — 읽기 전용 예
사용자 인터페이스에 액세스 메뉴 항목 추가하기 메뉴 항목 추가하기 아니요 예
Properties에 대한 액세스 아니요 예 예 예
Jdbc, UrlFetch에 액세스 아니요 아니요 예 예
기타 서비스 Logger
Utilities		 사용자 데이터에 액세스하지 않는 서비스 사용자 데이터에 액세스하지 않는 서비스 모든 서비스

전체 수명 주기

부가기능이 현재 사용자에게 설치되어 있거나 현재 파일에 사용 설정되어 있다면 부가기능이 문서, 양식, 프레젠테이션, 스프레드시트에 로드되어 부가기능 메뉴에 표시되고 간단한 트리거 onInstall(e), onOpen(e), onEdit(e)에 대한 수신 대기가 시작됩니다. 사용자가 부가기능의 메뉴 항목 중 하나를 클릭하면 실행됩니다.

설치 중

스토어에서 편집기 부가기능이 설치되면 onInstall(e) 함수가 AuthMode.FULL에서 실행됩니다. 이렇게 하면 부가기능에서 복잡한 설정 루틴을 실행할 수 있지만 onInstall(e)를 사용하여 메뉴 항목을 만드는 것도 중요합니다. 문서, 양식, 프레젠테이션 또는 스프레드시트가 이미 열려 있고 onOpen(e) 함수가 실행되지 않았기 때문입니다. 이 샘플과 같이 편의를 위해 onInstall(e)에서 onOpen(e)를 호출하면 됩니다.

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

시작

문서, 양식, 프레젠테이션 또는 스프레드시트가 열릴 때 현재 사용자가 설치하거나 공동작업자가 파일에서 사용 설정한 모든 편집기 부가기능이 로드되고 각 onOpen(e) 함수가 호출됩니다. onOpen(e)이 실행되는 승인 모드는 부가기능이 설치되었는지 또는 사용 설정되었는지에 따라 다릅니다.

부가기능에서 기본 메뉴만 만드는 경우 모드는 중요하지 않습니다. 이 샘플은 간단한 onOpen(e)의 모습을 보여줍니다.

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

하지만 저장된 Apps Script 속성을 기반으로 동적 메뉴 항목을 추가하거나 현재 문서, 양식, 프레젠테이션 또는 스프레드시트의 콘텐츠를 읽거나 다른 고급 작업을 수행하려면 승인 모드를 감지하고 적절히 처리해야 합니다. 이 샘플은 고급 onOpen(e) 함수가 표시되는 방식을 보여줍니다. 이 함수는 승인 모드에 따라 동작을 변경합니다.

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

실행 중

누군가 부가기능의 메뉴 항목 중 하나를 클릭하면 Apps Script에서 먼저 사용자가 부가기능을 설치했는지 확인하고, 사용자가 부가기능을 설치하라는 메시지를 표시합니다. 사용자가 부가기능을 승인하면 스크립트에서 AuthMode.FULL의 메뉴 항목에 상응하는 함수를 실행합니다. 부가기능은 문서, 양식, 프레젠테이션 또는 스프레드시트에서도 사용할 수 있게 됩니다.