GASのPropertiesServiceの使い方｜設定値の保存・取得とnullの対処

2026年10月13日

GASでAPIの接続設定や処理件数を毎回コードに書き込んでいるなら、PropertiesServiceで設定値を分けて管理できます。名前をキーとして値を保存し、次の実行でも同じキーから読み出せる仕組みです。

最初に押さえるのは、保存先の共有範囲と値の型です。スクリプト全体で使う設定と、利用者ごとの設定を混ぜず、読み出した文字列を必要な型に変換します。ここでは外部サービスを呼ばずに試せる、処理件数の設定を例にします。

Script PropertiesとUser Propertiesを使い分ける

保存先	選び方	設定例
getScriptProperties()	同じスクリプトの利用者で共通にする	接続先の識別子、共通の処理件数
getUserProperties()	現在のユーザーごとに分ける	表示形式、個人の選択設定

Document Propertiesもありますが、利用できる実行環境に条件があります。通常の単独スクリプトで共通設定を保存する入門例なら、まずScript Propertiesで考えると整理しやすくなります。各保存先の共有範囲はGoogle公式のProperties Serviceガイドで確認できます。

設定値をコードから分離しても、その設定を読む権限を持つ共同編集者から秘密にできるわけではありません。APIキーを保存する場合はプロジェクトの共有相手を絞り、取得した値をログやHTMLへ出さない運用まで合わせて考えます。

プロジェクトの設定画面から値を登録する

練習用のApps Scriptプロジェクトを開きます。
左側の「プロジェクトの設定」を開き、スクリプトプロパティの項目を探します。
プロパティ名をDEMO_PAGE_SIZE、値を20として追加・保存します。
以下のコードを保存し、readDemoPageSizeを実行します。

function readDemoPageSize() {
  const raw = PropertiesService.getScriptProperties()
    .getProperty('DEMO_PAGE_SIZE');
  const pageSize = parseDemoPageSize(raw);
  console.log('今回の処理件数: ' + pageSize);
  return pageSize;
}

function parseDemoPageSize(raw) {
  if (raw === null) return 20;
  if (raw.trim() === '') {
    throw new Error('DEMO_PAGE_SIZEが空です');
  }
  const value = Number(raw);
  if (!Number.isInteger(value) || value < 1 || value > 100) {
    throw new Error('DEMO_PAGE_SIZEは1〜100の整数にしてください');
  }
  return value;
}

この例の1〜100は記事内で決めた入力条件です。PropertiesService自体が100件までしか扱えない、という意味ではありません。実際の処理内容に合わせて上限を変えます。

値を30へ変更して再実行すると、ログに表示される件数も30になります。キーを登録していない場合だけ既定値の20を使い、空文字やabc、0、小数は入力ミスとして止めています。未登録と入力誤りを区別すると、設定の欠落を見つけやすくなります。

コードから保存・更新・削除する

function saveDemoPageSize() {
  PropertiesService.getScriptProperties()
    .setProperty('DEMO_PAGE_SIZE', '30');
}

function deleteDemoPageSize() {
  PropertiesService.getScriptProperties()
    .deleteProperty('DEMO_PAGE_SIZE');
}

saveDemoPageSizeは同じキーがあれば値を上書きします。初期化用の関数を毎回呼ぶと、画面で変更した値も30に戻るため、設定を書き換えたいときだけ実行します。削除の例はDEMO_PAGE_SIZEだけを対象にしており、ほかの設定には触れません。

複数の値はsetPropertiesでまとめて保存できます。一方、getPropertiesで取得したオブジェクトを書き換えるだけでは保存先へ反映されません。更新にはsetPropertyなどの保存メソッドが必要です。個別の挙動はPropertiesクラスの公式リファレンスにまとまっています。