편집자 부가기능 승인

대부분의 Google Apps Script 앱의 승인은 간단합니다. 스크립트 프로젝트는 사용자가 스크립트 프로젝트를 사용하려고 할 때 필요한 누락된 권한을 요청합니다.

편집자 부가기능의 승인 모델은 다음과 같은 여러 가지 이유로 더 복잡합니다.

• 사용자가 파일을 만들면 아직 부가기능을 승인하지 않았더라도 사용자가 설치한 모든 부가기능이 확장 프로그램 메뉴에 나열됩니다.

• 이러한 부가기능은 공동작업자와 공유할 수 있는 Google Drive의 파일에서 작동합니다. 편집자 부가기능이 설치되지 않은 공동작업자는 파일 작성자가 부가기능을 사용한 문서에서 부가기능을 볼 수 있습니다.

• 편집자 부가기능은 문서가 열릴 때 onOpen 함수를 자동으로 실행합니다.

사용자 데이터를 보호하기 위해 일부 서비스를 onOpen에서 사용할 수 없도록 하는 승인 모드가 적용됩니다. 이 가이드에서는 코드가 할 수 있는 작업과 시기를 설명합니다.

승인 모델

편집자 부가기능의 승인 모드는 부가기능을 설치한 사용자 또는 공동작업자 등 부가기능을 사용하는 사용자에 따라 달라지는 부가기능의 상태에 따라 달라집니다.

편집자 부가기능 상태

확장 프로그램 메뉴의 편집자 부가기능은 설치되거나 사용 설정되거나 둘 다일 수 있습니다.

• 사용자 또는 관리자가 Google Workspace Marketplace에서 부가기능을 가져와 Google 데이터에 액세스할 수 있도록 승인하면 특정 사용자를 위해 부가기능이 설치 됩니다.
• 문서, 양식, 프레젠테이션 또는 스프레드시트에서 사용자가 부가기능을 사용하면 부가기능이 사용 설정 됩니다.
• 사용자가 파일에서 공동작업을 하고 그중 한 명이 부가기능을 사용하면 해당 사용자를 위해 부가기능이 설치 되고 파일에 대해 사용 설정 됩니다.

다음 표에는 설치됨과 사용 설정됨의 차이점이 요약되어 있습니다. 스크립트를 부가기능으로 테스트할 때는 두 상태 중 하나 또는 둘 다에서 테스트를 실행할 수 있습니다.

승인 모드

사용자가 문서, 양식, 프레젠테이션 또는 스프레드시트를 열면 편집자 부가기능의 onOpen 함수가 자동으로 실행됩니다. 사용자 데이터를 보호하기 위해 Apps Script는 onOpen 함수가 할 수 있는 작업을 제한합니다. 편집자 부가기능 상태에 따라 onOpen 함수가 실행되는 승인 모드가 결정됩니다.

파일, 양식, 프레젠테이션 또는 스프레드시트에서 편집자 부가기능이 사용 설정 된 경우 onOpen이 AuthMode.LIMITED에서 실행됩니다. 부가기능이 사용 설정되지 않고 설치만 된 경우 onOpen이 AuthMode.NONE에서 실행됩니다.

AuthMode.NONE에서 부가기능은 사용자가 맞춤 함수를 클릭하거나 실행하여 부가기능과 상호작용할 때까지 특정 서비스를 실행할 수 없습니다. 부가기능이 onOpen, onInstall 또는 전역 범위에서 이러한 서비스를 사용하려고 하면 권한이 실패하고 메뉴 채우기와 같은 다른 호출이 중지 됩니다. 도움말만 지원되는 옵션입니다.

제한된 서비스 호출을 실행하려면 AuthMode.FULL 승인 모드를 사용해야 합니다. 메뉴 옵션 클릭과 같은 사용자 상호작용 함수는 이 모드에서만 실행됩니다. AuthMode.FULL 모드에서 코드가 실행된 후 부가기능은 승인된 모든 범위를 사용할 수 있습니다.

게시된 편집자 부가기능만 AuthMode.NONE에 있을 수 있습니다. 게시되지 않은 편집자 부가기능은 AuthMode.LIMITED에서 onOpen을 실행합니다. 그러나 두 승인 모드 모두에서 의도되었습니다. 이렇게 하려면 편집자 부가기능을 테스트하세요.

Apps Script는 승인 모드 를 Apps Script 이벤트 매개변수 e의 authMode 속성으로 전달합니다. e.authMode 값은 Apps Script ScriptApp.AuthMode enum의 상수와 일치합니다.

승인 모드는 스크립트 편집기, 메뉴 항목 또는 Apps Script google.script.run 호출에서 실행하는 것을 비롯한 모든 Apps Script 실행 메서드에 적용됩니다. 그러나 e.authMode 속성은 스크립트가 트리거 의 결과로 실행되는 경우에만 검사할 수 있습니다. 예를 들어 트리거는 onOpen, onEdit 또는 onInstall입니다. Google Sheets의 맞춤 함수 는 LIMITED와 비슷하지만 약간 다른 제한사항이 있는 자체 승인 모드인 AuthMode.CUSTOM_FUNCTION 를 사용합니다. 다른 모든 경우 스크립트는 다음 표에 설명된 대로 AuthMode.FULL에서 실행됩니다.

편집자 부가기능의 승인 수명 주기

현재 사용자를 위해 부가기능이 설치되거나 현재 파일에서 사용 설정되면 파일이 열릴 때 문서, 양식, 프레젠테이션 또는 스프레드시트에 부가기능이 로드 됩니다. 부가기능은 확장 프로그램 메뉴에 나열되고 간단한 트리거 onInstall, onOpen, onEdit를 수신 대기하기 시작합니다. 사용자가 확장 프로그램 메뉴 항목을 클릭하면 실행됩니다.

편집자 부가기능이 설치됨

스토어에서 편집자 부가기능을 설치하면 onInstall 함수가 AuthMode.FULL에서 실행됩니다. 이 승인 모드에서 부가기능은 복잡한 설정 루틴을 실행할 수 있습니다. 문서, 양식, 프레젠테이션 또는 스프레드시트가 이미 열려 있고 onOpen 함수가 실행되지 않았으므로 onInstall을 사용하여 메뉴 항목을 만들어야 합니다. 다음 샘플에서는 onInstall 함수에서 onOpen 함수를 호출하는 방법을 보여줍니다.

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

편집자 부가기능이 열림

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

부가기능이 기본 메뉴만 만드는 경우 모드는 중요하지 않습니다. 다음 샘플에서는 기본 onOpen 함수를 보여줍니다.

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

저장된 Apps Script 속성을 기반으로 동적 메뉴 항목을 추가하거나, 현재 파일의 콘텐츠를 읽거나, 기타 고급 작업을 실행하려면 승인 모드를 식별하고 적절하게 처리해야 합니다.

다음 샘플에서는 승인 모드에 따라 작업을 변경하는 고급 onOpen 함수를 보여줍니다.

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

onOpen 함수가 실행되면 전체 스크립트가 로드되고 전역 문이 onOpen과 동일한 승인 모드에서 실행됩니다. 승인 모드에서 전역 문을 금지하는 경우 전역 문과 onOpen이 모두 실행되지 않습니다. 게시된 부가기능이 메뉴 항목을 추가하지 못하면 브라우저 콘솔을 검토하여 오류가 반환되었는지 확인합니다. 그런 다음 스크립트를 검사하여 onOpen 함수 또는 전역 변수가 AuthMode.NONE에서 허용되지 않는 서비스를 호출하는지 확인합니다.

부가기능은 AuthMode.LIMITED에서 실행되는 동안 사이드바 또는 대화상자를 열 수 없습니다. 메뉴 항목을 사용하여 사이드바와 대화상자를 열 수 있습니다. 이러한 항목은 AuthMode.FULL에서 실행되기 때문입니다.

사용자가 편집자 부가기능을 실행함

사용자가 확장 프로그램 메뉴 항목을 클릭하면 Apps Script는 먼저 사용자가 부가기능을 설치했는지 확인하고 설치하지 않은 경우 설치하라는 메시지를 표시합니다. 사용자가 부가기능을 승인한 경우 스크립트는 AuthMode.FULL에서 메뉴 항목에 해당하는 함수를 실행합니다. 부가기능이 아직 사용 설정되지 않은 경우 문서, 양식, 프레젠테이션 또는 스프레드시트에서 사용 설정됩니다.

부가기능 메뉴가 렌더링되지 않는 문제 해결

코드가 승인 모드를 올바르게 관리하지 않으면 부가기능 메뉴가 렌더링되지 않을 수 있습니다. 예를 들면 다음과 같습니다.

• 부가기능이 현재 승인 모드에서 지원되지 않는 Apps Script 서비스를 실행하려고 합니다.

• 부가기능이 사용자와 상호작용하기 전에 서비스 호출을 실행하려고 합니다.

AuthMode.NONE에서 권한 오류를 일으키는 서비스 호출을 삭제하거나 재정렬하려면 다음 작업을 시도하세요.

1. 부가기능의 Apps Script 프로젝트를 열고 onOpen 함수를 찾습니다.
2. onOpen 함수에서 PropertiesService, SpreadsheetApp 또는 GmailApp과 같은 Apps Script 서비스 또는 관련 객체를 언급하는 부분을 검색합니다.
3. 서비스가 UI 요소를 만드는 것 외에 다른 용도로 사용되는 경우 서비스를 삭제하거나 주석 블록으로 래핑합니다. .getUi, .createMenu, .addItem, .addToUi 메서드만 남겨둡니다. 또한 함수 외부에 있는 서비스를 찾아 삭제합니다.
4. 이전 단계에서 주석 처리되거나 삭제된 코드 줄이 포함될 수 있는 함수(특히 생성된 정보를 사용하는 함수)를 식별하고 서비스 호출을 필요한 함수로 이동합니다. 이전 단계에서 변경된 사항을 수용하도록 코드베이스를 재정렬하거나 다시 작성합니다.
5. 코드를 저장하고 테스트 배포를 만듭니다. 테스트 배포를 만들 때는 구성 필드가 현재 사용자를 위해 설치됨 이고 구성 상자 아래의 텍0}스트가 에서 테스트 AuthMode.NONE 라고 표시되는지 확인합니다.
6. 테스트 배포를 실행하고 확장 프로그램 메뉴를 엽니다.
7. 모든 메뉴 항목이 표시되면 문제가 해결된 것입니다. 도움말 메뉴만 표시되면 1단계로 돌아갑니다. 서비스 호출을 놓쳤을 수 있습니다.

관련 주제

• 웹 앱
• 부가기능 유형
• 편집자 부가기능 테스트