このページは 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 要素もパラメータとしては使用できますが、この関数のみのパラメータであり、戻り値としては無効です。form 以外の Date、Function、DOM 要素、または他の禁止された型（オブジェクトや配列内の禁止された型を含む）を渡そうとすると、リクエストは失敗します。循環参照を作成するオブジェクトも失敗し、配列内の未定義のフィールドは null になります。

サーバーに渡されるオブジェクトは、元のオブジェクトのコピーになることに注意してください。サーバー関数がオブジェクトを受け取ってそのプロパティを変更しても、クライアントのプロパティに影響はありません。

成功ハンドラ

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

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

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 つの成功ハンドラが共有されますが、他のボタンは変更せずに、サーバーからの値で更新されます。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に動かしています

スクリプトランナー