「Webアプリの画面にボタンを設置して、GASの裏側で請求書を自動作成できるようになった!……でも、処理が終わったのかまだ動いているのか、画面を見ただけじゃさっぱり分からない……」
前回(第87回)で google.script.run を使ってブラウザからGoogleサーバー側のプログラムを呼び出す仕組みを体験した際、こんなもどかしさを感じませんでしたか?
ボタンを押したあと、画面が「生成中…」のまま固まってしまったり、もし途中でエラーが起きて処理がストップしていても画面には何も表示されず、非エンジニアの同僚から「これ、動いてるの? 壊れちゃった?」と不安そうに聞かれてしまう……。これは、Webアプリ開発を始めたばかりの人が必ず直面する大きな壁です。
札幌オフィスの冬は、猛吹雪の日にJRの運行状況アプリを何度もリロードして「いま電車がどこまで来ているのか」を確認したくなりますが、Webシステムも全く同じです。ユーザーにとっては「いま何が行われていて、無事に終わったのか、それとも失敗したのか」が画面上でハッキリ分かることが、何よりも安心感につながります。
そこで第88回となる今回は、google.script.run の真の相棒である withSuccessHandler()(成功ハンドラー) と withFailureHandler()(失敗ハンドラー) を徹底解説します!
この2つの命令をマスターすると、Google側で請求書作成が終わった瞬間に「🎉 3件の請求書が正常に発行されました!」と画面に爽やかな完了バナーを出し、作成されたGoogleドキュメントへの直リンク一覧をパッと表示させることができます。さらに、万が一エラーが起きたときにも「⚠️ エラーが発生しました:〇〇」と親切なメッセージを出して画面を安全に復帰させることができるようになります。
画面とプログラムが気持ちよく対話する「双方向Webアプリケーション」の完成形を、一緒に楽しく作っていきましょう!
1. そもそも withSuccessHandler / withFailureHandler とは?
前回(第87回)の解説で、google.script.run は「フードコートの呼び出しベル(非同期処理)」のようなものだとお話ししましたよね。
注文カウンター(ブラウザ)で「スープカレーセット(請求書発行)」を注文したあと、手元の画面はフリーズせずに待ち受け状態になります。そして、奥の厨房(Googleサーバー)で料理が完成したとき、手元で「ピピピッ!」と鳴って呼び出してくれる仕掛けこそが、今回学ぶ2つのハンドラーです。
2つのハンドラーの役割分担
| メソッド名 | 呼び出されるタイミング | 受け取るデータ | 主な役割 |
|---|---|---|---|
| withSuccessHandler(関数名) | サーバー側のGAS処理が正常に完了したとき | サーバー側の関数が return した値(オブジェクトや文字列) | 完了通知の表示、ボタンの再有効化、生成ファイルへのリンク表示 |
| withFailureHandler(関数名) | サーバー側のGAS処理でエラー(例外)が起きたとき | エラー情報が入った Error オブジェクト | エラー警告の表示、ボタンの復帰、再試行の案内 |
コードの基本構文(メソッドチェーン)
JavaScriptでは、ドット(.)で数珠つなぎにして命令を連結する「メソッドチェーン」という記法を使います。
// フロントエンド(HTML側のJavaScript)の基本構文
google.script.run
.withSuccessHandler(onSuccess) // 成功したら onSuccess 関数を呼んでね!
.withFailureHandler(onFailure) // 失敗したら onFailure 関数を呼んでね!
.generateInvoices(); // サーバー側の関数を実行!
ポイントは、「サーバー側の関数を呼び出す手前」にハンドラーをセットしておく という順番です。
「成功したときの届け先(withSuccessHandler)」と「失敗したときの連絡先(withFailureHandler)」をあらかじめGoogleに渡してから、「じゃあ、この処理を実行して!」と頼むイメージですね。
2. 成功時・失敗時の「データの流れ」を完全図解!
「ブラウザから送ったデータ」と「サーバーから返ってくるデータ」がどのように行き交うのか、頭の中の地図をスッキリ整理しておきましょう。
① 正常終了時のデータの流れ(Successルート)
【ブラウザ(HTML)】
│ ① ボタンをクリック!
▼
google.script.run.withSuccessHandler(onSuccess).generateInvoices()
│
│ ② インターネット経由でリクエスト送信
▼
【Googleサーバー(コード.gs)】
function generateInvoices() {
// 請求書ドキュメントを3件作成...
return { count: 3, message: "完了しました" }; // ③ 結果を return!
}
│
│ ④ 戻り値をブラウザへ返送
▼
【ブラウザ(HTML)】
function onSuccess(result) {
// ⑤ result の中に { count: 3, message: "完了しました" } が届く!
// 画面に「3件作成完了!」と表示する
}
サーバー側の関数が return で返したデータが、そのままブラウザ側の onSuccess(result) の引数(result)の中にポンと手渡されます。文字列や数値だけでなく、オブジェクトや配列もそのままの形で受け取ることができます!
② エラー発生時のデータの流れ(Failureルート)
【ブラウザ(HTML)】
│ ① ボタンをクリック!
▼
google.script.run.withFailureHandler(onFailure).generateInvoices()
│
│ ② リクエスト送信
▼
【Googleサーバー(コード.gs)】
function generateInvoices() {
// スプレッドシートが見つからない!などのエラー発生
throw new Error("指定されたシートが存在しません。");
}
│
│ ③ エラー情報をブラウザへ緊急返送
▼
【ブラウザ(HTML)】
function onFailure(error) {
// ④ error.message に「指定されたシートが存在しません。」が入る!
// 画面に赤い警告ボックスを出し、ボタンを再有効化する
}
サーバー側で何らかの例外(エラー)が発生すると、withSuccessHandler はスキップされ、自動的に withFailureHandler に登録された関数が呼び出されます。引数の error.message を見ることで、「なぜ失敗したのか」を画面上に分かりやすく表示できる仕組みです。
3. STEP1:準備!前回の「請求管理システム」を確認しよう
それでは、実際のコードを書いて動かしていきましょう!
今回は、前回(第87回)で作成した「札幌オフィス_請求管理システム」のスプレッドシートとプロジェクトをそのまま拡張します。
スプレッドシートの構成確認
スプレッドシート「札幌オフィス_請求管理システム」の「請求データ一覧」シートに、以下のようにテストデータが入っていることを確認してください(F列が「未発行」になっている行が処理対象になります)。
| A列(請求番号) | B列(取引先会社名) | C列(請求日) | D列(品名・内容) | E列(請求金額) | F列(発行ステータス) |
|---|---|---|---|---|---|
| INV-202610-001 | 株式会社札幌スープカレー本舗 | 2026/10/25 | Webサイト改修・SEO対策費用 | 165,000円 | 未発行 |
| INV-202610-002 | 道産子フーズ株式会社 | 2026/10/25 | 業務自動化GASツール開発費用 | 220,000円 | 未発行 |
| INV-202610-003 | 北海ITソリューションズ | 2026/10/25 | クラウドインフラ設計コンサルティング | 330,000円 | 未発行 |
※前回すでに実行してF列が「発行済」になっている場合は、テスト用に手動で「未発行」に戻しておいてくださいね!
4. STEP2:【サーバー側】コード.gs に「処理結果の戻り値」を実装しよう!
まずはバックエンド(コード.gs)の改修からスタートします。
前回のコードでは、請求書を作ったあとに何も返さず return; していました。今回はフロントエンドでリッチな完了通知が出せるように、「発行した件数」 と 「作成された各請求書のファイル名&URLリスト」 をオブジェクトにまとめて return するようにパワーアップさせます!
スプレッドシートの上部メニュー「拡張機能」>「Apps Script」を開き、コード.gs を以下のコードに上書きしてください。
/**
* 札幌オフィス統合ダッシュボード Webアプリケーション
* 第88回:withSuccessHandler / withFailureHandler 実装版
*/
function doGet(e) {
var htmlOutput = HtmlService.createTemplateFromFile('index').evaluate();
htmlOutput.setTitle('【札幌オフィス】請求書発行ダッシュボード');
htmlOutput.addMetaTag('viewport', 'width=device-width, initial-scale=1');
return htmlOutput;
}
/**
* サーバー側:請求書一括生成処理
* 完了時に作成結果のオブジェクト(件数、ファイル情報リスト)をフロントへ返す!
*/
function generateInvoices() {
Logger.log("=== 請求書一括生成処理を開始します ===");
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheetByName("請求データ一覧");
// シートの存在チェック(エラーハンドリングの実験用ガード)
if (!sheet) {
throw new Error("シート「請求データ一覧」が見つかりませんでした。スプレッドシートを確認してください。");
}
var lastRow = sheet.getLastRow();
if (lastRow < 2) {
return {
success: true,
count: 0,
invoices: [],
message: "対象となるデータ行がありませんでした。"
};
}
// 2行目から最終行までのデータを一括取得(第13回 Range.getValues)
var values = sheet.getRange(2, 1, lastRow - 1, 6).getValues();
var createdInvoices = []; // 生成したファイル情報を格納する配列
for (var i = 0; i < values.length; i++) {
var invoiceNo = values[i][0]; // A列: 請求番号
var companyName = values[i][1]; // B列: 会社名
var rawDate = values[i][2]; // C列: 請求日
var itemName = values[i][3]; // D列: 品名
var amount = values[i][4]; // E列: 金額
var status = values[i][5]; // F列: 発行ステータス
// 「未発行」の行だけを処理する
if (status === "未発行") {
var dateText = Utilities.formatDate(new Date(rawDate), "Asia/Tokyo", "yyyy年MM月dd日");
// Googleドキュメントの請求書を自動作成(第51回〜第60回の復習)
var docName = "【御請求書】" + companyName + "_" + invoiceNo;
var doc = DocumentApp.create(docName);
var body = doc.getBody();
// タイトル
var titlePara = body.appendParagraph("御 請 求 書");
titlePara.setHeading(DocumentApp.Heading.TITLE);
titlePara.setAlignment(DocumentApp.HorizontalAlignment.CENTER);
body.appendParagraph("請求番号:" + invoiceNo);
body.appendParagraph("請求日:" + dateText);
body.appendParagraph("");
body.appendParagraph(companyName + " 御中").setHeading(DocumentApp.Heading.HEADING2);
body.appendParagraph("平素は格別のお引き立てを賜り、厚く御礼申し上げます。\n下記の通りご請求申し上げます。");
body.appendParagraph("");
// 金額装飾(第55回)
var amountPara = body.appendParagraph("ご請求金額:" + amount + "(税込)");
amountPara.setFontSize(18);
amountPara.setBold(true);
amountPara.setForegroundColor("#C00000"); // 札幌コーポレートレッド
body.appendParagraph("");
// 明細表(第56回・第57回)
var table = body.appendTable([
["品名・作業内容", "ご請求金額"],
[itemName, amount]
]);
table.getRow(0).getCell(0).setBackgroundColor("#1A365D").editAsText().setForegroundColor("#FFFFFF").setBold(true);
table.getRow(0).getCell(1).setBackgroundColor("#1A365D").editAsText().setForegroundColor("#FFFFFF").setBold(true);
body.appendParagraph("");
body.appendParagraph("【お振込先】\n北洋銀行 札幌駅前支店 普通 1234567\n口座名義:カ)デジタルワンダーランド");
doc.saveAndClose();
// スプレッドシート側のステータスを「発行済」に更新(第6回 setValue)
sheet.getRange(i + 2, 6).setValue("発行済");
// 生成したファイルの情報を配列に追加
createdInvoices.push({
no: invoiceNo,
company: companyName,
url: doc.getUrl(),
amount: amount
});
}
}
Logger.log("=== 処理完了: " + createdInvoices.length + " 件発行 ===");
// ★超重要!フロントエンド(withSuccessHandler)へ返す実行結果オブジェクト
return {
success: true,
count: createdInvoices.length,
invoices: createdInvoices,
timestamp: Utilities.formatDate(new Date(), "Asia/Tokyo", "HH:mm:ss")
};
}
末尾の return { ... } に注目してください!
発行した件数(count)や、作成されたファイルのURLリスト(invoices)をひとまとめのオブジェクトとして返却しています。このデータが、次のステップでブラウザ側の画面を彩る材料になります。
5. STEP3:【フロント側】index.html に成功&失敗ハンドラーを実装しよう!
続いて、ブラウザ画面となる index.html を編集します。
今回は、以下の本格的なUI制御を組み込みます。
- 処理中:ボタンを無効化し、ぐるぐる回るスピナーと「処理中メッセージ」を表示する
- 成功時(withSuccessHandler):緑色のサクセスバナーを表示し、発行された請求書ドキュメントへのリンク一覧をカード内に動的レンダリングする
- 失敗時(withFailureHandler):赤色のエラーバナーを表示し、エラー原因を表示してボタンを再試行可能な状態へ復帰させる
左側のファイル一覧から index.html を開き、以下の完全版コードで上書き保存してください。
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<base target="_top">
<title>札幌オフィス 請求書発行ダッシュボード</title>
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: "Helvetica Neue", Arial, "Hiragino Kaku Gothic ProN", sans-serif;
background-color: #f0f4f8;
color: #2d3748;
padding: 40px 20px;
display: flex;
justify-content: center;
align-items: flex-start;
min-height: 100vh;
}
.card {
background-color: #ffffff;
max-width: 650px;
width: 100%;
border-radius: 12px;
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
padding: 32px;
border-top: 5px solid #1a365d;
}
.header {
margin-bottom: 24px;
border-bottom: 1px solid #edf2f7;
padding-bottom: 16px;
}
h1 {
font-size: 20px;
color: #1a365d;
margin-bottom: 6px;
}
.lead {
font-size: 13px;
color: #718096;
line-height: 1.6;
}
.action-box {
background-color: #f7fafc;
border: 1px solid #e2e8f0;
border-radius: 8px;
padding: 24px;
text-align: center;
margin-bottom: 24px;
}
/* アクションボタン */
.btn-generate {
background-color: #dd6b20; /* 札幌オレンジ */
color: #ffffff;
font-size: 16px;
font-weight: 700;
padding: 14px 28px;
border: none;
border-radius: 8px;
cursor: pointer;
box-shadow: 0 4px 10px rgba(221, 107, 32, 0.3);
transition: all 0.2s ease;
display: inline-flex;
align-items: center;
justify-content: center;
gap: 10px;
width: 100%;
max-width: 320px;
}
.btn-generate:hover:not(:disabled) {
background-color: #c05621;
transform: translateY(-2px);
box-shadow: 0 6px 14px rgba(221, 107, 32, 0.4);
}
.btn-generate:disabled {
background-color: #a0aec0;
cursor: not-allowed;
box-shadow: none;
transform: none;
}
/* ローディングスピナー */
.spinner {
display: none;
width: 18px;
height: 18px;
border: 3px solid rgba(255, 255, 255, 0.3);
border-radius: 50%;
border-top-color: #ffffff;
animation: spin 0.8s linear infinite;
}
@keyframes spin {
to { transform: rotate(360deg); }
}
/* メッセージ通知バナー */
.banner {
display: none;
padding: 16px;
border-radius: 8px;
font-size: 14px;
line-height: 1.5;
margin-top: 20px;
text-align: left;
}
.banner-success {
background-color: #f0fff4;
border: 1px solid #9ae6b4;
color: #22543d;
}
.banner-error {
background-color: #fff5f5;
border: 1px solid #feb2b2;
color: #9b2c2c;
}
.banner-title {
font-weight: bold;
margin-bottom: 4px;
display: flex;
align-items: center;
gap: 6px;
}
/* 生成された請求書リスト */
.invoice-list {
list-style: none;
margin-top: 12px;
padding-top: 12px;
border-top: 1px dashed #9ae6b4;
}
.invoice-item {
display: flex;
justify-content: space-between;
align-items: center;
padding: 8px 0;
font-size: 13px;
}
.invoice-link {
color: #2b6cb0;
text-decoration: none;
font-weight: 600;
display: inline-flex;
align-items: center;
gap: 4px;
}
.invoice-link:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div class="card">
<div class="header">
<h1>📑 札幌オフィス 請求書発行ダッシュボード</h1>
<p class="lead">スプレッドシートの未発行データを読み込み、取引先ごとの請求書ドキュメントを一括生成します。</p>
</div>
<div class="action-box">
<!-- 発行ボタン -->
<button id="execBtn" class="btn-generate" onclick="onClickGenerateButton()">
<div id="btnSpinner" class="spinner"></div>
<span id="btnText">⚡ 請求書を一括自動発行する</span>
</button>
<!-- 成功通知バナー -->
<div id="successBanner" class="banner banner-success">
<div class="banner-title">
<span>🎉</span>
<span id="successTitle">請求書の発行が完了しました!</span>
</div>
<p id="successDetail" style="font-size: 13px;"></p>
<ul id="invoiceResultList" class="invoice-list"></ul>
</div>
<!-- エラー通知バナー -->
<div id="errorBanner" class="banner banner-error">
<div class="banner-title">
<span>⚠️</span>
<span>エラーが発生しました</span>
</div>
<p id="errorMessage" style="font-size: 13px;"></p>
</div>
</div>
</div>
<script>
/**
* ボタンクリック時の処理
*/
function onClickGenerateButton() {
var btn = document.getElementById("execBtn");
var btnText = document.getElementById("btnText");
var spinner = document.getElementById("btnSpinner");
var successBanner = document.getElementById("successBanner");
var errorBanner = document.getElementById("errorBanner");
// ① バナーを非表示にしてリセット
successBanner.style.display = "none";
errorBanner.style.display = "none";
// ② ボタンを「処理中」の状態に変更(連打防止!)
btn.disabled = true;
btnText.innerText = "請求書を生成中...";
spinner.style.display = "inline-block";
// ③ 【最重要】google.script.run に成功&失敗ハンドラーをチェーンして呼び出す!
google.script.run
.withSuccessHandler(onSuccess)
.withFailureHandler(onFailure)
.generateInvoices();
}
/**
* 成功時コールバック関数(サーバーから return された結果オブジェクトを受け取る)
*/
function onSuccess(response) {
var btn = document.getElementById("execBtn");
var btnText = document.getElementById("btnText");
var spinner = document.getElementById("btnSpinner");
var successBanner = document.getElementById("successBanner");
var successDetail = document.getElementById("successDetail");
var resultList = document.getElementById("invoiceResultList");
// ① ボタンを通常状態へ復旧
btn.disabled = false;
btnText.innerText = "⚡ 請求書を一括自動発行する";
spinner.style.display = "none";
// ② 結果の表示
if (response.count === 0) {
successDetail.innerText = "対象となる未発行データはありませんでした。(" + response.timestamp + " 同期)";
resultList.innerHTML = "";
} else {
successDetail.innerText = "合計 " + response.count + " 件の請求書ドキュメントを作成しました。(" + response.timestamp + " 完了)";
// ③ 作成されたドキュメントのリンク一覧を動的に生成
var html = "";
for (var i = 0; i < response.invoices.length; i++) {
var item = response.invoices[i];
html += '<li class="invoice-item">' +
'<span><b>' + item.company + '</b> (' + item.amount + ')</span>' +
'<a href="' + item.url + '" target="_blank" class="invoice-link">📄 ドキュメントを開く ↗</a>' +
'</li>';
}
resultList.innerHTML = html;
}
// ④ 成功バナーをスッと表示!
successBanner.style.display = "block";
}
/**
* 失敗時コールバック関数(サーバー側で起きたエラー情報を受け取る)
*/
function onFailure(error) {
var btn = document.getElementById("execBtn");
var btnText = document.getElementById("btnText");
var spinner = document.getElementById("btnSpinner");
var errorBanner = document.getElementById("errorBanner");
var errorMessage = document.getElementById("errorMessage");
// ① ボタンを再試行できるように復帰
btn.disabled = false;
btnText.innerText = "⚡ 請求書を一括自動発行する";
spinner.style.display = "none";
// ② エラーメッセージを親切に表示
errorMessage.innerText = "処理中に問題が発生しました:\n" + error.message;
// ③ エラーバナーを表示!
errorBanner.style.display = "block";
}
</script>
</body>
</html>
6. STEP4:【動作確認】テスト用URL(/dev)で成功と失敗の画面制御を体感しよう!
コードが保存できたら、さっそく「デプロイをテスト」からテスト用URL(末尾が /dev のURL)を開いて、画面の動きをテストしてみましょう!
実験①:正常系テスト(サクセス通知とリンクリストの確認)
スプレッドシートのF列が「未発行」になっている状態で、Webアプリ画面の「⚡ 請求書を一括自動発行する」ボタンをクリックしてみてください。
- ボタンがグレーに変わり、左側で白いスピナーがくるくると回転し始める
- 数秒待つと……ボタンが元に戻り、画面下にパッと鮮やかな薄緑色の成功バナーが出現!
- 「🎉 請求書の発行が完了しました! 合計 3 件の請求書ドキュメントを作成しました。」というメッセージが表示される
- その下に、株式会社札幌スープカレー本舗、道産子フーズ株式会社、北海ITソリューションズの3社分の「📄 ドキュメントを開く ↗」リンクが綺麗にリスト表示される!
- リンクをクリックすると、新しく生成されたGoogleドキュメントが別タブで直接開く!
前回の「ボタンを押したけど終わったのか分からない状態」から一変、ユーザーが次のアクション(ドキュメントの確認)まで迷わず進める、完璧なUIへと進化しましたね!
実験②:異常系テスト(エラーバナーの自動表示を確認)
今度は、あえてエラーを発生させて withFailureHandler が正しく動くかを試してみましょう。
スプレッドシートの画面に戻り、シートタブの名前「請求データ一覧」を一時的に「請求データ一覧_テスト」に変更してみてください(GAS側の getSheetByName("請求データ一覧") が見つからなくなる状態を作ります)。
その状態で、もう一度Webアプリの画面から発行ボタンを押してみます。
- 「請求書を生成中…」のスピナーが回る
- 約1〜2秒後、今度は赤色のエラーバナーがパッと表示される!
- 「⚠️ エラーが発生しました:処理中に問題が発生しました:シート「請求データ一覧」が見つかりませんでした。スプレッドシートを確認してください。」と、GAS側で投げたエラー文言がそのまま表示される!
- ボタンが自動的に復帰し、再試行可能な状態に戻る!
確認が終わったら、スプレッドシートのシート名を元の「請求データ一覧」に戻しておきましょう。
このように、システムトラブルが起きたときでも画面が固まることなく、「何が原因で止まったのか」をユーザーに的確に伝えられるのが withFailureHandler の最大の強みです。
7. 実務で差がつく!「ハンドラー活用」のプロ技3選
成功と失敗の基本がマスターできたら、現場のプロダクト開発で必ず役立つ3つの発展テクニックを押さえておきましょう!
プロ技①:ボタン連打防止(二重送信防止)の完全ライフサイクル
Webアプリで最も多いバグが、ボタンの連打による「二重登録・多重実行」です。今回のコードでは、以下のライフサイクルを徹底しています。
- クリック直後:
btn.disabled = true;で即座にボタンをロックし、スピナーを回す - 成功時(onSuccess):
btn.disabled = false;でボタンを戻す - 失敗時(onFailure):
btn.disabled = false;でボタンを戻す(ここを忘れると、失敗した後に二度とボタンが押せなくなってしまいます!)
成功時だけでなく「失敗したときにも必ずボタンを元に戻す」のが、ユーザーを迷わせないプロの鉄則です。
プロ技②:withUserObject() で画面側のコンテキストを引き継ぐ
一覧表の中に複数のボタンが並んでいて、「3行目のボタンが押された」「クリックされた行だけを完了表示にしたい」という場面がありますよね。
そんなときに活躍するのが .withUserObject(任意の値) です!
// 押されたボタン自身(this)を userObject として引き渡す例
function onRowButtonClick(btnElement, rowId) {
btnElement.disabled = true;
google.script.run
.withSuccessHandler(function(result, element) {
// 第2引数 element に、さっき渡した btnElement がそのまま届く!
element.innerText = "済";
element.classList.add("btn-done");
})
.withUserObject(btnElement) // ← ここで画面側の要素を預ける!
.processSingleRow(rowId);
}
withSuccessHandler(function(result, userObject) { ... }) のように第2引数で受け取れるため、「どのボタンが押された結果なのか」をコールバック関数の中で簡単に特定できます。
プロ技③:サーバー側からは常に「JSONライクなオブジェクト」で返す
サーバー側の関数から、単に return "完了"; と文字列だけを返すのはもったいないです。
今回のSTEP2のように、以下のような構造のオブジェクトで返す設計にしておくと、フロントエンド側での表現力が何倍にも広がります。
// サーバー側の推奨 return 設計
return {
success: true, // 成功フラグ
count: 3, // 処理件数
data: [...], // 生成したデータやURL
message: "正常終了", // ユーザー向けメッセージ
timestamp: "14:30:15" // 処理時刻
};
8. 初心者が100%つまずく!5大トラップと完全対処法
withSuccessHandler や withFailureHandler を使う際、開発者が必ずと言っていいほど直面するエラーや落とし穴をまとめました。困ったときはまずここを確認してください!
トラップ1:ハンドラー名にカッコ () を付けて即時実行してしまう大事故!
初心者事故率No.1のトラップです!
// ✕ 絶対にやってはいけないNGコード(カッコが付いている!)
google.script.run
.withSuccessHandler(onSuccess()) // ← サーバーの完了を待たずに今すぐ実行されてしまう!
.generateInvoices();
// ◯ 正しい書き方(関数名だけを渡す)
google.script.run
.withSuccessHandler(onSuccess) // ← カッコは付けない!
.generateInvoices();
onSuccess() とカッコを書いてしまうと、「サーバーから結果が返ってきたとき」ではなく、「ボタンを押したその瞬間」に関数が実行されてしまいます。その結果、まだ処理が終わっていないのに result が undefined のまま成功処理が走って画面が崩れてしまいます。必ずカッコなしの onSuccess で渡しましょう!
トラップ2:サーバー側で return を書き忘れて response が null になる
サーバー側の generateInvoices() の最後で return を書き忘れると、処理自体は成功しても、ブラウザ側の onSuccess(response) に届く response は null(または undefined)になります。
「response.count を読もうとしたら Cannot read property 'count' of null と怒られた!」という場合は、コード.gs の末尾に return { ... }; がちゃんと書かれているか確認してください。
トラップ3:try…catch でエラーを握りつぶして withSuccessHandler に流れてしまう
サーバー側で第30回の try...catch を書いたときによくある落とし穴です。
// ✕ 失敗例:エラーをキャッチしたのに何事もなかったかのように終了している
function generateInvoices() {
try {
// 重大なエラーが発生!
} catch (e) {
Logger.log("エラー: " + e.message);
// そのまま関数が終わってしまう ➔ GASは「正常終了」と判断!
}
}
catch の中でエラーを記録するだけで終わってしまうと、GASは「エラーは無事に解決されたんだな」と判断し、ブラウザ側では withSuccessHandler のほうが動いてしまいます。
エラーが起きたことをブラウザに知らせたい場合は、catch の中で throw e;(エラーを再スロー)するか、return { success: false, error: e.message }; のように明示的なエラーオブジェクトを返すように設計しましょう。
トラップ4:サーバー側から返せないデータ型を渡して通信エラー
前回のルールでも触れましたが、サーバー側から return できるデータは「JSON形式に変換できるもの(文字列、数値、真偽値、配列、プレーンなオブジェクト)」だけです。
return doc;(Documentオブジェクトそのもの) ➔ エラー!return sheet;(Sheetオブジェクトそのもの) ➔ エラー!return new Date();➔ 環境によって壊れやすいので、Utilities.formatDateで文字列にしてから返すのが安全!
トラップ5:メソッドチェーンの順番間違い
// ✕ 間違った順番(実行関数のあとにハンドラーを書いている)
google.script.run
.generateInvoices()
.withSuccessHandler(onSuccess); // エラーになります!
必ず google.script.run.withSuccessHandler(...).実行関数() の順番で書きましょう。「ハンドラーの設定が先、関数の実行が最後!」が鉄の掟です。
9. 今回のまとめ&次回予告
今回は、WebアプリケーションのUI制御に欠かせない withSuccessHandler() と withFailureHandler() の使い方を徹底解説しました!
本日の重要ポイントおさらい
withSuccessHandler(関数名)で、サーバー側の正常終了時に戻り値を受け取って画面を更新できる!withFailureHandler(関数名)で、サーバー側のエラー発生時に親切な警告画面を表示できる!- ハンドラーに渡す関数名には、絶対にカッコ
()を付けない! - サーバー側は
return { count: 3, ... }のようにオブジェクトで結果を返すと、フロントでの表現力が爆上がりする! - ボタン連打を防ぐため、クリック直後に無効化し、成功・失敗どちらのルートでも必ずボタンを復帰させるのがプロの作法!
これで、ユーザーがボタンを押してから処理が終わり、次の作業に進むまでの一連の流れ(UX:ユーザー体験)が完璧に整いました!
もう「処理中なのかエラーなのか分からない」なんて同僚に心配されることもありませんね。
🚀 次回予告:外部からのデータ受信用API窓口を開設しよう!
ここまでの回では、「人間がブラウザを開いてボタンを押す」という画面操作を中心としたWebアプリを作ってきました。
でも、自動化の世界は画面操作だけにとどまりません!
「社外の問い合わせフォームからデータが送信されたとき、GASが裏側で自動でデータを受け取ってスプレッドシートに追記してほしい」
「札幌オフィスの入口にある出退勤の打刻端末(IoT機器など)からPOST通信を受け取って、自動で出勤簿を更新したい!」
といった、システム同士の自動連携(API連携) がしたくなる瞬間が必ずやってきます。
そこで次回(第89回)は、外部システムからデータを受信するための専用API窓口を開設する doPost(e) & ContentService を徹底解説します!
GASが「Web画面」だけでなく「Web API」としても機能する超強力なステップに進みますので、ぜひ次回も楽しみに待っていてくださいね!
