google.script.run
は HTML サービスのページで利用できる、クライアント側の非同期 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>
パラメータ
名前 | 型 | 説明 |
---|---|---|
... | ほとんどのタイプは有効ですが、Date 、Function 、form 以外の DOM 要素は無効です。説明を参照 | 有効なパラメータには、Number 、Boolean 、String 、null などの JavaScript プリミティブや、プリミティブ、オブジェクト、配列で構成される JavaScript オブジェクトと配列があります。ページ内の form 要素もパラメータとして有効ですが、関数唯一のパラメータである必要があります。Date 、Function 、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>
パラメータ
名前 | 型 | 説明 |
---|---|---|
function | Function | サーバー側関数が例外をスローした場合に実行されるクライアント側コールバック関数。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>
パラメータ
名前 | 型 | 説明 |
---|---|---|
function | Function | サーバー側関数が正常に返された場合に実行されるクライアント側コールバック関数。サーバーの戻り値は最初の引数として関数に渡され、ユーザー オブジェクト(存在する場合)が 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>
パラメータ
名前 | 型 | 説明 |
---|---|---|
object | Object | 成功ハンドラと失敗ハンドラの 2 番目のパラメータとして渡すオブジェクト。ユーザー オブジェクトはサーバーに送信されないため、サーバー呼び出しのパラメータや戻り値の制限の対象にはなりません。ただし、ユーザー オブジェクトは new 演算子で作成されたオブジェクトにはできません |
リターン
google.script.run
- この「スクリプト ランナー」(チェーン用)