このページは Cloud Translation API によって翻訳されました。

HTML サービス: サーバー機能と通信する

google.script.run は、HTML サービスページからサーバーサイドの Apps Script 関数を呼び出すことを可能にする、非同期のクライアントサイド JavaScript API です。次の例は、google.script.run の最も基本的な機能（クライアント側の JavaScript からサーバーで関数を呼び出す）を示しています。

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>
</html>

このスクリプトをウェブアプリとしてデプロイし、その URL にアクセスすると何も表示されませんが、ログを表示すると、サーバー関数 doSomething() が呼び出されたことがわかります。

サーバー側関数に対するクライアントサイドの呼び出しは非同期です。ブラウザがサーバーに関数 doSomething() の実行をリクエストすると、ブラウザはレスポンスを待たずに直ちにコードの次の行に進みます。つまり、サーバー関数の呼び出しが想定どおりに実行されない場合があります。同時に 2 つの関数呼び出しを行った場合、どちらの関数が最初に実行されるかを把握することはできません。そのため、ページが読み込まれるたびに結果が異なる可能性があります。この場合、成功ハンドラと失敗ハンドラがコードのフローの制御に役立ちます。

google.script.run API を使用すると、サーバー関数に対して 10 件の同時呼び出しが可能になります。10 個のスポットが稼働しているときに 11 回目の呼び出しを行うと、10 個のスポットのうちの 1 つが解放されるまでサーバー関数は遅延します。この制限について考える必要はほとんどありません。特にほとんどのブラウザでは、同じサーバーへの同時リクエスト数がすでに 10 未満に制限されているためです。たとえば、Firefox の場合、この制限は 6 回です。ほとんどのブラウザでは、既存のリクエストのいずれかが完了するまで、過剰なサーバーリクエストを遅延させます。

パラメータと戻り値

クライアントからパラメータを使用してサーバー関数を呼び出すことができます。同様に、サーバー関数は成功ハンドラに渡されるパラメータとしてクライアントに値を返すことができます。

有効なパラメータと戻り値は、Number、Boolean、String、null などの JavaScript プリミティブと、プリミティブ、オブジェクト、配列で構成される JavaScript オブジェクトと配列です。ページ内の form 要素もパラメータとして使用できますが、これは関数の唯一のパラメータである必要があり、戻り値としては有効ではありません。Date、Function、DOM 要素のほかに、form やその他の禁止されているタイプ（オブジェクトや配列内の禁止されているタイプなど）を渡そうとすると、リクエストは失敗します。循環参照を作成するオブジェクトも失敗し、配列内の未定義のフィールドは null になります。

サーバーに渡されるオブジェクトは、元のオブジェクトのコピーになります。サーバー関数がオブジェクトを受信してそのプロパティを変更しても、クライアントのプロパティには影響しません。

成功ハンドラ

クライアントサイドのコードは、サーバー呼び出しの完了を待たずに次の行に進むため、withSuccessHandler(function) を使用すると、サーバーが応答したときに実行するクライアントサイドのコールバック関数を指定できます。サーバー関数が値を返すと、API はその値をパラメータとして新しい関数に渡します。

次の例では、サーバーが応答したときにブラウザのアラートを表示します。このコードサンプルでは、サーバー側の関数が Gmail アカウントにアクセスするため、承認が必要です。スクリプトを承認する最も簡単な方法は、ページを読み込む前にスクリプトエディタから getUnreadEmails() 関数を手動で 1 回実行することです。また、ウェブアプリをデプロイするときに、「ウェブアプリにアクセスするユーザー」として実行することもできます。その場合は、アプリを読み込むときに承認を求められます。

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>

障害ハンドラ

サーバーが応答しない場合やエラーをスローした場合は、withFailureHandler(function) を使用して、成功ハンドラの代わりに失敗ハンドラを指定できます。その際、Error オブジェクト（存在する場合）を引数として渡します。

デフォルトでは、エラーハンドラを指定しない場合、エラーは 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>

User オブジェクト

サーバーに対する複数の呼び出しで同じ成功ハンドラまたは失敗ハンドラを再利用するには、withUserObject(object) を呼び出して、ハンドラに 2 番目のパラメータとして渡されるオブジェクトを指定します。この「ユーザーオブジェクト」（User クラスと混同しないでください）を使用すると、クライアントがサーバーに接続したコンテキストに応答できます。ユーザーオブジェクトはサーバーに送信されないため、サーバー呼び出しのパラメータや戻り値に制限なく、関数や DOM 要素など、ほぼあらゆるものを使用できます。ただし、ユーザーオブジェクトを new 演算子で構築されたオブジェクトにすることはできません。

この例では、2 つのボタンのいずれかをクリックすると、そのボタンはサーバーから取得した値で更新され、もう 1 つのボタンは、1 つの成功ハンドラを共有している場合でも変更されません。onclick ハンドラ内で、キーワード this が button 自体を参照します。

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>

フォーム

form 要素をパラメータとして使用してサーバー関数を呼び出すと、フォームは、フィールド名をキー、フィールド値を値として持つ単一のオブジェクトになります。Blob オブジェクトになるファイル入力フィールドの内容を除き、値はすべて文字列に変換されます。

この例では、ページを再読み込みせずに、ファイル入力フィールドを含むフォームを処理し、ファイルを Google ドライブにアップロードして、クライアントサイドページにファイルの URL を出力します。onsubmit ハンドラ内で、キーワード this がフォーム自体を参照します。なお、ページ内のすべてのフォームを読み込む際、デフォルトの送信アクションは preventFormSubmit により無効になります。これにより、例外の発生時にページが不正確な URL にリダイレクトされるのを防ぐことができます。

Code.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() はクライアントからはまったく表示されません。

Code.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) と組み合わせて使用すると特に便利です。

HTML サービス: サーバー機能と通信する

Code.gs

Index.html

パラメータと戻り値

成功ハンドラ

Code.gs

Index.html

障害ハンドラ

Code.gs

Index.html

User オブジェクト

Code.gs

Index.html

フォーム

Code.gs

Index.html

スクリプト ランナー

非公開関数

Code.gs

Index.html

アプリケーションの Google Workspace ダイアログのサイズ変更

Google Workspaceのダイアログとサイドバーを閉じる

ブラウザの Google Workspaceのフォーカスを移動しています

スクリプトランナー