【Googleスプレッドシート】Apps ScriptでJSON.parseとJSON.stringifyの使い方!APIレスポンスの整形

APIから取得したデータはJSON形式であることが多く、そのままではスプレッドシートで扱いにくいものです。JSON.parseとJSON.stringifyを使えば、データを自在に変換してシートに書き込んだり、他のシステムに送信したりできます。この記事ではApps Scriptでこれらの関数を活用し、APIレスポンスを効率的に整形する方法を解説します。具体的なコード例とともに、よくあるエラーの対処法も紹介します。

JSON.parseとJSON.stringifyの基本概念

JSONはデータ交換の標準フォーマットで、ほとんどのWeb APIがレスポンスとしてJSON文字列を返します。Apps Scriptでは、UrlFetchAppでAPIを呼び出した結果は文字列として取得されます。この文字列をそのままスプレッドシートに書き込んでも、セルに数値や日付として正しく格納できません。そこでJSON.parseを使ってJavaScriptオブジェクトに変換し、必要なプロパティにアクセスできるようにします。逆に、スプレッドシートのデータを他のAPIに送信するときは、オブジェクトをJSON.stringifyで文字列に変換してから送信します。これらの関数はJavaScriptの標準メソッドであり、Apps Scriptでもそのまま利用できます。

JSON.parseの基本手順

手順1: APIレスポンスを文字列として取得する

1. UrlFetchApp.fetch でAPIを呼び出す
   UrlFetchApp.fetch(URL) を使ってAPIからデータを取得します。戻り値はHTTPResponseオブジェクトです。
2. getContentText で本文を文字列として取得する
   HTTPResponseオブジェクトのgetContentText()メソッドで、レスポンスボディを文字列として取得します。
3. JSON.parse でオブジェクトに変換する
   取得した文字列をJSON.parse()に渡してJavaScriptオブジェクトに変換します。

例えば、次のように記述します。

function fetchData() {
  var url = 'https://api.example.com/data';
  var response = UrlFetchApp.fetch(url);
  var jsonString = response.getContentText();
  var data = JSON.parse(jsonString);
  Logger.log(data);
}

このコードでは、APIから取得したJSON文字列をオブジェクトに変換し、ログに出力しています。data変数にはオブジェクトが代入されるため、data.key のようにプロパティにアクセスできます。

JSON.stringifyの基本手順

手順2: オブジェクトをJSON文字列に変換する

1. 変換したいオブジェクトを用意する
   スプレッドシートから取得したデータなどをオブジェクトとして準備します。
2. JSON.stringify で文字列に変換する
   JSON.stringify(オブジェクト) を実行すると、JSON形式の文字列が返ります。
3. 文字列を送信または保存する
   変換した文字列を別のAPIに送信したり、ログとして保存したりします。

具体例として、シートのデータをオブジェクトに変換してからJSON文字列にします。

function sheetToJson() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var range = sheet.getDataRange();
  var values = range.getValues();
  var headers = values[0];
  var jsonArray = [];
  for (var i = 1; i < values.length; i++) {
    var row = values[i];
    var obj = {};
    for (var j = 0; j < headers.length; j++) {
      obj[headers[j]] = row[j];
    }
    jsonArray.push(obj);
  }
  var jsonString = JSON.stringify(jsonArray);
  Logger.log(jsonString);
}

この関数は、シートの全データをJSON文字列に変換します。ヘッダー行をキーにしたオブジェクトの配列になり、JSON.stringifyで文字列化しています。

APIレスポンスをシートに書き込む実践例

実際にAPIからデータを取得し、シートに書き込む例を示します。ここでは例として、JSONPlaceholderのサンプルAPIを使用します。

function importUsers() {
  var url = 'https://jsonplaceholder.typicode.com/users';
  var response = UrlFetchApp.fetch(url);
  var jsonString = response.getContentText();
  var users = JSON.parse(jsonString);
  
  var sheet = SpreadsheetApp.getActiveSheet();
  sheet.clear();
  var headers = ['ID', 'Name', 'Username', 'Email'];
  sheet.appendRow(headers);
  
  users.forEach(function(user) {
    var row = [user.id, user.name, user.username, user.email];
    sheet.appendRow(row);
  });
}

このコードでは、JSON.parseでユーザー配列を取得し、各ユーザーのプロパティをセルに書き込んでいます。appendRowで一行ずつ追加します。

よくあるエラーとその対処法

JSON.parseが失敗する原因と対策

JSON.parseは引数が正しいJSON形式でないとエラーになります。例えば、シングルクォートで囲まれていたり、末尾にカンマがある文字列はパースに失敗します。そのため、try…catchでエラーを処理することが重要です。

function safeParse(jsonString) {
  try {
    return JSON.parse(jsonString);
  } catch (e) {
    Logger.log('パースエラー: ' + e);
    return null;
  }
}

循環参照によるJSON.stringifyのエラー

オブジェクトが自分自身への参照を含む循環構造の場合、JSON.stringifyはエラーになります。これを避けるには、文字列化する前に循環参照を削除するか、replacer関数を使用します。

var obj = {};
obj.self = obj;
// 以下の行はエラーになる
// JSON.stringify(obj);
// 対策: 循環参照を除去する

文字列に改行や特殊文字が含まれる場合

APIレスポンスに改行コードやタブが含まれていると、JSON.parseがエラーになることがあります。事前に replace メソッドで特殊文字をエスケープするか、正しいJSONであることを確認します。

var cleanString = jsonString.replace(/[\n\t]/g, ' ');
var data = JSON.parse(cleanString);

JSON.parseとJSON.stringifyの比較

関数	入力	出力	主な用途
JSON.parse	JSON形式の文字列	JavaScriptオブジェクト、配列、またはプリミティブ値	APIレスポンスのパース、外部データの読み込み
JSON.stringify	JavaScriptオブジェクト、配列、またはプリミティブ値	JSON形式の文字列	データのシリアライズ、API送信、ログ出力

上記の表から、両者は逆の変換を行っていることがわかります。適切に使い分けることで、Apps Script内でのデータ変換がスムーズになります。

まとめ

この記事では、Apps ScriptにおけるJSON.parseとJSON.stringifyの基本的な使い方と実践例を解説しました。JSON.parseでAPIレスポンスをオブジェクトに変換し、シートに書き込む流れを習得できたはずです。また、JSON.stringifyでシートのデータをJSON文字列に変換する方法も紹介しました。これらの関数を使いこなすことで、外部APIとの連携が格段に楽になります。次は、UrlFetchAppの詳細なオプションやOAuth認証について学んでみると良いでしょう。