クラス google.script.run（クライアントサイド API）

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

google.script.run は、クライアント側の Apps Script 関数を呼び出すことができる HTML サービスページで使用できる非同期のクライアント側 JavaScript API です。クライアントサイド コードから 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>

パラメータ

名前型説明
...ほとんどの型は合法ですが、form 以外の Date、Function、DOM 要素ではありません。説明をご確認ください。有効なパラメータは、Number、Boolean、String、null などの JavaScript プリミティブに加えて、プリミティブ、オブジェクト、配列から構成される JavaScript オブジェクトと配列です。ページ内の form 要素もパラメータとしては合法ですが、関数の唯一のパラメータにする必要があります。Date、Function、form 以外の DOM 要素、またはその他の禁止されている型（オブジェクトや配列内の禁止された型を含む）を渡そうとすると、リクエストが失敗します。循環参照を作成するオブジェクトも失敗し、配列内の未定義のフィールドは 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 - この「スクリプト ランナー」&チェーン