【GAS入門#97】API連打でエラーを出さない!Utilities.sleep()の使い方とレートリミット対策(ウェイト制御)完全攻略

「前回の記事を参考にして、スプレッドシートのデータをループ処理で一気にSlackへ通知しようとしたら、途中で『429 Too Many Requests』という見慣れないエラーが出てプログラムが止まってしまった……」

「外部のAPIサーバーから数百件のデータを繰り返し取得しようとしたら、急に通信をブロックされて締め出されてしまった……」

GAS(Google Apps Script)で外部サービスとの連携や自動送信ができるようになってくると、多くの開発者が必ずこの「連続アクセスの壁」にぶつかります。

前回(第96回)は、UrlFetchApp.fetch() のPOST通信を使って、Slackの #sapporo-dashboard チャンネルへリッチな請求書発行通知や異常検知アラートを送信する方法を学びましたよね。1件や2件の通知を送る分には完璧に動きますが、調子に乗って「よし、未処理の案件50件を一瞬で全部通知させよう!」と for ループの中で通信を猛連打すると、相手のサーバーから「アクセスが急激すぎます!少し落ち着いてください!」と怒られてしまうのです。

冬の札幌でも、朝のラッシュ時に新千歳空港へ向かうJR快速エアポートの改札や、チカホ(札幌駅前通地下歩行空間)からオフィスビルへ入る自動ドアに人が一気に押し寄せると、いくら通路が広くても詰まってしまいますよね。セコマのホットシェフだって、揚げたてのフライドチキンを一度に50個注文されたら厨房がパンクしてしまいます。プログラムの世界も全く同じで、どんなに優秀なサーバーであっても「人間ではあり得ない超高速の連打アクセス」が届くと、サーバーを守るためにシャッターをガラガラと降ろしてしまうのです。

そんなトラブルを防ぎ、相手のサーバーと仲良く安全に大量通信を行うために欠かせないのが、プログラムに「あえてスマートな休憩時間」を挟み込むGAS標準の便利メソッド Utilities.sleep()(ユーティリティーズ・スリープ) です!

今回は、外部API連携における最重要マナーである「ウェイト制御(レートリミット対策)」をテーマに、Utilities.sleep() の基本構文からミリ秒の感覚、実務で絶対に落ちないSlack連続通知のループ設計、さらにはプロの現場で必須となる「指数バックオフ(リトライ処理)」まで、どこよりも分かりやすく丁寧に解説していきます!

1. そもそも Utilities.sleep() とは?「プログラムの一時停止ボタン」

まずは、今回新しく覚える命令の仕組みと役割から紐解いていきましょう。

Utilities.sleep() は、Google Apps Scriptの処理を指定した時間だけ完全に「一時停止(待機)」させるための命令(メソッド)です。

// プログラムの実行を「3秒間」ピタッと一時停止する
Utilities.sleep(3000);

コードの構造はとてもシンプルです。第29回の日付フォーマットでも登場した、GASの便利ツール箱である Utilities クラスに対して、.sleep(待機時間) と指示を出すだけです。

超重要!時間の単位は「秒」ではなく「ミリ秒(ms)」

Utilities.sleep() を使う上で、初心者が一番最初につまずくポイントが「カッコの中に指定する数値の単位」です。

プログラミングの世界では、時間は基本的に ミリ秒(1/1000秒) で指定します。

止めたい時間コードでの指定数値解説
0.5秒500500ミリ秒
1秒10001,000ミリ秒(★ウェイトの基本単位!)
2秒20002,000ミリ秒
3秒30003,000ミリ秒
5秒50005,000ミリ秒

もし「3秒待たせたいな」と思って Utilities.sleep(3); と書いてしまうと、コンピューターは「3ミリ秒(0.003秒)待てばいいのね!」と解釈し、まばたきをするよりも一瞬で次の行へ進んでしまいます。「1秒 = 1000」という換算ルールをしっかり頭に叩き込んでおきましょう!

2. なぜ外部APIを連打してはダメなの?「レートリミット(429エラー)」の正体

「プログラムなんだから、待たずに1秒で100回通信したほうが処理が早く終わって良いんじゃないの?」と思う方もいるかもしれません。しかし、Web API連携の世界には「レートリミット(Rate Limit / 利用制限)」という厳格なルールが存在します。

相手のサーバーが身を守るための「自己防衛機能」

人間が手作業でブラウザをクリックしたりメッセージを送信する場合、どんなにキーボード操作が速い人でも、1秒間に送れるリクエストはせいぜい1〜2回程度ですよね。

ところが、コンピューター(プログラム)が本気を出すと、1秒間に数百回〜数千回もの通信を一瞬で浴びせかけることができてしまいます。もし世界中のユーザーがそんなプログラムを一斉に動かしたら、相手のサーバーは過剰な負荷でパンクし、サービス全体がダウンしてしまいます。最悪の場合、悪意のあるサイバー攻撃(DoS攻撃)と区別がつきません。

そのため、SlackやLINE、Twitter(X)、各種Web APIサービスは、ほぼ例外なく以下のような防御ルールを設けています。

  • 「1秒間に送っていいのは原則1回まで」
  • 「1分間に送信できるのは最大60回まで」
  • 「短時間の連打を検知したら、その通信を強制切断する」

恐怖のエラーコード「429 Too Many Requests」

この制限を超えて通信を連打した瞬間、相手のサーバーから返されるのが HTTPステータスコード「429 Too Many Requests(リクエストが多すぎます)」 です。

このエラーが発生すると、以下のような深刻なトラブルにつながります。

  1. 処理が途中で強制中断する:50件中10件送ったところでプログラムがクラッシュし、誰に送れて誰に送れていないのか分からなくなる。
  2. ペナルティ(通信ブロック):制限を超えたペナルティとして、相手のサービスから「今後15分間はあなたの通信を一切受け付けません」と締め出されてしまう。

だからこそ、ループ処理の中で UrlFetchApp.fetch() を呼び出す直前や直後に Utilities.sleep(1000〜1500) を挟み込み、「1回送ったら、1秒ちょっと優しく深呼吸して待つ」 という紳士的なウェイト制御を入れることが、プロのエンジニアとしてシステムを安定運用するための絶対の鉄則なのです!

3. STEP1:準備!「札幌オフィス備品調達・取引先連絡リスト」を用意しよう

それでは、実際に手元の環境でウェイト制御を体験するための練習用スプレッドシートを作成していきましょう!

今回は、札幌オフィスの冬支度(除雪スコップや暖房器具、ホットシェフ差し入れなど)の備品発注を想定し、複数の案件に対して順番に外部通知をシミュレーションするリストを用意します。

スプレッドシートの作成手順:

  1. ブラウザで Googleドライブ を開き、新しいGoogleスプレッドシートを作成します。
  2. ファイル名を 「札幌オフィス_外部連携管理簿」 に変更します。
  3. 画面下のシートタブ名を 「通知対象リスト」 に変更します。
  4. 1行目に見出し、2行目以降に以下のようなサンプルデータを5行ほど入力してください。
A列(発注ID)B列(品名・案件名)C列(発注先会社名)D列(数量)E列(ステータス)
ORD-001オフィス用大型除雪スコップ札幌金物卸センター4本未送信
ORD-002足元用遠赤外線パネルヒーター道産子電器チェーン6台未送信
ORD-003チカホ通勤用・靴用滑り止めスパイク北海セーフティ用品10セット未送信
ORD-004ホワイトボード用マーカーセット大通文具プラザ2箱未送信
ORD-005残業用フライドチキン差し入れクーポンセコマフードサービス15枚未送信

シートの準備ができたら、上部メニューバーの 「拡張機能」 > 「Apps Script」 をクリックして、GASのエディタ画面を開いておきましょう!

4. STEP2:【実践】Utilities.sleep() の基本動作とミリ秒の感覚を掴もう!

まずは、Utilities.sleep() が本当に指定した秒数だけプログラムを一時停止させているのか、実行ログを使って目に見える形で実験してみましょう!

第1回で学んだ Logger.log() と、第29回で学んだ Utilities.formatDate() を活用して、待機前後の正確な時刻を記録します。

/**
* 第97回 STEP2:Utilities.sleep() の基本動作検証
* 待機前後のタイムスタンプを出力して、停止時間を確認します。
*/
function testSleepBasic() {
Logger.log("=== 待機実験スタート ===");

// 1. 待機前の現在時刻をログ出力(秒単位まで表示)
var beforeTime = Utilities.formatDate(new Date(), "Asia/Tokyo", "HH:mm:ss.SSS");
Logger.log("■ 停止前の時刻 : " + beforeTime);

// 2. ここでプログラムを「2.5秒間(2500ミリ秒)」停止させる!
Logger.log("⏳ 2.5秒間(2500ms)のウェイトに入ります...");
Utilities.sleep(2500);

// 3. 待機後の現在時刻をログ出力
var afterTime = Utilities.formatDate(new Date(), "Asia/Tokyo", "HH:mm:ss.SSS");
Logger.log("■ 再開後の時刻 : " + afterTime);

Logger.log("=== 待機実験完了! ===");
}

エディタ上部の 「保存(フロッピーアイコン)」 を押し、関数が testSleepBasic になっていることを確認して 「実行」 ボタンをクリックしてみましょう!

画面下部の「実行ログ」を確認してみてください。

情報 === 待機実験スタート ===
情報 ■ 停止前の時刻 : 14:10:00.120
情報 ⏳ 2.5秒間(2500ms)のウェイトに入ります...
情報 ■ 再開後の時刻 : 14:10:02.625
情報 === 待機実験完了! ===

停止前の「00.120秒」から、再開後の「02.625秒」まで、約2.5秒(2500ミリ秒)のタイムラグがきっちりと発生しているのが確認できますね!

このように、Utilities.sleep() が呼ばれた瞬間、GASのエンジンはその行で時計の針が進むのを静かに待ち、指定時間が経過した瞬間に何事もなかったかのように次の行を実行してくれます。

5. STEP3:【本格実践】ループ処理の中にウェイトを組み込んで連続API通信を安全化しよう!

基本が確認できたところで、いよいよ本題の実務コードへと進みましょう!

スプレッドシートの「通知対象リスト」から未送信の案件を1行ずつループ処理で読み込み、第96回で学んだSlackのWebhook宛てに順次POST送信(または外部APIを呼び出し)しながら、1回の送信ごとに Utilities.sleep(1200)(1.2秒)のウェイトを挟む プロ仕様の連続実行スクリプトを作成します。

(※SlackのWebhook URLをお持ちでない場合でも、動作検証できるようにダミー通信モードの解説も添えています!)

/**
* 札幌オフィス備品発注:ウェイト制御付き連続Slack通知スクリプト
*/
function sendBatchNotificationsWithSleep() {
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheetByName("通知対象リスト");
var lastRow = sheet.getLastRow();

if (lastRow < 2) {
Logger.log("処理対象のデータが存在しません。");
return;
}

// 第93回のおさらい:金庫からSlackのWebhook URLを取得
var webhookUrl = PropertiesService.getScriptProperties().getProperty("SLACK_WEBHOOK_URL");

// A2:E最終行までのデータを一括取得(第13回 Range.getValues)
var values = sheet.getRange(2, 1, lastRow - 1, 5).getValues();

Logger.log("=== 連続通信処理を開始します(対象: " + values.length + " 件) ===");

var sentCount = 0;

for (var i = 0; i < values.length; i++) {
var orderId = values[i][0]; // A列: 発注ID
var itemName = values[i][1]; // B列: 品名
var company = values[i][2]; // C列: 発注先
var quantity = values[i][3]; // D列: 数量
var status = values[i][4]; // E列: ステータス

// 「未送信」の行だけを対象にする
if (status === "未送信") {
var rowNum = i + 2; // スプレッドシートの実際の行番号

// 送信するメッセージの組み立て
var messageText = "📦 【札幌オフィス備品発注】\n" +
"・発注ID: " + orderId + "\n" +
"・品名: " + itemName + " (" + quantity + ")\n" +
"・発注先: " + company;

// ① 外部通信の実行(第96回の復習!)
var success = sendToSlack(webhookUrl, messageText);

if (success) {
// スプレッドシートのステータスを「送信済」に更新(第6回 setValue)
sheet.getRange(rowNum, 5).setValue("送信済");
sentCount++;
Logger.log("✅ [" + (i + 1) + "/" + values.length + "] " + orderId + " の送信完了");
} else {
Logger.log("⚠️ [" + (i + 1) + "/" + values.length + "] " + orderId + " の送信に失敗しました");
}

// -------------------------------------------------------------
// ② 【最重要!】相手のサーバーを守る「1.2秒(1200ms)」のウェイト制御
// ※最後の1件の後は待つ必要がないため、(i < values.length - 1) で判定
// -------------------------------------------------------------
if (i < values.length - 1) {
Logger.log("⏳ レートリミット回避のため 1.2秒 待機中...");
Utilities.sleep(1200);
}
}
}

Logger.log("=== 全件の処理が正常終了しました!(送信件数: " + sentCount + " 件) ===");
}

/**
* 補助関数:SlackへPOST送信する(第96回参照)
*/
function sendToSlack(webhookUrl, text) {
// Webhook URLが未設定の場合はシミュレーション(テスト実行用)
if (!webhookUrl) {
Logger.log("(※Webhook URLが未設定のため、通信成功をシミュレートしました)");
return true;
}

var payload = { "text": text };
var options = {
"method": "post",
"contentType": "application/json",
"payload": JSON.stringify(payload),
"muteHttpExceptions": true
};

try {
var response = UrlFetchApp.fetch(webhookUrl, options);
return (response.getResponseCode() === 200);
} catch (e) {
Logger.log("通信例外エラー: " + e.message);
return false;
}
}

ここがプロの設計!3つのポイントを解説

上記のコードには、現場で障害を起こさないための細やかな工夫が詰まっています。

  1. あえて1000msではなく「1200ms」にする: 「Slackは1秒に1回までだから、ちょうど1000ミリ秒待てばいいや」と思いがちですが、ネットワークの通信速度やサーバー側の時計にはコンマ数秒のブレがあります。ギリギリの1000msを攻めると、わずかなタイミングのズレで429エラーを踏むリスクがあります。実務では 1200ms や 1500ms のように、安全マージン(余裕)を20〜50%上乗せして設定するのがプロの知恵です。
  2. 最後の1件は待たない(if (i < values.length - 1)): ループの最後のデータが送信し終わった後は、もう次の通信がないので待つ必要がありませんよね。無駄な待ち時間を削るためのスマートな判定を入れています。
  3. 送信成功した行だけステータスを更新する: 通信が成功したのを確認してから sheet.getRange(...).setValue("送信済") を実行しています。万が一途中でエラーが起きても、次回実行したときは「未送信」の行から安全に再開できます。

実行してみると、Slackチャンネルに約1.2秒おきに「ポン……ポン……ポン……」と心地よいリズムでメッセージが連続投稿されていくはずです。サーバーに全く負荷をかけず、エラーも一切出ない極めて安定した自動化が実現できました!

6. 実務で差がつく!「ウェイト制御&リトライ処理」のプロ技3選

基本のウェイト制御ができるようになったら、さらにワンランク上の「企業レベルで通用する堅牢なシステム設計」を3つ伝授します!

プロ技①:世界標準アルゴリズム「指数バックオフ(Exponential Backoff)」

通信相手のサーバーが一時的に混雑していて429エラーや503エラーが返ってきたとき、すぐに諦めて処理を諦めてしまうのは勿体ないですよね。かといって、1秒後にすぐ同じ通信を再送したら、相手のサーバーはさらにパニックになります。

そこでGoogleやAmazon(AWS)が公式に推奨しているのが、「指数バックオフ」というリトライ(再試行)手法です!

失敗するたびに、「1秒 ➔ 2秒 ➔ 4秒 ➔ 8秒 ➔ 16秒……」と待機時間を倍々に増やしながら再試行します。

/**
* 指数バックオフを取り入れた最強のAPIリクエスト関数
*/
function fetchWithExponentialBackoff(url, options, maxRetries) {
var retries = maxRetries || 3; // 最大3回までリトライ
var waitTime = 1000; // 初期待機時間:1秒(1000ms)

for (var i = 0; i <= retries; i++) {
try {
var response = UrlFetchApp.fetch(url, options);
var code = response.getResponseCode();

// 200番台なら大成功!
if (code >= 200 && code < 300) {
return response;
}

// 429(レートリミット)または 503(サーバー過負荷)の場合はリトライ対象
if (code === 429 || code === 503) {
Logger.log("⚠️ サーバー混雑(HTTP " + code + ")。" + (waitTime / 1000) + "秒 待機して再試行します...");
} else {
// それ以外のエラー(404 Not Foundなど)は待っても無駄なので即終了
throw new Error("HTTPエラー: " + code);
}

} catch (e) {
if (i === retries) throw e; // 上限回数に達したらエラーを投げる
Logger.log("通信エラー検知: " + e.message);
}

// 【指数待機】1秒 ➔ 2秒 ➔ 4秒 と倍々に増やして眠る
Utilities.sleep(waitTime);
waitTime = waitTime * 2;
}

throw new Error("最大リトライ回数を超過しました。");
}

相手のサーバーの回復を優しく待ちながら自動でリカバリーしてくれるため、夜間バッチ処理の信頼性が劇的に跳ね上がります!

プロ技②:ランダムな揺らぎ「ジッター(Jitter)」を足して同時衝突を防ぐ

複数のGASスクリプトや別々のトリガーが同じ時間に動いている場合、みんながピッタリ1000ms刻みで通信すると、偶然同じ瞬間にアクセスが重なって衝突(スパイク)することがあります。

これを防ぐため、待機時間に わずかなランダムの数値(ジッター) を混ぜるのがプロの常套手段です。

// 1000ms 〜 1500ms の間でランダムなウェイトを生成する
var randomJitter = Math.floor(Math.random() * 500); // 0〜499の乱数
var sleepTime = 1000 + randomJitter; // 1000〜1499ms

Utilities.sleep(sleepTime);

たった1行乱数を足すだけで、機械的な規則性が崩れ、相手のセキュリティフィルターにスパム判定されるリスクをほぼゼロにできます。

プロ技③:GASの「6分間の壁(実行時間上限)」とのトレードオフ計算

ウェイト制御を使う上で、絶対に頭に入れておかなければならないのが 「GASの1回の最大実行時間は6分間(360秒)」 という制限です。

  • 1回の通信につき 1.5秒 待機する場合:
  • 100件処理すると ➔ 待機時間だけで 150秒(2分30秒) 消費
  • 200件処理すると ➔ 待機時間だけで 300秒(5分00秒) 消費!

つまり、1件ごとに丁寧に待機を入れると、1回のプログラム実行で処理できる件数は 最大でも150〜200件程度が限界 になります。

もし500件や1000件のデータを処理したい場合は、一度に全件やろうとせず、第23回で学んだ「トリガー(定期実行)」を使って「1回につき50件ずつ処理して、続きは10分後のトリガーにバトンタッチする」という分割バッチ設計を組みましょう!

7. 初心者が100%つまずく!Utilities.sleep() の5大トラップと完全対処法

一見シンプルに見える Utilities.sleep() ですが、初心者が必ずと言っていいほどハマってしまう落とし穴をまとめました。エラーが出たり意図通りに動かないときは、ここをチェックしてください!

トラップ1:引数を「秒」だと勘違いして一瞬で終わる

本記事の最初でもお伝えしましたが、事故率No.1のミスです!

// ✕ 3秒待たせたいのに「3ミリ秒」しか止まらない!
Utilities.sleep(3);

// ◯ 3秒待たせたいなら「3000ミリ秒」を指定する!
Utilities.sleep(3000);

「sleepを書いたのに全然待ってくれない!」というときは、桁数が3つ足りていないことを疑いましょう。

トラップ2:Webアプリの画面側(HTML)を止めようとして動かない

第81回〜第90回でWebアプリ開発を学んだ人がやりがちなミスです。

index.html の <script> タグ(ブラウザ側で動くJavaScript)の中で Utilities.sleep(1000); と書いても、「Utilities is not defined」というエラーで動きません。Utilities はGoogleのクラウドサーバー(コード.gs)の中だけで動く専用ツールです。

ブラウザ側で画面の表示を一定時間待たせたい場合は、通常のJavaScript標準機能である setTimeout() を使ってくださいね。

トラップ3:sleep中にスプレッドシートの画面がリアルタイム更新されると勘違いする

sheet.getRange("A1").setValue("処理中...");
Utilities.sleep(5000); // 5秒待つ
sheet.getRange("A1").setValue("完了!");

「A1セルに『処理中…』と表示させてから5秒待って、そのあと『完了!』に変わるアニメーションを作りたい!」と思って上記のようなコードを書いても、スプレッドシートの画面には「処理中…」が一瞬たりとも表示されません。

GASはパフォーマンス向上のため、セルの書き換えをメモリに溜め込み、プログラムがすべて完了した瞬間にまとめて画面へ反映する仕様になっているからです。途中の画面変化をユーザーに見せたい場合は、第88回で学んだWebアプリのUI(withSuccessHandler)を活用しましょう。

トラップ4:短すぎるウェイト(50msなど)でレートリミットを突破できない

「待機時間はできるだけ短いほうがいいから、Utilities.sleep(50)(0.05秒)にしておこう!」と設定する人がいますが、これではウェイトの意味がほぼありません。相手のサーバーから見れば、0.05秒間隔のアクセスは人間業ではなく依然として「猛烈な機械的連打」と判定されます。外部APIの連続通信では、最低でも 1000ms(1秒) 以上の休息を確保しましょう。

トラップ5:無駄に長すぎるsleepで6分の実行時間上限に激突する

安全を重視しすぎて、1件ごとに Utilities.sleep(10000)(10秒)のような過剰な待機時間を設定してしまうと、たった36件のデータを処理しただけで制限時間の6分(360秒)を使い切ってしまい、スクリプトがタイムアウトで強制停止します。「1〜2秒程度」の適切な待機時間を設定するように心がけましょう。

8. 今回のまとめ&次回予告

今回は、外部APIやSlackへの連続通信時にエラーを防ぐための必須テクニック Utilities.sleep() によるウェイト制御 について徹底解説しました!

  1. Utilities.sleep(ミリ秒) で、指定した時間だけプログラムを安全に一時停止できる!
  2. 引数の単位は「ミリ秒」なので、1秒待つなら 1000 を指定する!
  3. APIをループで連打すると「429 Too Many Requests」でブロックされるため、1〜1.5秒程度のウェイトを入れるのが世界共通のマナー!
  4. 指数バックオフ(1秒 ➔ 2秒 ➔ 4秒……)を実装すれば、一時的なサーバー混雑時も自動でリカバリーできる!
  5. 待機時間の積み重ねによる「GASの6分間の実行時間上限」を意識して、処理件数を調整する!

「プログラムは速ければ速いほど正義」と思われがちですが、外部のシステムと対話するときは、相手のペースに合わせて「あえて待つ」という気配りができるかどうかが、プロのエンジニアとしての腕の見せ所です。今回のウェイト制御を味方につけて、どんなに大量のデータでも絶対に途中で落ちないタフな自動化システムを構築していきましょう!

さて、外部連携を極めたところで、連載ロードマップもいよいよ残すところあと3回!

次回は、システムの「表示速度」を極限まで引き上げる最強のチューニング技術に挑みます!

次回(第98回)のテーマは、
「CacheService.getScriptCache() × 『月次売上データ』を一時キャッシュしてダッシュボードの表示速度を爆速化」 です!

Webアプリのダッシュボードを開くたびにスプレッドシート全体を読み込みに行くと、画面が出るまでに数秒〜十数秒も待たされてイライラしてしまいますよね。一度取得したデータをGoogleの高速メモリに「一時保存(キャッシュ)」しておくことで、2回目以降のアクセスを一瞬(0.1秒)で終わらせる爆速化テクニックをお届けします。最終回に向けてさらに加速していきますので、ぜひ次回も楽しみにしていてくださいね!