【Googleスプレッドシート】Apps ScriptでDocumentプロパティを使う!ファイル単位のデータ保存

Googleスプレッドシートでスクリプトを書いていると、スクリプト全体で共有するデータ保存場所としてScriptプロパティを使うことがあります。しかし、ファイルごとに個別のデータを持たせたい場合は、Documentプロパティが便利です。この記事では、Apps ScriptのDocumentプロパティを使ってスプレッドシート単位でデータを保存・取得する方法を解説します。具体的なコード例や注意点も紹介しますので、ぜひ参考にしてください。

Documentプロパティの概要とその仕組み

Documentプロパティは、スプレッドシートファイルごとに独立したプロパティストアです。Scriptプロパティがスクリプト全体で共有されるのに対し、Documentプロパティはそのファイル内でのみ有効です。保存できるデータは文字列のみで、数値やオブジェクトを保存する場合はJSON文字列に変換する必要があります。最大容量は500KB程度で、ファイルのコピー時にはプロパティは引き継がれません。この仕組みにより、ファイル固有の設定や実行状態を安全に管理できます。

Documentプロパティを使用する手順

1. プロパティオブジェクトの取得

まずは、Documentプロパティを操作するためのオブジェクトを取得します。以下のコードをスクリプトエディタに記述してください。

function getDocProps() {
  var props = PropertiesService.getDocumentProperties();
  return props;
}

この関数を実行すると、現在のスプレッドシートに紐付いたプロパティオブジェクトが返ります。

2. データの保存(setProperty)

keyとvalueを指定してデータを保存します。valueは文字列でなければならないため、数値やオブジェクトはJSON.stringify()で変換します。

function saveData() {
  var props = PropertiesService.getDocumentProperties();
  props.setProperty('lastRun', new Date().toISOString());
  props.setProperty('count', JSON.stringify(42));
  props.setProperty('config', JSON.stringify({mode:'auto', interval:5}));
}

3. データの取得(getProperty)

保存したデータをkeyで取得します。オブジェクトの場合はJSON.parse()で戻します。

function loadData() {
  var props = PropertiesService.getDocumentProperties();
  var lastRun = props.getProperty('lastRun');
  var count = JSON.parse(props.getProperty('count'));
  var config = JSON.parse(props.getProperty('config'));
  Logger.log('最終実行: ' + lastRun);
  Logger.log('カウント: ' + count);
  Logger.log('設定: ' + JSON.stringify(config));
}

4. データの削除(deleteProperty)

特定のkeyのデータを削除するにはdeletePropertyを使います。

function deleteData() {
  var props = PropertiesService.getDocumentProperties();
  props.deleteProperty('count');
}

5. 全キーの取得(getKeys)

保存されている全てのkeyを配列として取得できます。管理画面などで活用します。

function listKeys() {
  var props = PropertiesService.getDocumentProperties();
  var keys = props.getKeys();
  Logger.log('保存キー一覧: ' + keys.join(', '));
}

Documentプロパティ使用時の注意点と制限

容量制限に注意する

Documentプロパティの最大容量は約500KBです。保存するデータ量が多いとエラーが発生します。大きなテキストや画像データは避け、軽量な設定値やフラグに限定してください。容量を超えた場合は古いデータを削除するか、別の保存方法を検討します。

データ型は文字列のみ

保存できる値は文字列だけです。数値やブール値、配列やオブジェクトを保存する場合はJSON.stringify()で文字列化し、取得時にJSON.parse()で戻す必要があります。boolean値を保存する場合は’true’や’false’の文字列として保存し、取得後に変換します。

スクリプトの権限とスコープ

Documentプロパティの読み書きには、スクリプトの実行権限が「現在のスプレッドシート」に対するものだけで済みます。Scriptプロパティよりも権限が限定されるため、他のファイルに影響を与えず安全です。ただし、トリガーを使用する場合はトリガー設定に注意してください。

DocumentプロパティとScriptプロパティの比較

項目	Documentプロパティ	Scriptプロパティ
保存スコープ	ファイル単位	スクリプト全体
最大容量	約500KB	約500KB
必要な権限	ファイルへのアクセス権のみ	スクリプトの実行権限に依存
削除タイミング	ファイルをコピーしてもプロパティはコピーされない	スクリプトが削除されるまで保持

この表の通り、Documentプロパティはファイルに紐付くため、ファイルを複製してもデータは引き継がれません。一方、Scriptプロパティはスクリプト全体で共有されるため、複数のファイルから同じスクリプトを実行する場合に便利です。用途に応じて使い分けましょう。

Documentプロパティを使うと、Googleスプレッドシートファイルごとに独立したデータ保存が可能です。スクリプトでファイル固有の設定値や状態を保持したい場合に便利です。例えば、ユーザーごとの設定や前回実行時の状態を保存するのに活用できます。是非、あなたのスクリプトに取り入れてみてください。