google.script.run
는 서버 측 Apps Script 함수를 호출할 수 있는 HTML 서비스 페이지에서 사용할 수 있는 비동기 클라이언트 측 JavaScript API입니다. 클라이언트 측 코드에서 Google Docs, Sheets, Forms의 대화상자 또는 사이드바와 상호작용하려면 google.script.host
를 사용하세요. 자세한 내용은 HTML 서비스의 서버 함수와 통신 가이드를 참고하세요.
방법
메서드 | 반환 유형 | 간략한 설명 |
---|---|---|
myFunction(...) (모든 서버 측 함수) |
void |
해당 이름으로 서버 측 Apps Script 함수를 실행합니다. |
withFailureHandler(function) |
google.script.run |
서버 측 함수에서 예외가 발생할 경우 실행할 콜백 함수를 설정합니다. |
withSuccessHandler(function) |
google.script.run |
서버 측 함수가 성공적으로 반환되면 실행할 콜백 함수를 설정합니다. |
withUserObject(object) |
google.script.run |
성공 및 실패 핸들러에 두 번째 매개변수로 전달할 객체를 설정합니다. |
자세한 문서
myFunction(...)
(모든 서버 측 함수)
해당 이름으로 서버 측 Apps Script 함수를 실행합니다.
Code.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> <body> </body> </html>
매개변수
이름 | 유형 | 설명 |
---|---|---|
... | 대부분의 유형은 유효하지만 form 외에 Date , Function 또는 DOM 요소는 허용되지 않습니다. 설명을 참조하세요. | 유효한 매개변수는 Number , Boolean , String , null 와 같은 자바스크립트 프리미티브와 프리미티브, 객체, 배열로 구성된 자바스크립트 객체 및 배열입니다. 페이지 내의 form 요소도 매개변수로 유효하지만 함수의 유일한 매개변수여야 합니다. Date , Function , form 외의 DOM 요소 또는 객체나 배열 내의 금지된 유형 등 기타 금지된 유형을 전달하려고 하면 요청이 실패합니다. 순환 참조를 만드는 객체도 실패하고 배열 내에 정의되지 않은 필드는 null 가 됩니다. 서버로 전달된 객체는 원본의 사본이 됩니다. 서버 함수가 객체를 수신하여 속성을 변경해도 클라이언트의 속성은 영향을 받지 않습니다. |
리턴
void
- 이 메서드는 비동기식이며 직접 반환되지 않습니다. 그러나 서버 측 함수는 성공 핸들러에 전달된 매개변수로 클라이언트에 값을 반환할 수 있습니다. 또한 form
요소가 유효한 반환 유형이 아닌 것을 제외하고 반환 유형에는 매개변수 유형과 동일한 제한사항이 적용됩니다.
withFailureHandler(function)
서버 측 함수에서 예외가 발생할 경우 실행할 콜백 함수를 설정합니다. Error
객체가 함수에 첫 번째 인수로 전달되고 사용자 객체 (있는 경우)가 두 번째 인수로 전달됩니다. 실패 핸들러가 없으면 실패가 자바스크립트 콘솔에 기록됩니다. 이를 재정의하려면 withFailureHandler(null)
를 호출하거나 아무 작업도 하지 않는 실패 핸들러를 제공합니다.
Code.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>
매개변수
이름 | 유형 | 설명 |
---|---|---|
function | Function | 서버 측 함수에서 예외가 발생할 경우 실행할 클라이언트 측 콜백 함수입니다. Error 객체는 함수에 첫 번째 인수로 전달되고 사용자 객체 (있는 경우)가 두 번째 인수로 전달됩니다. |
리턴
google.script.run
: 체이닝을 위한 '스크립트 실행기'
withSuccessHandler(function)
서버 측 함수가 성공적으로 반환되면 실행할 콜백 함수를 설정합니다. 서버의 반환 값이 함수에 첫 번째 인수로 전달되고 사용자 객체 (있는 경우)가 두 번째 인수로 전달됩니다.
Code.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>
매개변수
이름 | 유형 | 설명 |
---|---|---|
function | Function | 서버 측 함수가 성공적으로 반환되면 실행할 클라이언트 측 콜백 함수입니다. 서버의 반환 값이 함수에 첫 번째 인수로 전달되고, 사용자 객체 (있는 경우)가 두 번째 인수로 전달됩니다. |
리턴
google.script.run
: 체이닝을 위한 '스크립트 실행기'
withUserObject(object)
성공 및 실패 핸들러에 두 번째 매개변수로 전달할 객체를 설정합니다. User
클래스와 혼동해서는 안 되는 이 '사용자 객체'를 사용하면 콜백 함수가 클라이언트가 서버에 접속한 컨텍스트에 응답할 수 있습니다. 사용자 객체는 서버로 전송되지 않으므로 서버 호출에 대한 매개변수 및 반환 값에 관한 제한사항이 적용되지 않습니다. 그러나 사용자 객체는 new
연산자로 구성된 객체가 될 수 없습니다.
Code.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>
매개변수
이름 | 유형 | 설명 |
---|---|---|
object | Object | 성공 및 실패 핸들러에 두 번째 매개변수로 전달할 객체입니다. 사용자 객체는 서버로 전송되지 않으므로 서버 호출에 대한 매개변수 및 반환 값에 대한 제한사항이 적용되지 않습니다. 그러나 사용자 객체는 new 연산자로 구성된 객체가 될 수 없습니다. |
리턴
google.script.run
: 체이닝을 위한 '스크립트 실행기'