外部のWeb APIと通信してデータを取得したり、SlackやLINEなどの外部ツールへデータを送信しようとしたとき、画面やログに[object Object]と表示されてしまったり、SyntaxError: Unexpected token in JSON at position 0という真っ赤なエラーに阻まれて頭を抱えたことはありませんか?
前回(第94回)は、UrlFetchApp.fetch()を使って外部APIから札幌のリアルタイムな気象データを取得し、ダッシュボードへ連携させる方法を学びました。その際にもさらっとJSON.parse()が登場しましたが、「実はなんとなく使っていて、裏で何が起きているのかよく分かっていない……」「二重、三重に入り組んだ複雑なデータ構造から、欲しい値をどうやって抜き出せばいいのか迷子になる……」という方も多いはずです。
そこで第95回となる今回は、Web API連携をマスターする上で絶対に避けては通れない最重要ペア、JSON.parse()(ジェイソン・パース)とJSON.stringify()(ジェイソン・ストリングファイ)を徹底解説します!
「そもそもJSONって何?」「なぜ変換が必要なの?」という基本概念から、複雑に入り組んだ多重ネスト構造からのスマートなデータ抽出術、次回(第96回)のSlack自動通知に直結する送信データの組み立て方、そして実務で必ず役立つエラー回避策まで、どこよりも分かりやすく丁寧に解き明かしていきます。データの「相互変換力」を身につけて、APIを自由自在に操るデータマスターを目指しましょう!
1. そもそもJSONとは?なぜ変換(相互解析)が必要なのか
まずは、プログラミングの世界で毎日飛び交っている「JSON」の正体と、なぜわざわざ変換処理を行うのかという根本的な仕組みからスッキリ整理しておきましょう。
JSON(ジェイソン)ってなに?
JSONとは、JavaScript Object Notation(JavaScript オブジェクト記法)の頭文字をとった言葉です。名前に「JavaScript」と付いていますが、現在ではPythonやRuby、PHP、Goなど、世界中のあらゆるプログラミング言語やWebサービス同士がデータを受け渡すための「世界共通のデータ交換テキスト形式」として使われています。
JSONの見た目は、本連載でも何度も登場してきた「JavaScriptのオブジェクト(連想配列)」や「配列」と非常によく似ています。
{
"officeName": "札幌オフィス",
"temperature": 18.5,
"isOpen": true,
"members": ["佐藤", "高橋", "伊藤"]
}
決定的な違い!「プログラム上のデータ」と「通信用の文字列」
初心者が最もつまずきやすいのが、「JavaScriptオブジェクト」と「JSON」の違いです。見た目がそっくりなため同じものだと思われがちですが、コンピューターにとってはまったくの別物です!
| 比較項目 | JavaScriptオブジェクト(配列や連想配列) | JSON(JSON文字列)★通信用 |
|---|---|---|
| 実体 | コンピューターのメモリ上に広がる「プログラムの部品」 | ただの1本の「平文テキスト(文字列)」 |
| 操作 | data.officeNameのように自由に中身を操作できる | 単なる文字の羅列なので、そのままでは値を取り出せない |
| インターネット通信 | 複雑すぎて電波(通信)に乗せてそのまま送れない | 普通の文字(テキスト)なので世界中へ安全に送信できる |
| 型の例 | Object, Array | String(文字列型) |
「冷凍食品と電子レンジ」でイメージしよう!
この2つの関係は、身近な「出来立ての料理」と「冷凍パック食品」に例えると一発で理解できます。
- JavaScriptオブジェクト(出来立てのスープカレー):お皿の上に温かく盛り付けられた料理です。スプーンですぐに具材(データ)を食べられますが、そのまま宅急便で遠くのオフィスへ送ろうとすると、こぼれてぐちゃぐちゃになってしまいます。
JSON.stringify()(急速冷凍してパック詰め):出来立ての料理を、遠くへ運べるようにカチカチにパッキングして「1つの荷物(JSON文字列)」にする作業です。- インターネット通信(宅急便):冷凍パックされた荷物(JSON文字列)なら、全国どこへでも安全に配送できます。
JSON.parse()(電子レンジでチンして解凍):届いた冷凍パックを開けてレンジで温め、再び手元ですぐに食べられる「出来立ての料理(JavaScriptオブジェクト)」に戻す作業です。
つまり、「送るときは冷凍(stringify)し、受け取ったら解凍(parse)する」。このキャッチボールを行うために、2つの命令がペアで用意されているのです!
【手元のGAS(オブジェクト)】 │ ▼ JSON.stringify() ── [ 冷凍・梱包:テキスト化 ] 【通信の電波(JSON文字列)】 │ (インターネット経由で送信 / 受信) ▼ JSON.parse() ────── [ 解凍・復元:オブジェクト化 ] 【相手のサーバー / 手元のGAS(オブジェクト)】
2. 本日マスターする2大メソッドの構文と基本動作
まずは、今回主役となる2つの命令の文法と書き方をしっかり確認しておきましょう。
① JSON.parse():文字列をオブジェクトへ変換(解凍・受信)
外部APIから取得したレスポンス文字列や、外部から届いたPOSTデータ(第89回参照)を、プログラムで自由に扱えるオブジェクトや配列に変換します。
// 基本構文
var オブジェクト = JSON.parse(JSON文字列);
// 具体例
var jsonString = '{"store":"セコマ札幌駅前店","item":"フライドチキン","price":313}';
var data = JSON.parse(jsonString);
Logger.log(data.item); // 実行結果:フライドチキン
Logger.log(data.price + "円"); // 実行結果:313円
たった1行JSON.parse()を通すだけで、文字列の中からdata.itemのようにドット記法で好きな項目をピンポイントで取り出せるようになります。
② JSON.stringify():オブジェクトを文字列へ変換(梱包・送信)
手元のスプレッドシートから集計したデータや作成したメッセージオブジェクトを、外部APIやSlackへ送信できる1本の「JSON文字列」に変換します。
// 基本構文
var json文字列 = JSON.stringify(オブジェクトや配列);
// 具体例
var myOrder = {
office: "札幌オフィス",
lunch: "スープカレー",
spiceLevel: 3
};
var payloadText = JSON.stringify(myOrder);
Logger.log(payloadText);
// 実行結果:'{"office":"札幌オフィス","lunch":"スープカレー","spiceLevel":3}'(文字列型になる)
3. STEP1:準備!「札幌オフィスの冬期出張手配リスト」を用意しよう
理論が整理できたところで、実際に手元で動かすハンズオン環境を用意しましょう!
今回は、冬の札幌オフィスで頻繁に発生する「東京・各都市への技術カンファレンス出張や遠征手配」を想定した、少し複雑なデータ連携をシミュレーションします。新千歳空港発のフライト便、宿泊ホテル、出張メンバー、旅費精算データなどが入り組んだ実践的なJSONを扱っていきます。
スプレッドシートとGASエディタの準備手順
- ブラウザでGoogleドライブを開き、新しいGoogleスプレッドシートを作成します。
- ファイル名を「札幌オフィス出張・業務管理簿」に変更します。
- 画面下のシートタブ名を「出張データ連携」に変更しておきます。
- 上部メニューバーの「拡張機能」>「Apps Script」をクリックしてエディタを開きます。
- プロジェクト名を「出張データJSON解析ツール」に変更し、エディタ内のコードを全消去して真っ白にしておきましょう。
4. STEP2:【実践1】JSON.parse() で多重ネスト構造から欲しいデータを抜き出そう!
実際の外部Web API(ホテル予約APIやフライト情報API、各種SaaS)からデータを受け取ると、データが二重、三重に階層化(ネスト)されていることが日常茶飯事です。初心者の方が「欲しい値がどこにあるか分からない!」と最も挫折しやすいポイントを、実際に手を動かして攻略していきましょう!
1. 複雑なネストJSONを解析するコードを入力する
以下のスクリプトをGASエディタに貼り付けてみましょう。外部APIから届いたと想定される、階層の深いJSON文字列を解析するコードです。
/**
* 第95回 STEP2:JSON.parse() による多重ネストデータの解析
* 外部出張管理APIから届いた複雑なJSONを解凍し、必要な情報を取り出します。
*/
function parseBusinessTripJson() {
// ① 外部APIから受信したと想定される生のJSON文字列
// (オブジェクトの中に配列、その中にさらにオブジェクトが入った実践的な構造)
var mockApiResponse = '{\n' +
' "status": "success",\n' +
' "targetCity": "札幌",\n' +
' "tripPlan": {\n' +
' "planId": "STP-202611-08",\n' +
' "title": "東京DXカンファレンス登壇&拠点視察",\n' +
' "budget": 120000,\n' +
' "flight": {\n' +
' "airline": "JAL",\n' +
' "departure": "新千歳空港 (CTS)",\n' +
' "arrival": "羽田空港 (HND)",\n' +
' "seatClass": "普通席(Uシート連絡)"\n' +
' },\n' +
' "members": [\n' +
' {"name": "道産子 太郎", "role": "登壇エンジニア", "hotel": "新宿ワシントンホテル"},\n' +
' {"name": "大通 花子", "role": "PM・ディレクター", "hotel": "JR東日本ホテルメッツ"}\n' +
' ]\n' +
' }\n' +
'}';
Logger.log("=== 1. パース処理(解凍)を開始します ===");
// ② 【本日の主役!】JSON.parse() で文字列からJavaScriptオブジェクトへ変換
var tripData = JSON.parse(mockApiResponse);
// ③ 階層を1段ずつ辿ってデータを取り出してみる!
var planTitle = tripData.tripPlan.title;
var departure = tripData.tripPlan.flight.departure;
var destination = tripData.tripPlan.flight.arrival;
var budget = tripData.tripPlan.budget;
Logger.log("■ 出張計画名 : " + planTitle);
Logger.log("■ 移動ルート : " + departure + " ➔ " + destination);
Logger.log("■ 予算総額 : " + budget.toLocaleString() + " 円");
// ④ ネストされた配列(members)の中身を取り出す
var memberList = tripData.tripPlan.members;
Logger.log("■ 参加メンバー一覧(合計 " + memberList.length + " 名):");
for (var i = 0; i < memberList.length; i++) {
var person = memberList[i];
Logger.log(" ・" + person.name + "(" + person.role + ")宿泊先: " + person.hotel);
}
Logger.log("=== 全データの抽出が正常に完了しました! ===");
}
2. コードの読み解き方を徹底解説!
初心者の方が迷子にならないための「多重階層の辿り方(ナビゲーション)」のコツを分解します。
tripData.tripPlan.flight.departureの読み方:
ドット(.)は「〜の中の」という意味です。一番外側のtripDataの中にある ➔tripPlanの中にある ➔flightの中にある ➔departure(出発地)というように、住所を都道府県・市・区と絞り込む感覚で奥へ進んでいきます。- 配列の混ざった階層の辿り方:
tripData.tripPlan.membersは角カッコ[ ]で囲まれた「配列(リスト)」です。そのため、いきなりtripData.tripPlan.members.nameと書いても取れません(第13回・第72回の復習ですね!)。必ずmembers[0].nameのようにインデックス番号[0]を指定して、「1人目の人の名前」と指定する必要があります。
3. 保存して実行・ログの確認
エディタ上部の「保存」を押し、関数がparseBusinessTripJsonになっていることを確認して「実行」をクリックしてください。
情報 === 1. パース処理(解凍)を開始します ===
情報 ■ 出張計画名 : 東京DXカンファレンス登壇&拠点視察
情報 ■ 移動ルート : 新千歳空港 (CTS) ➔ 羽田空港 (HND)
情報 ■ 予算総額 : 120,000 円
情報 ■ 参加メンバー一覧(合計 2 名):
情報 ・道産子 太郎(登壇エンジニア)宿泊先: 新宿ワシントンホテル
情報 ・大通 花子(PM・ディレクター)宿泊先: JR東日本ホテルメッツ
情報 === 全データの抽出が正常に完了しました! ===
複雑な文字列から、目的のデータだけが正確に取り出せましたね! これさえできれば、どんな外部APIから大量のデータが送られてきても、もう怖くありません。
5. STEP3:【実践2】JSON.stringify() でスプレッドシートのデータを送信形式に変換しよう!
今度は逆の方向です! スプレッドシートに入力された日々の業務データや出張記録を、次回(第96回)のSlack自動通知や外部システムへ送信できるように、綺麗なJSON文字列へと「梱包(シリアライズ)」する実践を行います。
1. スプレッドシートにサンプルデータを入力する
スプレッドシート「札幌オフィス出張・業務管理簿」の「出張データ連携」シートに、以下の通りテスト用データを入力してください。
| A列(出張ID) | B列(出張者) | C列(目的地) | D列(経費概算) | E列(ステータス) |
|---|---|---|---|---|
| TRIP-101 | 道産子 太郎 | 東京・品川オフィス | 45,000 | 承認済 |
| TRIP-102 | 大通 花子 | 大阪・梅田サテライト | 58,000 | 申請中 |
| TRIP-103 | すすきの 次郎 | 函館出張所(特急北斗) | 22,000 | 承認済 |
2. シートのデータをJSON文字列に変換するコードを入力する
GASエディタに以下のコードを追加して実行してみましょう。
/**
* 第95回 STEP3:JSON.stringify() によるシートデータのJSON変換
* スプレッドシートの表を読み込み、外部API送信用のJSON文字列を生成します。
*/
function createPayloadFromSheet() {
var ss = SpreadsheetApp.getActiveSpreadsheet();
var sheet = ss.getSheetByName("出張データ連携");
// データ範囲(2行目〜4行目、A列〜E列)を一括取得(第13回 Range.getValues)
var values = sheet.getRange(2, 1, 3, 5).getValues();
var exportList = [];
// ループ処理で1行ずつオブジェクトに変換して配列に追加(第16回 map 的アプローチ)
for (var i = 0; i < values.length; i++) {
var row = values[i];
exportList.push({
tripId: row[0],
staffName: row[1],
destination: row[2],
cost: Number(row[3]),
status: row[4]
});
}
// 送信用に全体をまとめるメタデータ付きオブジェクトを作成
var payloadObject = {
office: "札幌オフィス",
exportedAt: Utilities.formatDate(new Date(), "Asia/Tokyo", "yyyy/MM/dd HH:mm:ss"),
totalCount: exportList.length,
records: exportList
};
Logger.log("=== 2. JSON.stringify() によるテキスト化 ===");
// ① 通常の stringify(1行のコンパクトな文字列)➔ 通信送信時に使用
var compactJson = JSON.stringify(payloadObject);
Logger.log("■ 通信用コンパクトJSON:");
Logger.log(compactJson);
// ② 【プロ技!】第3引数に「インデント幅(2)」を渡して整形 ➔ ログ確認に最適!
var prettyJson = JSON.stringify(payloadObject, null, 2);
Logger.log("■ 人間が見やすい整形済みJSON(Pretty Print):");
Logger.log(prettyJson);
}
3. ここがスゴい!JSON.stringify(obj, null, 2) の「整形出力」
実行ログを確認してみてください。通常のJSON.stringify()を実行すると、改行や空白が一切ない1本の長い文字列が出力されます。コンピューター同士が通信する際はデータサイズが軽くなるためこれで完璧ですが、開発中に中身をチェックしたいときは目がチカチカして読みづらいですよね。
そこで大活躍するのが、第2引数にnull、第3引数にスペースの数2を渡す「Pretty Print(整形出力)」テクニックです!
情報 ■ 人間が見やすい整形済みJSON(Pretty Print):
情報 {
"office": "札幌オフィス",
"exportedAt": "2026/11/03 15:45:10",
"totalCount": 3,
"records": [
{
"tripId": "TRIP-101",
"staffName": "道産子 太郎",
"destination": "東京・品川オフィス",
"cost": 45000,
"status": "承認済"
},
...
]
}
インデントと改行が自動で整然と挿入され、人間が一目でデータ構造を確認できるようになります。デバッグやログ出力の際には必ず重宝するプロの小技ですので、ぜひ覚えておきましょう!
6. 実務で差がつく!JSON相互変換のプロ技3選
基本操作ができるようになったら、実務の企業システムや本番環境で必須となる「堅牢なプロの設計テクニック」を3つ伝授します!
プロ技①:try...catch で「JSONパースエラーによるシステム強制終了」を防ぐ
外部APIと通信していると、相手側のサーバーがメンテナンスに入っていたりエラーを起こしている場合、JSONではなく<html><body>502 Bad Gateway</body></html>のような「HTMLのエラー画面」が返ってくることがあります。
このHTML文字列に対して無警戒にJSON.parse()を実行すると、SyntaxError: Unexpected token < in JSON at position 0というエラーが発生し、プログラム全体が即死してしまいます。第30回で学んだtry...catchを挟んで、安全に身を守りましょう!
/**
* 安全にJSONをパースするヘルパー関数
*/
function safeJsonParse(jsonString) {
try {
return JSON.parse(jsonString);
} catch (error) {
Logger.log("⚠️ JSONパースに失敗しました。受信データが不正です: " + error.message);
return null; // エラー時は安全に null を返す
}
}
プロ技②:オプショナルチェイニング(?.)で undefined エラーをエレガントに回避
深いネスト構造からデータを取り出す際、もし途中のflightが存在しなかった場合、data.tripPlan.flight.arrivalと書くとTypeError: Cannot read properties of undefinedが発生してクラッシュします。
最新のJavaScript(GAS V8エンジン対応)では、オプショナルチェイニング演算子(?.)を使うことで、途中のデータが存在しなくてもエラーにならず安全にundefinedを返してくれます!
// 昔の泥臭い安全対策(長くて読みづらい)
var arrival = (data && data.tripPlan && data.tripPlan.flight) ? data.tripPlan.flight.arrival : "未定";
// モダンなプロの書き方(?. を使うと1行で超スッキリ!)
var arrival = data?.tripPlan?.flight?.arrival ?? "未定";
プロ技③:ディープコピー(参照を切ったオブジェクトの完全複製)
JavaScriptでは、オブジェクトを変数に代入すると「同じメモリの場所を参照する(参照渡し)」ため、コピー先の値を書き換えると元のオブジェクトまで勝手に書き換わってしまうという厄介な仕様があります。
JSON.stringify()して即座にJSON.parse()を通すことで、元のデータと完全に縁を切った「完全な独立クローン(ディープコピー)」を一瞬で作成できます!
var originalData = { office: "札幌", budget: 100000 };
// JSONを経由して完全クローンを作成!
var clonedData = JSON.parse(JSON.stringify(originalData));
clonedData.budget = 200000; // クローン側だけ変更
Logger.log(originalData.budget); // ➔ 100000 のまま保持される!
7. 初心者が100%つまずく!JSONの5大トラップと完全対処法
JSONを扱い始めた開発者が、必ずと言っていいほど一度は直面する「典型的な5大トラップ」をまとめました。エラーが出たときはまずここをチェックしてみてください!
トラップ1:シングルクォーテーション「'」を使って構文エラーになる
// ✕ 絶対にやってはいけないNG記法(JSONの仕様違反)
var badJson = "{ 'name': '札幌太郎' }";
JSON.parse(badJson); // ➔ SyntaxError発生!
// ◯ 正しい書き方(必ず「ダブルクォーテーション "」を使う)
var goodJson = '{ "name": "札幌太郎" }';
JSON.parse(goodJson); // 正常完了!
【原因と対策】 JavaScriptのコード上ではシングルクォーテーション'も自由に使えますが、「JSONの世界のルール」ではキーも文字列も必ず半角のダブルクォーテーション"で囲まなければならないと厳格に決まっています。外側をシングルクォーテーションで囲み、内側を"にするのが基本です。
トラップ2:末尾のカンマ(Trailing Comma)を残してしまう
// ✕ NG:最後の要素の後ろにカンマがある
var badJson = '{"name": "札幌", "price": 500, }'; // 末尾の「,」が原因でエラー!
JSON.parse(badJson); // ➔ SyntaxError
【原因と対策】 モダンなJavaScriptでは配列の最後のカンマは許容されますが、JSON規格では「最後のカンマ」は完全な文法違反です。自作でJSON文字列を組み立てる際は末尾のカンマを必ず除去しましょう。
トラップ3:undefined や関数が stringify で綺麗サッパリ消滅する
var myData = {
office: "札幌",
memo: undefined, // undefined
calc: function() { return 100; } // 関数
};
var jsonStr = JSON.stringify(myData);
Logger.log(jsonStr);
// ➔ 実行結果:{"office":"札幌"} (memo と calc が消える!)
【原因と対策】 JSONには「undefined」や「関数」というデータ型が存在しません。そのため、JSON.stringify()を通した瞬間に自動的に無視されて消滅します。空の値を送りたい場合は、undefinedではなく明示的にnullをセットしておきましょう。
トラップ4:すでにオブジェクトのものを二重に JSON.parse() しようとする
UrlFetchAppのレスポンスですでにライブラリ等によってオブジェクト化されているデータや、もともとオブジェクト型である変数に対して、勘違いしてもう一度JSON.parse(obj)を実行してしまうケースです。
引数にオブジェクトを渡すと、JavaScriptが裏で勝手に"[object Object]"という文字列に変換してからパースしようとするため、SyntaxError: Unexpected token o in JSON at position 1という超有名な謎エラーが出ます。「token o」が出たら、「二重パース」を疑いましょう!
トラップ5:循環参照(Circular Reference)を持つオブジェクトの変換エラー
親オブジェクトが子を持ち、子が親を参照しているようなループ構造のオブジェクトをJSON.stringify()しようとすると、TypeError: Converting circular structure to JSONエラーで停止します。APIで送信するデータは、常にシンプルな親子構造のプレーンなオブジェクトに整形してから送信しましょう。
8. 今回のまとめ&次回予告
今回は、Web API連携やシステム間データ通信の心臓部となるJSON.parse()とJSON.stringify()の相互変換テクニックについて徹底解説しました!
本日の重要ポイントおさらい
- JSONは「通信用の文字列」、JavaScriptオブジェクトは「手元で操作できるプログラム部品」!
JSON.parse(文字列)で外部から受信したJSONを解凍し、自由に取り出せるオブジェクトにする!JSON.stringify(オブジェクト)で手元のデータをテキスト化し、API送信可能な荷物に梱包する!- ログで中身を確認するときは
JSON.stringify(data, null, 2)の整形出力(Pretty Print)が圧倒的に見やすい! - 不意のHTMLエラー画面や通信トラブルで落ちないよう、パース時は
try...catchで囲むのがプロの鉄壁ガード!
冷え込みが進む札幌の街中を歩くとき、暖かい地下歩行空間(チカホ)や地下鉄の連絡通路の構造を一度頭に入れておけば、吹雪の日でも一切濡れずに目的地へ最短ルートでササッと移動できますよね。プログラミングのJSON操作も全く同じです。複雑に入り組んだデータ構造の「階層と道順」さえ見通せるようになれば、どんな外部サービスから送られてくる巨大なデータでも、迷子にならずに欲しい値へ瞬時にアクセスできるようになりますよ!
さて、データの梱包(JSON.stringify)と解凍(JSON.parse)が完璧にできるようになったところで、いよいよ次回は待ちに待った超人気テーマの実践です!
次回(第96回)のテーマは、
「UrlFetchApp.fetch() (POST) × 請求書発行や異常検知をSlackの #sapporo-dashboard チャネルに自動通知」 です!
第93回で金庫に隠したシークレットWebhook URLと、今回学んだJSON.stringify()、そしてPOST通信を合体させて、スプレッドシートやダッシュボードの更新結果をおしゃれなSlack通知としてリアルタイムに届ける実践テクニックを解説します。社内の業務効率化で最も喜ばれる花形機能ですので、ぜひ次回も楽しみにしていてくださいね!
