公式ドキュメント - append

書き込みを行うメソッドにappendとupdateがあって、appendでもOVERRIDEが使えるので、どっちでも更新できそうな感じだったので、使い分けを調べていたらapeendの仕様にハマったので整理した。
具体的には、appendに渡すrangeと書き込まれる位置の仕様について整理した。

やること

書き込みたいシートの初期状態は以下の通り。

公式ドキュメント上のテストを利用してappendを実行します。(spreadsheetIdの記載は省略)

range: 対象範囲の取得（rangeに指定した範囲 ≠ 対象範囲(※)。後述します。）
InsertDataOption: 上書き or 挿入
valueInputOption: そのまま値を入れる or 普通にスプレッドシートに手で入力した時のように日付などをフォーマットするか

今回は1マスにfugaを書き込みます。

結果

仕様はこんな感じになっている。

range(D27:D28)の範囲から表を抽出(D27) → 検査元（と名付けます。）
検査元から上方向に伸ばして値が途切れるところまで検査を行う → 第１検査範囲
第１検査範囲から左右方向に伸ばして値が途切れるところまで検査を行う → 第２検査範囲
第２検査範囲から下方向に伸ばして値が途切れるところまで検査を行う → 第３検査範囲
検査元〜第３検査範囲 → ※対象範囲
対象範囲の下行の左端 → appendの起点

上記やることを実施した結果は以下の通り。（図１）

図１からC28のhogeを消した状態でappendした場合（図２）

図2からD25のhogeを消した状態でappendした場合（図3）

まとめ

総括してappendは表の下に挿入するためのメソッドということ。rangeで指定した範囲から表全体を把握して、その表の下に挿入しようとしている。表全体を把握する仕様が上記のようになっているという解釈。

upadteとの使い分けとしては、
シートの一番下の行に挿入する時はappend
途中のセルを更新したり、空白に挿入する時はupdateを使う。

途中の空白のセルにもupdate使った方が良さそう。
あと、今回は値がバラバラに入力された状態でテストしていて、それがハマりのポイントになっているので、シートに表を書く時はA1から埋めて、シンプルな構成にしておくのがよい。
メモ等を書く場合は表から離して書く。