スプレッドシートの自動化を進めていると、「たくさんのデータを一気にシートへ流し込みたい!」「集計した結果を表としてサッと書き出したい!」という場面が必ず出てきます。
第6回で学んだ Range.setValue() を覚えているでしょうか? setValue() は1つのセルに値を書き込む大変便利な命令ですが、もし100行や1000行あるデータを1セルずつ setValue() で書き込もうとすると、処理に何十秒もかかったり、最悪の場合は実行時間制限(6分間の壁)に引っかかってエラーで止まってしまいます。
そこで登場するのが、今回解説する Range.setValues()(最後に s がつく複数形) です!
Range.setValues() を使いこなせると、数百行・数千行もの膨大なデータをたった1回の命令で、一瞬(1秒未満)で書き込むことができるようになります。
今回は、初心者が一番つまずきやすい「2次元配列」の考え方から、実務で誰もが一度は遭遇するエラーの対処法まで、どこよりも詳しく・丁寧にかみ砕いて解説します!
1. なぜ Range.setValues() を使うと爆速になるの?
まずは、単数形の setValue() と複数形の setValues() の違いをしっかり理解しておきましょう。
単数形と複数形の決定的な違い
| 項目 | setValue()(単数形) | setValues()(複数形) |
| 操作対象 | 1つのセル(例:A1セルだけ) | 複数のセル範囲(例:A1:C10の表全体) |
| 渡すデータ | 単一の値("札幌", 500 など) | 2次元配列([[...], [...]]) |
| 通信回数 | セルの数だけ何度も通信する | たった1回の通信で完了する |
| 処理スピード | データの数が多いと激重になる | データが多くても爆速(一瞬) |
「手押し車」と「大型トラック」でイメージしてみよう!
なぜこんなにスピードが変わるのか、身近な例えで考えてみましょう。
倉庫から部屋へ、100個の段ボール箱を運ぶ作業をイメージしてください。
setValue()を繰り替えす場合:1個の箱を「手押し車」に乗せて、倉庫と部屋を 100往復 します。行ったり来たりする時間だけでクタクタになってしまいますよね。setValues()を使う場合:100個の箱を「大型トラック」に全部積み込んで、1回の往復 で一気に運んでしまいます。
GASの世界でも全く同じです。 「プログラム(GAS)」から「スプレッドシート」へアクセスする通信(往復作業)は、非常に時間がかかります。 100回の通信を行う setValue() よりも、1回の通信でまとめてデータを引き渡す setValues() の方が圧倒的に速いのはこのためです。
2. 超重要!setValues() の相棒「2次元配列」を世界一わかりやすく解剖
setValues() を使うときに、初心者が最も高く感じてしまう壁が 「2次元配列(にじげんはいれつ)」 というデータの形式です。 ここさえ乗り越えればGASのレベルが一段階アップしますので、焦らず順番に解剖していきましょう!
そもそも「配列(1次元配列)」ってなに?
プログラミングでいう「配列」とは、データを横一列に並べたコインロッカーのような箱のことです。JavaScriptでは半角のカッコ [ ] を使って表現します。
// これが普通の配列(1次元配列)
var shopList = ["GARAKU", "奥芝商店", "マジックスパイス"];
これは「1行だけのデータ」や「単なるリスト」を表すのに向いています。
「2次元配列」はスプレッドシートの表そのもの!
スプレッドシートの表を思い出してください。表には「行(縦)」と「列(横)」がありますよね。
この「行」と「列」を持った表構造をプログラムで表現したものが2次元配列です。
考え方はとてもシンプルで、「配列の中に、さらに配列を入れた二重構造」 になっています。
視覚的に見てみましょう!
// 2次元配列(3行 × 3列 の表データ)
var curryTable = [
["店名", "エリア", "おすすめ辛さ"], // ← 1行目(0番目の要素)
["GARAKU", "中央区", "3番"], // ← 2行目(1番目の要素)
["奥芝商店", "駅前", "2番"] // ← 3行目(2番目の要素)
];
スプレッドシートの画面と見比べてみてください。
- 一番外側の
[]が 表全体(枠組み) - その中にある小分けの
[]が 1つひとつの「行」 - 行の中にあるカンマ区切りのデータが 1つひとつの「列(セル)」
どうでしょう?「配列の中に各行のデータが入っているだけ」と思うと、少し親しみやすくなりませんか?
setValues() は、この「スプレッドシートの見た目と全く同じ形をした2次元配列」を受け取ることで、一瞬で表を復元してくれる仕組みになっています。
3. STEP1:【実践】札幌スープカレーおすすめリストを一括書き込みしてみよう!
概念が掴めたところで、実際に手を動かして Range.setValues() を動かしてみましょう! 今回は、札幌市内の有名なスープカレー店リストをスプレッドシートへ一気に書き込むプログラムを作成します。
1. スプレッドシートの準備
- Googleドライブから新しいGoogleスプレッドシートを作成します。
- 画面左上のタイトルを「GAS14回_練習」にし、シート名を 「スープカレーリスト」 に変更しておきます。
- シート上は何も入力せず、真っ白な状態で OK です!
2. GASのエディタ画面を開く
上部メニューの 「拡張機能」 > 「Apps Script」 をクリックして、スクリプトエディタを開きます。
3. コードを入力する
最初から書いてある function myFunction() { ... } をすべて消して、以下のコードをそのままコピー&ペーストしてください。
function writeCurryList() {
// ① 今開いているスプレッドシートとシートを取得する
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getActiveSheet();
// ② 書き込みたい表データ(2次元配列:4行 × 3列)を作成する
var curryData = [
["店名", "エリア", "名物メニュー"],
["GARAKU", "中央区", "やわらかチキンと大地の恵み"],
["奥芝商店", "駅前エリア", "海老だしスープカレー"],
["マジックスパイス", "白石区", "チキン(涅槃)"]
];
// ③ 書き込み先となるセル範囲を指定する
// (開始行: 1, 開始列: 1, 行数: 4, 列数: 3) ➡ つまり「A1:C4」の範囲を指定!
var targetRange = sheet.getRange(1, 1, 4, 3);
// ④ setValues() を使って一括書き込みを実行!
targetRange.setValues(curryData);
// ⑤ 完了ログを出力
Logger.log("データの一括書き込みが正常に完了しました!");
}
4. 保存して実行する
- エディタ上部にある 「保存ボタン(フロッピーディスクのアイコン)」 を押します。
- 実行する関数が
writeCurryListになっていることを確認し、「実行」 をクリックします。 - 初回実行時は権限の承認画面が出ることがあるので、画面の指示に従って許可(アクセスを許可)してください。
5. 結果を確認する!
スプレッドシートの画面に戻ってみましょう。
A1からC4までの4行3列の範囲に、一瞬でキレイなスープカレー店一覧表が書き込まれていれば大成功です!
4. ここで差がつく!プロがやる「サイズ不一致エラーを防ぐ動的指定」
先ほどのコードで、ひとつ気になる部分がありませんでしたか?
// (開始行: 1, 開始列: 1, 行数: 4, 列数: 3)
var targetRange = sheet.getRange(1, 1, 4, 3);
この「4 行」や「3 列」という数字を、自分で「1、2、3、4…よし4行だな!」と手で数えてコードに直接書く(ハードコーディングする)のは、実はあまり良い書き方ではありません。
なぜなら、後から配列のデータが10行に増えたとき、コード側の「4」を修正し忘れるとエラーが発生して動かなくなってしまうからです。
配列の要素数から「行数」と「列数」を自動計算させよう!
プロのエンジニアは、配列が持っている .length(要素の数)という性質を使って、以下のように範囲を動的に取得します。
// 配列のサイズをプログラムに自動で数えさせる!
var rows = curryData.length; // 行数(curryDataの中にいくつ行があるか)➡ 4
var cols = curryData[0].length; // 列数(最初の行の中にいくつ要素があるか)➡ 3
// 自動で計算した rows と cols を getRange にセット!
var targetRange = sheet.getRange(1, 1, rows, cols);
targetRange.setValues(curryData);
コードのポイント解説
curryData.length配列全体の中に入っている「行の数」を数えてくれます。データが100行に増えれば、自動的に100になります。curryData[0].length「0番目の行(1行目)」の中に入っている「列の数(要素数)」を数えてくれます。
このテクニックを使えば、データが増減してもコードを書き換える必要が一切なくなるため、非常に安全でスマートなプログラムになりますよ!
5. 初心者が100%つまずく!5大トラップと解決策
Range.setValues() は非常にパワフルな命令ですが、ルールが厳格なためエラーが出やすいポイントでもあります。実務で必ず一度は遭遇する「5大トラップ」と、その解決策をまとめました。
トラップ1:The number of rows in the data does not match... エラー
実行したときに、以下のような赤文字のエラーが出ることがあります。
エラー内容の例:
Exception: The number of rows in the data does not match the number of rows in the range. The data has 4ですが、range has 5です。
【原因】
「書き込み先のセル範囲のサイズ(行数・列数)」 と 「用意した2次元配列のサイズ(行数・列数)」 が1マスでもズレていると、GASは「どこに何を入れればいいの!?」とパニックを起こしてエラーになります。
- ✕ 配列データ:4行 × 3列
- ✕ 指定したRange:5行 × 3列(
sheet.getRange(1, 1, 5, 3))
【解決策】
先ほど紹介した 「.length を使った動的指定」 を使いましょう!
手入力で getRange(1, 1, 4, 3) と書くのをやめ、sheet.getRange(1, 1, curryData.length, curryData[0].length) と書けば、サイズ不一致エラーは100%防ぐことができます。
トラップ2:1次元配列 ["A", "B", "C"] をそのまま渡して撃沈
1行だけのデータ(例:ヘッダー行など)を書き込みたいときに、やりがちなミスです。
// ✕ NGなコード(カッコが1重になっている)
var header = ["店名", "エリア", "価格"];
sheet.getRange(1, 1, 1, 3).setValues(header); // エラー発生!
【原因】
setValues() は絶対に2次元配列しか受け取ってくれません。どれだけデータが1行(または1列)しかなくても、1次元配列を渡すとエラーになります。
【解決策】
カッコを二重 [[ ]] にして、「1行分しかない2次元配列」 に仕立てて渡してあげましょう。
// ◯ OKなコード(二重カッコにして2次元配列にする!)
var header = [
["店名", "エリア", "価格"]
];
sheet.getRange(1, 1, 1, 3).setValues(header); // 大成功!
トラップ3:setValue と setValues(s の有無)のタイポ・誤用
名前が1文字(s があるかどうか)しか違わないため、打ち間違いによる事故が多発します。
- ミス①:複数形の
setValues()に単一の値("GARAKU")を渡してしまう➡Cannot find method setValues(string)...というエラーになります。 - ミス②:単数形の
setValue()に2次元配列(curryData)を渡してしまう➡ エラーにはならず、セルの中に[[GARAKU, ...]]という謎の文字が丸ごと埋め込まれて表示されてしまいます。
【解決策】
- セル1つだけに書く ➡
setValue()(単数) - 複数セル(表全体・配列)に書く ➡
setValues()(複数) と声に出して確認する癖をつけましょう!
トラップ4:行によって列の数がバラバラでエラーになる
2次元配列を作るときに、以下のように行によって要素の数が揃っていないとエラーになります。
// ✕ NG例(2行目だけ列数が足りない)
var badData = [
["店名", "エリア", "価格"],
["GARAKU", "中央区"] // ← 価格のデータ(3列目)が抜けている!
];
【原因】
スプレッドシートの表は必ずきれいな長方形(または正方形)でなければなりません。途中の列が欠けている歪んだ配列は渡せないルールになっています。
【解決策】
データがない空のセルを作りたい場合でも、省略せずに ""(空文字)を入れて、すべての行の列数を揃えてください。
// ◯ OK例(空文字で列数を揃える)
var goodData = [
["店名", "エリア", "価格"],
["GARAKU", "中央区", ""] // 3列目を空文字にして長方形を保つ!
];
トラップ5:書き込み先にすでにあるデータが警告なしで上書きされる
Range.setValue() と同様、setValues() も指定した範囲にすでに文字や数式が入っていても、一切の確認ダイアログを出さずに上書き破壊します。
「大切な既存の計算式や履歴データを、プログラムの誤実行で消してしまった…」という悲劇を防ぐため、以下の対策を行いましょう。
- 書き込み開始位置(
getRangeの行・列)が正しいか事前に確認する - 空いている新規シートで一度テスト実行する
- 必要に応じて第7回で学んだ
Sheet.appendRow()や、最終行を取得するgetLastRow()と組み合わせて末尾に追記する
6. まとめ&次回予告
今回は、複数セルへデータを一括書き込みする超重要メソッド Range.setValues() を詳しく解説しました!
今日の重要ポイント
setValues()は複数のセルにまとめてデータを流し込む爆速命令- 渡すデータは必ず「2次元配列(
[[...], [...]])」の形式にする - 書き込み先の
Rangeのサイズ(行・列)と、配列のサイズをピッタリ合わせる curryData.length(行数)とcurryData[0].length(列数)を使って指定すればサイズ不一致エラーを防げる!
前回学んだ Range.getValues()(一括読み込み)でシートからデータを取り出し、GASのプログラムで加工したあと、今回の Range.setValues()(一括書き込み)でシートへ戻す—— これこそが、実務で大量のデータを処理する際のGAS自動化の基本黄金パターンとなります!
次回(第15回)は、今回扱った配列データの中から、特定の条件に合うデータ(例:「中央区の店舗だけ」「価格が500円以下の商品だけ」など)をスマートに抽出する Array.filter() について解説します! 表の検索・絞り込み処理が劇的に楽になりますので、ぜひ楽しみに待っていてくださいね!
