google.script.run は、HTML サービス ページからサーバーサイドの Apps Script 関数を呼び出せる非同期クライアントサイドの JavaScript API です。次の例は、google.script.run の最も基本的な機能である、クライアントサイドの JavaScript からサーバー上の関数を呼び出すことを示しています。
コード.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>
</html>
このスクリプトをウェブアプリとしてデプロイし、その URL にアクセスしても何も表示されませんが、ログを見ると、サーバー関数 doSomething() が呼び出されたことがわかります。
サーバーサイド関数へのクライアントサイド呼び出しは非同期です。ブラウザがサーバーに関数 doSomething() の実行をリクエストした後、ブラウザはレスポンスを待たずにすぐに次の行のコードに進みます。つまり、サーバー関数呼び出しが想定どおりの順序で実行されない可能性があります。2 つの関数呼び出しを同時に行う場合、どちらの関数が先に実行されるかを把握することはできません。結果はページの読み込みごとに異なる場合があります。この状況では、成功ハンドラと失敗ハンドラを使用してコードのフローを制御できます。
google.script.run API では、サーバー関数を 10 回同時に呼び出すことができます。10 件の呼び出しがまだ実行中であるときに 11 件目の呼び出しを行うと、10 件のスポットのいずれかが解放されるまで、サーバー関数は遅延します。実際には、ほとんどのブラウザで同じサーバーの同時リクエスト数が 10 未満に制限されているため、この制限について考える必要はほとんどありません。たとえば Firefox では、この上限は 6 です。ほとんどのブラウザは、既存のリクエストのいずれかが完了するまで、余分なサーバー リクエストを遅らせます。
パラメータと戻り値
クライアントからパラメータを使用してサーバー関数を呼び出すことができます。同様に、サーバー関数は、成功ハンドラに渡されるパラメータとして値をクライアントに返すことができます。
有効なパラメータと戻り値は、Number、Boolean、String、null などの JavaScript プリミティブと、プリミティブ、オブジェクト、配列で構成される JavaScript オブジェクトと配列です。ページ内の form 要素もパラメータとして使用できますが、関数の唯一のパラメータである必要があります。また、戻り値として使用することはできません。Date、Function、form 以外の DOM 要素、またはオブジェクトや配列内の禁止されている型などの他の禁止されている型を渡そうとすると、リクエストは失敗します。循環参照を作成するオブジェクトも失敗し、配列内の未定義のフィールドは null になります。
サーバーに渡されたオブジェクトは、元のオブジェクトのコピーになります。サーバー関数がオブジェクトを受け取ってプロパティを変更しても、クライアントのプロパティは影響を受けません。
成功ハンドラ
クライアントサイドのコードは、サーバー呼び出しの完了を待たずに次の行に進むため、withSuccessHandler(function) を使用すると、サーバーが応答したときに実行するクライアントサイドのコールバック関数を指定できます。サーバー関数が値を返すと、API は値をパラメータとして新しい関数に渡します。
次の例では、サーバーが応答したときにブラウザのアラートを表示します。このコードサンプルでは、サーバーサイド関数が Gmail アカウントにアクセスするため、承認が必要です。スクリプトを承認する最も簡単な方法は、ページを読み込む前にスクリプト エディタから getUnreadEmails() 関数を手動で 1 回実行することです。または、ウェブアプリをデプロイするときに、ウェブアプリにアクセスするユーザーとして実行することもできます。この場合、アプリの読み込み時に承認を求めるメッセージが表示されます。
コード.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>
障害ハンドラ
サーバーが応答しなかった場合やエラーをスローした場合、withFailureHandler(function) では成功ハンドラの代わりに失敗ハンドラを指定できます。この場合、Error オブジェクト（存在する場合）が引数として渡されます。
デフォルトでは、障害ハンドラを指定しない場合、障害は JavaScript コンソールに記録されます。これをオーバーライドするには、withFailureHandler(null) を呼び出すか、何もしない失敗ハンドラを指定します。
次の例に示すように、失敗ハンドラの構文は成功ハンドラとほぼ同じです。
コード.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>
User オブジェクト
サーバーへの複数の呼び出しで同じ成功または失敗ハンドラを再利用するには、withUserObject(object) を呼び出して、ハンドラに渡されるオブジェクトを 2 番目のパラメータとして指定します。この「ユーザー オブジェクト」（User クラスとは異なります）を使用すると、クライアントがサーバーに接続したコンテキストに応答できます。ユーザー オブジェクトはサーバーに送信されないため、関数や DOM 要素など、ほぼすべてのオブジェクトを指定できます。また、サーバー呼び出しのパラメータや戻り値に制限はありません。ただし、ユーザー オブジェクトは new 演算子で作成されたオブジェクトにすることはできません。
この例では、2 つのボタンのいずれかをクリックすると、そのボタンがサーバーからの値で更新され、他のボタンは変更されません。これは、1 つの成功ハンドラを共有しているにもかかわらずです。onclick ハンドラ内では、キーワード this は button 自体を参照します。
コード.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>
フォーム
form 要素をパラメータとしてサーバー関数を呼び出すと、フォームはフィールド名がキー、フィールド値が値の単一オブジェクトになります。値はすべて文字列に変換されます。ただし、ファイル入力フィールドの内容は Blob オブジェクトになります。
この例では、ページを再読み込みせずに、ファイル入力フィールドを含むフォームを処理します。ファイルを Google ドライブにアップロードし、クライアントサイドのページにファイルの URL を出力します。onsubmit ハンドラ内では、キーワード this はフォーム自体を指します。ページ内のすべてのフォームは、読み込み時に preventFormSubmit によってデフォルトの送信アクションが無効になっています。これにより、例外が発生した場合にページが不正確な URL にリダイレクトされるのを防ぐことができます。
コード.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function processForm(formObject) {
var formBlob = formObject.myFile;
var driveFile = DriveApp.createFile(formBlob);
return driveFile.getUrl();
}
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
// Prevent forms from submitting.
function preventFormSubmit() {
var forms = document.querySelectorAll('form');
for (var i = 0; i < forms.length; i++) {
forms[i].addEventListener('submit', function(event) {
event.preventDefault();
});
}
}
window.addEventListener('load', preventFormSubmit);
function handleFormSubmit(formObject) {
google.script.run.withSuccessHandler(updateUrl).processForm(formObject);
}
function updateUrl(url) {
var div = document.getElementById('output');
div.innerHTML = '<a href="' + url + '">Got it!</a>';
}
</script>
</head>
<body>
<form id="myForm" onsubmit="handleFormSubmit(this)">
<input name="myFile" type="file" />
<input type="submit" value="Submit" />
</form>
<div id="output"></div>
</body>
</html>
スクリプト ランナー
google.script.run は「スクリプト ランナー」のビルダーと考えることができます。スクリプト ランナーに成功ハンドラ、失敗ハンドラ、ユーザー オブジェクトを追加しても、既存のランナーは変更されません。代わりに、新しい動作の新しいスクリプト ランナーが返されます。
withSuccessHandler()、withFailureHandler()、withUserObject() は任意の組み合わせと順序で使用できます。値がすでに設定されているスクリプト ランナーで、変更関数を呼び出すこともできます。新しい値は、以前の値を上書きします。
この例では、3 つのサーバー呼び出しすべてに共通の障害ハンドラを設定しますが、2 つの個別の成功ハンドラを設定します。
var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);
myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();
プライベート関数
名前がアンダースコアで終わるサーバー関数は非公開と見なされます。これらの関数は google.script から呼び出すことはできません。また、その名前はクライアントに送信されません。そのため、サーバー上で秘密にしておく必要がある実装の詳細を非表示にできます。また、google.script は、ライブラリ内の関数や、スクリプトのトップレベルで宣言されていない関数も確認できません。
この例では、関数 getBankBalance() はクライアント コードで使用できます。ソースコードを調べるユーザーは、関数を呼び出さなくてもその名前を見つけることができます。ただし、deepSecret_() 関数と obj.objectMethod() 関数はクライアントには完全に非表示です。
コード.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getBankBalance() {
var email = Session.getActiveUser().getEmail()
return deepSecret_(email);
}
function deepSecret_(email) {
// Do some secret calculations
return email + ' has $1,000,000 in the bank.';
}
var obj = {
objectMethod: function() {
// More secret calculations
}
};
Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function onSuccess(balance) {
var div = document.getElementById('output');
div.innerHTML = balance;
}
google.script.run.withSuccessHandler(onSuccess)
.getBankBalance();
</script>
</head>
<body>
<div id="output">No result yet...</div>
</body>
</html>
Google Workspace アプリのダイアログのサイズ変更
Google ドキュメント、スプレッドシート、フォームのカスタム ダイアログ ボックスのサイズを変更するには、クライアントサイド コードで google.script.host メソッド setWidth(width) または setHeight(height) を呼び出します。（ダイアログの初期サイズを設定するには、HtmlOutput メソッド setWidth(width) と setHeight(height) を使用します）。ダイアログはサイズ変更時に親ウィンドウの中央に再配置されず、サイドバーのサイズ変更はできません。
Google Workspaceでダイアログとサイドバーを閉じる
HTML サービスを使用して Google ドキュメント、スプレッドシート、フォームにダイアログ ボックスまたはサイドバーを表示する場合、window.close() を呼び出してインターフェースを閉じることはできません。代わりに、google.script.host.close() を呼び出す必要があります。例については、HTML をユーザー インターフェースとして提供する Google Workspace をご覧ください。
ブラウザのフォーカスを移動する Google Workspace
ユーザーのブラウザでフォーカスをダイアログまたはサイドバーから Google ドキュメント、スプレッドシート、フォーム エディタに戻すには、メソッド google.script.host.editor.focus() を呼び出すだけです。このメソッドは、ドキュメント サービスのメソッド Document.setCursor(position) と Document.setSelection(range) と組み合わせると特に便利です。