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

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

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、DOM 要素のほかに、form やその他の禁止されているタイプ（オブジェクトや配列内の禁止されているタイプなど）を渡そうとすると、リクエストは失敗します。循環参照を作成するオブジェクトも失敗し、配列内の未定義フィールドは 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) と組み合わせると特に便利です。

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

コード.gs

Index.html

パラメータと戻り値

成功ハンドラ

コード.gs

Index.html

障害ハンドラ

コード.gs

Index.html

User オブジェクト

コード.gs

Index.html

フォーム

コード.gs

Index.html

スクリプト ランナー

プライベート関数

コード.gs

Index.html

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

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

ブラウザのフォーカスを移動する Google Workspace

スクリプトランナー