クラス google.script.run(クライアントサイド API)

google.script.runHTML サービスのページで利用できる、クライアント側の非同期 JavaScript API です。サーバー側の Apps Script 関数を呼び出すことができます。クライアントサイドのコードから Google ドキュメント、スプレッドシート、フォームでダイアログやサイドバーを操作するには、google.script.host を使用します。詳しくは、HTML サービスのサーバー機能との通信に関するガイドをご覧ください。

Methods

メソッド戻り値の型概要
myFunction(...)(任意のサーバーサイド関数) void 対応する名前でサーバーサイドの Apps Script 関数を実行します。
withFailureHandler(function) google.script.run サーバー側の関数が例外をスローした場合に実行するコールバック関数を設定します。
withSuccessHandler(function) google.script.run サーバーサイド関数が正常に返された場合に実行するコールバック関数を設定します。
withUserObject(object) google.script.run 成功ハンドラと失敗ハンドラに 2 番目のパラメータとして渡すオブジェクトを設定します。

詳細なドキュメント

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>

パラメータ

名前説明
...ほとんどのタイプは有効ですが、DateFunctionform 以外の DOM 要素は無効です。説明を参照有効なパラメータには、NumberBooleanStringnull などの JavaScript プリミティブや、プリミティブ、オブジェクト、配列で構成される JavaScript オブジェクトと配列があります。ページ内の form 要素もパラメータとして有効ですが、関数唯一のパラメータである必要があります。DateFunction、DOM 要素のほかに、form、またはその他の禁止されているタイプ(オブジェクトや配列内の禁止タイプを含む)を渡そうとすると、リクエストは失敗します。循環参照を作成するオブジェクトも失敗し、配列内の未定義のフィールドは null になります。サーバーに渡されるオブジェクトは元のオブジェクトのコピーになります。サーバー関数がオブジェクトを受け取ってそのプロパティを変更しても、クライアントのプロパティは影響を受けません。

リターン

void - このメソッドは非同期で、直接返されません。ただし、サーバーサイド関数は、成功ハンドラに渡されるパラメータとしてクライアントに値を返すことができます。また、戻り値の型にはパラメータ型と同じ制限が適用されます(ただし、form 要素は正式な戻り値の型ではありません)。


withFailureHandler(function)

サーバー側の関数が例外をスローした場合に実行するコールバック関数を設定します。Error オブジェクトが最初の引数として関数に渡され、ユーザー オブジェクト(存在する場合)が 2 番目の引数として渡されます。失敗ハンドラがない場合、失敗は JavaScript コンソールに記録されます。これをオーバーライドするには、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 オブジェクトが最初の引数として関数に渡され、ユーザー オブジェクト(存在する場合)が 2 番目の引数として渡されます

リターン

google.script.run - この「スクリプト ランナー」(チェーン用)


withSuccessHandler(function)

サーバーサイド関数が正常に返された場合に実行するコールバック関数を設定します。サーバーの戻り値は最初の引数として関数に渡され、ユーザー オブジェクト(存在する場合)は 2 番目の引数として渡されます。

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サーバー側関数が正常に返された場合に実行されるクライアント側コールバック関数。サーバーの戻り値は最初の引数として関数に渡され、ユーザー オブジェクト(存在する場合)が 2 番目の引数として渡されます

リターン

google.script.run - この「スクリプト ランナー」(チェーン用)


withUserObject(object)

成功ハンドラと失敗ハンドラに 2 番目のパラメータとして渡すオブジェクトを設定します。この「ユーザー オブジェクト」を使用すると、コールバック関数がクライアントがサーバーに接続したコンテキストに応答できるようになります(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成功ハンドラと失敗ハンドラの 2 番目のパラメータとして渡すオブジェクト。ユーザー オブジェクトはサーバーに送信されないため、サーバー呼び出しのパラメータや戻り値の制限の対象にはなりません。ただし、ユーザー オブジェクトは new 演算子で作成されたオブジェクトにはできません

リターン

google.script.run - この「スクリプト ランナー」(チェーン用)