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

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

google.script.run は、非同期のクライアントサイド JavaScript API です。これにより、HTML サービスのページからサーバーサイドの Apps Script 関数を呼び出すことができます。次の例は、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() を呼び出す必要があります。例については、 Google Workspace ユーザーインターフェースとして HTML を提供するのセクションをご覧ください。

ブラウザのフォーカスを 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に移動しています

スクリプトランナー