대부분의 경우 부가기능을 사용하기 전에 승인을 받아야 합니다. 웹 앱과 같은 많은 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
의 메뉴 항목에 상응하는 함수를 실행합니다. 부가기능은 문서, 양식, 프레젠테이션 또는 스프레드시트에서도 사용할 수 있게 됩니다.