클래스 google.script.run (클라이언트 측 API)

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>

매개변수

이름유형설명
functionFunction서버 측 함수에서 예외가 발생할 경우 실행할 클라이언트 측 콜백 함수입니다. 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>

매개변수

이름유형설명
functionFunction서버 측 함수가 성공적으로 반환되면 실행할 클라이언트 측 콜백 함수입니다. 서버의 반환 값이 함수에 첫 번째 인수로 전달되고, 사용자 객체 (있는 경우)가 두 번째 인수로 전달됩니다.

리턴

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>

매개변수

이름유형설명
objectObject성공 및 실패 핸들러에 두 번째 매개변수로 전달할 객체입니다. 사용자 객체는 서버로 전송되지 않으므로 서버 호출에 대한 매개변수 및 반환 값에 대한 제한사항이 적용되지 않습니다. 그러나 사용자 객체는 new 연산자로 구성된 객체가 될 수 없습니다.

리턴

google.script.run: 체이닝을 위한 '스크립트 실행기'