このページは 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 個のスポットのいずれかが解放されるまでサーバー機能が遅延します。実際には、この制限について考える必要はありません。特にほとんどのブラウザで、同じサーバーへの同時リクエストの数が 10 未満の値ですでに制限されているためです。たとえば、Firefox の場合、上限は 6 個です。ほとんどのブラウザは、既存のリクエストのいずれかが完了するまで、同様にサーバーリクエストを過剰に遅延させます。

パラメータと戻り値

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

有効なパラメータと戻り値は、Number、Boolean、String、null などの JavaScript プリミティブに加えて、プリミティブ、オブジェクト、配列から構成される JavaScript オブジェクトと配列です。ページ内の form 要素もパラメータとしては有効ですが、関数の唯一のパラメータである必要があり、戻り値としては無効です。Date、Function、form 以外の DOM 要素、またはその他の禁止されている型（オブジェクトや配列内の禁止された型を含む）を渡そうとすると、リクエストが失敗します。循環参照を作成するオブジェクトも失敗し、配列内の未定義のフィールドは 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>

ユーザーオブジェクト

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

ユーザー オブジェクト

Code.gs

Index.html

フォーム

Code.gs

Index.html

スクリプト ランナー

プライベート関数

Code.gs

Index.html

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

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

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

ユーザーオブジェクト

スクリプトランナー