google.script.run는 HTML 서비스 페이지가 서버 측 Apps Script 함수를 호출할 수 있도록 지원하는 비동기 클라이언트 측 자바스크립트 API입니다. 다음 예는 클라이언트 측 자바스크립트에서 서버의 함수를 호출하는 google.script.run의 가장 기본적인 기능을 보여줍니다.
코드.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function doSomething() {
Logger.log('I was called!');
}
index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
google.script.run.doSomething();
</script>
</head>
</html>
이 스크립트를 웹 앱으로 배포하고 URL을 방문하면 아무것도 표시되지 않지만 로그를 보면 서버 함수 doSomething()가 호출된 것을 확인할 수 있습니다.
서버 측 함수에 대한 클라이언트 측 호출은 비동기식입니다. 브라우저에서 서버에 doSomething() 함수를 실행하도록 요청한 후에는 브라우저가 응답을 기다리지 않고 다음 코드 줄로 즉시 이동합니다. 즉, 서버 함수 호출이 예상한 순서대로 실행되지 않을 수 있습니다. 동시에 두 함수를 호출하면 어떤 함수가 먼저 실행되는지 알 수 없으므로 페이지를 로드할 때마다 결과가 달라질 수 있습니다. 이 경우 성공 핸들러 및 장애 핸들러가 코드의 흐름을 제어하는 데 도움이 됩니다.
google.script.run API를 사용하면 서버 함수를 동시에 10회 호출할 수 있습니다. 10이 여전히 실행 중일 때 11번째를 호출하면 10개의 스팟 중 하나가 해제될 때까지 서버 기능이 지연됩니다. 실제로는 대부분의 브라우저에서 동일한 서버에 대한 동시 요청 수를 이미 10개 미만으로 제한했기 때문에 이 제한사항에 대해 고민할 필요가 거의 없습니다.
예를 들어 Firefox에서는 한도가 6입니다. 대부분의 브라우저는 기존 요청 중 하나가 완료될 때까지 서버 초과 요청을 지연시킵니다.
매개변수 및 반환 값
클라이언트의 매개변수를 사용하여 서버 함수를 호출할 수 있습니다. 마찬가지로 서버 함수는 성공 핸들러에 전달된 매개변수로 클라이언트에 값을 반환할 수 있습니다.
법적 매개변수 및 반환 값은 Number, Boolean, String, null 등의 자바스크립트 프리미티브와 프리미티브, 객체, 배열로 구성된 자바스크립트 객체 및 배열입니다. 페이지 내 form 요소도 매개변수로 유효하지만 함수의 유일한 매개변수여야 하고 반환 값으로 사용할 수 없습니다. form 이외의 Date, Function, DOM 요소 또는 객체나 배열 내부의 금지된 유형을 비롯하여 기타 금지된 유형을 전달하려고 하면 요청이 실패합니다. 순환 참조를 만드는 객체도 실패하며 배열 내의 정의되지 않은 필드는 null가 됩니다.
서버에 전달된 객체는 원본의 사본이 됩니다. 서버 함수가 객체를 수신하고 속성을 변경해도 클라이언트의 속성은 영향을 받지 않습니다.
성공 핸들러
서버 측 코드가 서버 호출이 완료되기를 기다리지 않고 다음 줄로 계속 진행되므로 withSuccessHandler(function)를 사용하면 서버가 응답할 때 실행할 클라이언트 측 콜백 함수를 지정할 수 있습니다. 서버 함수가 값을 반환하면 API가 값을 새 함수에 매개변수로 전달합니다.
다음 예에서는 서버가 응답할 때 브라우저 알림을 표시합니다. 서버 측 함수가 Gmail 계정에 액세스하므로 이 코드 샘플에는 승인이 필요합니다. 스크립트를 승인하는 가장 간단한 방법은 페이지를 로드하기 전에 스크립트 편집기에서 getUnreadEmails() 함수를 수동으로 실행하는 것입니다. 또는 웹 앱을 배포할 때 '웹 앱에 액세스하는 사용자'로 실행하도록 선택할 수 있습니다. 이 경우 앱을 로드할 때 승인을 요청하는 메시지가 표시됩니다.
코드.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getUnreadEmails() {
return GmailApp.getInboxUnreadCount();
}
index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function onSuccess(numUnread) {
var div = document.getElementById('output');
div.innerHTML = 'You have ' + numUnread
+ ' unread messages in your Gmail inbox.';
}
google.script.run.withSuccessHandler(onSuccess)
.getUnreadEmails();
</script>
</head>
<body>
<div id="output"></div>
</body>
</html>
실패 핸들러
서버가 응답하지 않거나 오류가 발생하는 경우 withFailureHandler(function)를 사용하면 Error 객체 (있는 경우)를 인수로 전달하여 성공 핸들러를 지정하는 대신 실패 핸들러를 지정할 수 있습니다.
기본적으로 실패 핸들러를 지정하지 않으면 자바스크립트 콘솔에 오류가 로깅됩니다. 이를 재정의하려면 withFailureHandler(null)를 호출하거나 아무 작업도 하지 않는 실패 핸들러를 제공합니다.
이 예시에서 보듯이 실패 핸들러의 구문은 성공 핸들러와 거의 동일합니다.
코드.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getUnreadEmails() {
// 'got' instead of 'get' will throw an error.
return GmailApp.gotInboxUnreadCount();
}
index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function onFailure(error) {
var div = document.getElementById('output');
div.innerHTML = "ERROR: " + error.message;
}
google.script.run.withFailureHandler(onFailure)
.getUnreadEmails();
</script>
</head>
<body>
<div id="output"></div>
</body>
</html>
사용자 객체
withUserObject(object)를 호출하여 두 번째 매개변수로 핸들러에 전달될 객체를 지정하여 서버에 대한 여러 호출에 동일한 성공 또는 실패 핸들러를 재사용할 수 있습니다.
User 클래스와 혼동해서는 안 되는 이 '사용자 객체'를 사용하면 클라이언트가 서버에 연결한 컨텍스트에 응답할 수 있습니다. 사용자 객체는
서버로 전송되지 않으므로 함수, DOM 요소 등 서버 호출에 대한
매개변수 및 반환 값에 대한 제한 없이 거의 모든 개체일 수
있습니다. 그러나 사용자 객체는 new 연산자로 구성된 객체일 수 없습니다.
이 예에서는 두 버튼 중 하나를 클릭하면 서버의 버튼이 있는 버튼을 업데이트하고 다른 버튼은 변경하지 않은 채로 하나의 성공 핸들러를 공유하더라도 이 버튼은 변경되지 않습니다. onclick 핸들러 내에서 키워드 this는 button 자체를 참조합니다.
코드.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getEmail() {
return Session.getActiveUser().getEmail();
}
index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function updateButton(email, button) {
button.value = 'Clicked by ' + email;
}
</script>
</head>
<body>
<input type="button" value="Not Clicked"
onclick="google.script.run
.withSuccessHandler(updateButton)
.withUserObject(this)
.getEmail()" />
<input type="button" value="Not Clicked"
onclick="google.script.run
.withSuccessHandler(updateButton)
.withUserObject(this)
.getEmail()" />
</body>
</html>
Forms
form 요소를 매개변수로 사용하여 서버 함수를 호출하면 형식은 필드 이름이 키로, 필드 값이 값으로 포함된 단일 객체가 됩니다. 값은 모두 Blob 객체가 되는 파일 입력 필드의 콘텐츠를 제외하고 모두 문자열로 변환됩니다.
이 예시에서는 페이지를 새로고침하지 않고 파일 입력 필드를 비롯한 양식을 처리합니다. 파일을 Google Drive에 업로드한 다음 파일의 URL을 클라이언트 측 페이지에 출력합니다. onsubmit 핸들러 내에서 키워드 this은 양식 자체를 참조합니다. 페이지의 모든 양식을 로드하면 기본 제출 작업은 preventFormSubmit에 의해 사용 중지됩니다. 이렇게 하면 예외가 발생하는 경우 페이지가 잘못된 URL로 리디렉션되는 것을 방지할 수 있습니다.
코드.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function processForm(formObject) {
var formBlob = formObject.myFile;
var driveFile = DriveApp.createFile(formBlob);
return driveFile.getUrl();
}
index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
// Prevent forms from submitting.
function preventFormSubmit() {
var forms = document.querySelectorAll('form');
for (var i = 0; i < forms.length; i++) {
forms[i].addEventListener('submit', function(event) {
event.preventDefault();
});
}
}
window.addEventListener('load', preventFormSubmit);
function handleFormSubmit(formObject) {
google.script.run.withSuccessHandler(updateUrl).processForm(formObject);
}
function updateUrl(url) {
var div = document.getElementById('output');
div.innerHTML = '<a href="' + url + '">Got it!</a>';
}
</script>
</head>
<body>
<form id="myForm" onsubmit="handleFormSubmit(this)">
<input name="myFile" type="file" />
<input type="submit" value="Submit" />
</form>
<div id="output"></div>
</body>
</html>
스크립트 실행기
google.script.run를 '스크립트 실행기'의 빌더로 생각할 수 있습니다. 스크립트 실행기에 성공 핸들러, 실패 핸들러 또는 사용자 객체를 추가해도 기존 실행기는 변경되지 않으며, 대신 새 동작이 포함된 새 스크립트 실행기가 다시 제공됩니다.
withSuccessHandler(), withFailureHandler(), withUserObject()의 모든 조합과 순서를 사용할 수 있습니다. 이미 값이 설정된 스크립트 실행기에서 수정 함수를 호출할 수도 있습니다. 새 값은 단순히 이전 값을 재정의합니다.
이 예에서는 서버 호출 3개 모두에 공통 실패 핸들러를 설정하지만 별도의 성공 핸들러 2개는 다음과 같이 설정합니다.
var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);
myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();
비공개 함수
이름이 밑줄로 끝나는 서버 함수는 비공개로 간주됩니다.
이러한 함수는 google.script로 호출할 수 없으며 이름은 클라이언트로 전송되지 않습니다. 따라서 이를 사용하여 서버에서 기밀로 유지해야 하는 구현 세부정보를 숨길 수 있습니다. google.script는 라이브러리 내의 함수와 스크립트의 최상위 수준에서 선언되지 않은 함수도 볼 수 없습니다.
이 예에서는 클라이언트 코드에서 getBankBalance() 함수를 사용할 수 있습니다. 소스 코드를 검사하는 사용자는 개발자가 코드를 호출하지 않더라도 이름을 검색할 수 있습니다. 하지만 deepSecret_() 및 obj.objectMethod() 함수는 클라이언트에 전혀 표시되지 않습니다.
코드.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getBankBalance() {
var email = Session.getActiveUser().getEmail()
return deepSecret_(email);
}
function deepSecret_(email) {
// Do some secret calculations
return email + ' has $1,000,000 in the bank.';
}
var obj = {
objectMethod: function() {
// More secret calculations
}
};
index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function onSuccess(balance) {
var div = document.getElementById('output');
div.innerHTML = balance;
}
google.script.run.withSuccessHandler(onSuccess)
.getBankBalance();
</script>
</head>
<body>
<div id="output">No result yet...</div>
</body>
</html>
애플리케이션의 대화상자 Google Workspace 크기 조절
Google Docs, Sheets, Forms의 맞춤 대화상자는 클라이언트 측 코드에서 google.script.host 메서드 setWidth(width) 또는 setHeight(height)를 호출하여 크기를 조절할 수 있습니다. 대화상자의 초기 크기를 설정하려면 HtmlOutput 메서드 setWidth(width) 및 setHeight(height)를 사용합니다. 크기를 조절할 때 대화상자의 크기가 상위 창에서 다시 중앙에 배치되지 않으며 사이드바의 크기를 조절할 수 없습니다.
Google Workspace의 대화상자 및 사이드바 닫기
HTML 서비스를 사용하여 Google Docs, Sheets, Forms에서 대화상자 또는 사이드바를 표시하는 경우 window.close()를 호출하여 인터페이스를 닫을 수 없습니다. 대신 google.script.host.close()를 호출해야 합니다.
예는 HTML을 Google Workspace 사용자 인터페이스로 제공 섹션을 참고하세요.
브라우저 포커스를 Google Workspace로 이동 중
사용자 브라우저의 대화상자나 사이드바에서 포커스를 Google Docs, Sheets, Forms 편집기로 다시 전환하려면 google.script.host.editor.focus() 메서드를 호출하기만 하면 됩니다.
이 메서드는 문서 서비스 메서드 Document.setCursor(position) 및 Document.setSelection(range)와 함께 사용하면 특히 유용합니다.