【ITニュース解説】Your API wrote the row. Why did onEdit not run?

Googleスプレッドシートは、単なる表計算ツールとしてだけでなく、スクリプトを使って機能を拡張したり、外部のシステムと連携したりできる強力なプラットフォームだ。特に便利なのが、特定の出来事（イベント）をきっかけに自動でプログラムを実行する「トリガー」機能である。例えば、セルが編集されたときに自動で処理を行うonEditトリガーや、フォームが送信されたときに動くonFormSubmitトリガーなどがその代表だ。しかし、このトリガー機能には、システム開発者が知っておくべき重要な挙動がある。

それは、スプレッドシートにデータが書き込まれる際、それがユーザーの手入力によるものなのか、それともプログラム（APIやApps Script）によるものなのかによって、トリガーの発動条件が異なるという点だ。具体的には、ユーザーがスプレッドシートのセルを直接編集した場合にはonEditのようなトリガーが発動する。しかし、Google Sheets APIを介して外部システムからデータを書き込んだり、Apps Script内のプログラムがセルに値を設定したりしても、これらのトリガーは原則として発動しない。これはバグではなく、Googleが意図的に設計した仕様である。

この仕様が設けられている主な理由は、セキュリティの確保とシステム制御の明確化にあると考えられる。ユーザーがスプレッドシートを直接操作する状況と、プログラムが自動的に操作する状況では、その性質が大きく異なる。プログラムによる操作の場合にまで自動でトリガーが発動してしまうと、予期せぬスクリプトの連鎖が起きたり、処理が無限ループに陥ったりするリスクがある。また、外部システムからの大量のデータ書き込みに対して、不必要に何度もスクリプトが実行されることで、システムのパフォーマンスが低下したり、Apps Scriptの実行制限に抵触したりする可能性も出てくる。開発者がプログラムによる操作の際に、明示的に次の処理ステップを制御できるようになっていることで、より安定したシステムを構築できるというわけだ。

では、APIやスクリプトを使ってスプレッドシートにデータを書き込んだ後に、onEditトリガーが通常行うような後続の処理を実行したい場合はどうすれば良いのだろうか。これには主に二つの解決策がある。一つは、もし自分でデータ書き込みを行うスクリプトを開発している場合だ。この場合は、データをスプレッドシートに書き込んだ直後に、トリガーが本来実行するはずだった処理を行う関数をプログラム内で明示的に呼び出す。これにより、データ書き込みと後続処理を一連のプログラムとして実行できる。もう一つは、外部のシステムがスプレッドシートにデータを書き込む場合で、その外部システムを自分で制御できない場合だ。この状況では、スプレッドシートを定期的に監視（スキャン）する別の仕組みを用意する必要がある。この監視プログラムが、新しく書き込まれたデータや変更されたデータを検出し、必要な処理を実行する。この際、どのデータまで処理済みかを記録する「進捗管理」の仕組みや、同じデータを複数回処理しないための「重複防止」の仕組みを実装することが非常に重要になる。

このトリガーの挙動の違いを具体的に理解するための簡単な検証方法が提供されている。まず、使い捨ての新しいGoogleスプレッドシートを作成し、その中に「TriggerProbe」という名前のシートを用意する。次に、イベントの発生を詳細に記録するためのApps Scriptコードをスプレッドシートに組み込み、保存する。このスクリプトは、どのようなイベントがいつ、どのような情報（イベントオブジェクトの形）で発生したかをログに残してくれる。

検証の最初のステップとして、TriggerProbeシートのA1セルに「ui-probe」と手入力してみよう。この操作はユーザーによる直接編集なので、スクリプトに設定されたonEditトリガーが正常に発動し、記録ログにその実行が残るはずだ。これは、トリガーが期待通りに動作することを確認する「陽性対照」となる。

次に、このスプレッドシートに対して、Apps Scriptのプロジェクトトリガーパネルから、インストール可能なトリガーを三つ追加で設定する。具体的には、スプレッドシートの編集に対応するprobeInstalledEdit、変更全般に対応するprobeChange、そしてフォーム送信に対応するprobeSheetSubmitという関数を、それぞれ適切なトリガータイプに紐付ける。このとき、既存のonEdit関数に手動でトリガーを追加しないことや、トリガーを設定するアカウントは一つに絞ることが重要だ。これらのトリガーを設定した後、再度セルを手動で編集したり、スプレッドシートにリンクされた仮のGoogleフォームからデータを送信したりして、各トリガーが適切に発動することを確認する。

いよいよ本題の検証だ。Apps Scriptを使ってスプレッドシートに値を書き込むテストを行う。用意されたスクリプト内のwriteTriggerProbeという関数を一度実行してみよう。この関数は、プログラム的にA1セルに特定の値を書き込むものだ。実行が完了したというメッセージが表示されれば、スクリプトによる書き込みは成功している。しかし、このとき記録ログを確認しても、onEditやonChangeのようなトリガーは発動していないはずだ。セルは確かに変更されたのに、トリガーは動かない。これが、APIやスクリプトによる書き込みと、ユーザーによる手入力との決定的な違いを示す重要な証拠となる。

さらに、Sheets APIクライアントが利用できる環境であれば、Google Sheets APIのvalues.updateメソッドを使って、A1セルに「api-probe」という値を書き込んでみよう。これもプログラム的な書き込みである。この操作後も、トリガーログには何も記録されないことを確認できるだろう。もしAPIの認証設定ができていない場合は、このステップはスキップし、別のスクリプトからの書き込みでこのケースを代用することはできない。あくまでSheets APIを経由した書き込みで検証することが重要だ。

この検証を行う上でいくつか注意すべき点がある。まず、Apps ScriptのエディタからonEditなどのイベントハンドラ関数を直接「実行」ボタンでテストしてはいけない。エディタからの実行では、本来トリガーがイベント発生時に提供するはずの「イベントオブジェクト」（どのセルが編集されたか、どのような値が入力されたかなどの情報を含むオブジェクト）が提供されないため、実際のトリガーの挙動を正しく検証できないからだ。また、Google Sheetsのフォーム送信イベントと、Google Formsのフォーム送信イベントでは、それぞれで得られるイベントオブジェクトの構造が異なる点にも注意が必要である。これらを混同すると、スクリプトがエラーで終了する可能性がある。

検証が終わったら、設定したインストール可能なトリガーをすべて削除し、さらに、スプレッドシートに組み込んだイベントレコーダーのスクリプトコードも忘れずに削除することが大切だ。なぜなら、onEditのようなシンプルなトリガー関数は、プロジェクトからトリガー設定を削除しても、スクリプトコード自体が残っている限り、特定の条件で再び発動する可能性があるためである。最後に、検証のために作成した一時的なスプレッドシートや関連するGoogleフォームなどもすべてゴミ箱に入れ、クリーンアップを徹底しよう。

今回の検証で得られるのは、あくまでローカル環境での挙動の確認であり、Googleのイベント配信システム全体のパフォーマンスや信頼性を測定するものではない点も理解しておく必要がある。Googleの公式ドキュメントに記載されているトリガーの制限、イベントオブジェクトの構造、そしてSheets APIの利用方法などを参照しながら、実際のシステム開発に活かしていくことが重要だ。システムエンジニアを目指す上で、このような細かな仕様の違いを理解し、適切に対応できる知識は、安定したシステムを構築するために不可欠である。