プロパティ サービス

プロパティ サービスを使用すると、1 つのスクリプト、1 人のユーザーのスクリプトのユーザー、1 つのアドオンが使用されている 1 つのドキュメントにスコープが設定された Key-Value ペア形式の単純なデータを保存できます。通常は、デベロッパーの構成やユーザーの設定を保存するために使用されます。プロパティがスクリプト間で共有されることはありません。

プロパティ サービスの 1 日あたりの割り当てとストレージ上限については、Google サービスの割り当てをご覧ください。

不動産店の比較

次の表に示すように、PropertiesService グローバル オブジェクトにはメソッドが 3 つあります。どのメソッドも同様の Properties オブジェクトを返しますが、アクセス権は異なります。

	スクリプト プロパティ	ユーザー プロパティ	ドキュメント プロパティ
アクセス方法	getScriptProperties()	getUserProperties()	getDocumentProperties()
データの共有相手	スクリプト、アドオン、またはウェブアプリのすべてのユーザー	スクリプト、アドオン、またはウェブアプリの現在のユーザー	開いているドキュメント内のアドオンのすべてのユーザー
一般的な用途	アプリ全体の構成データ（デベロッパーの外部データベースのユーザー名やパスワードなど）	ユーザー固有の設定（指標やヤードポンド単位など）	ドキュメント固有のデータ（埋め込みグラフのソース URL など）

データ形式

プロパティ サービスは、すべてのデータを文字列として Key-Value ペアに保存します。まだ文字列ではないデータ型は自動的に文字列に変換されます。これには、保存されたオブジェクトに含まれるメソッドも含まれます。

データの保存

単一の値を保存するには、次の例に示すように適切なストアの Properties.setProperty(key, value) メソッドを呼び出します。

service/propertyService.gs

GitHub で表示

try {
  // Set a property in each of the three property stores.
  const scriptProperties = PropertiesService.getScriptProperties();
  const userProperties = PropertiesService.getUserProperties();
  const documentProperties = PropertiesService.getDocumentProperties();

  scriptProperties.setProperty('SERVER_URL', 'http://www.example.com/');
  userProperties.setProperty('DISPLAY_UNITS', 'metric');
  documentProperties.setProperty('SOURCE_DATA_ID',
      '1j3GgabZvXUF177W0Zs_2v--H6SPCQb4pmZ6HsTZYT5k');
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

データを一括保存するには、Key-Value ペアのマップを Properties.setProperties(properties) に渡します。パラメータ内のオブジェクトの Key-Value ペアは、それぞれ個別のプロパティとして保存されます。

service/propertyService.gs

GitHub で表示

try {
  // Set multiple script properties in one call.
  const scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperties({
    'cow': 'moo',
    'sheep': 'baa',
    'chicken': 'cluck'
  });
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

データの読み取り

以前に保存した単一の値を取得するには、Properties.getProperty(key) を呼び出します。

service/propertyService.gs

GitHub で表示

try {
  // Get the value for the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  const units = userProperties.getProperty('DISPLAY_UNITS');
  console.log('values of units %s', units);
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

現在のプロパティ ストア内のすべての値を取得するには、Properties.getProperties() を呼び出します。

service/propertyService.gs

GitHub で表示

try {
  // Get multiple script properties in one call, then log them all.
  const scriptProperties = PropertiesService.getScriptProperties();
  const data = scriptProperties.getProperties();
  for (const key in data) {
    console.log('Key: %s, Value: %s', key, data[key]);
  }
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

データの修正

getProperty() メソッドと getProperties() メソッドは、ライブビューではなく、保存されたデータのコピーを返すため、返されたオブジェクトを変更しても、プロパティ ストア内の値は更新されません。ストアのデータを更新するには、もう一度保存します。

service/propertyService.gs

GitHub で表示

try {
  // Change the unit type in the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  let units = userProperties.getProperty('DISPLAY_UNITS');
  units = 'imperial'; // Only changes local value, not stored value.
  userProperties.setProperty('DISPLAY_UNITS', units); // Updates stored value.
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

データを削除する

単一の値を削除するには、Properties.deleteProperty(key) を呼び出します。

service/propertyService.gs

GitHub で表示

try {
  // Delete the user property 'DISPLAY_UNITS'.
  const userProperties = PropertiesService.getUserProperties();
  userProperties.deleteProperty('DISPLAY_UNITS');
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

現在のストア内のすべてのプロパティを削除するには、Properties.deleteAllProperties() を呼び出します。

service/propertyService.gs

GitHub で表示

try {
  // Get user properties in the current script.
  const userProperties = PropertiesService.getUserProperties();
  // Delete all user properties in the current script.
  userProperties.deleteAllProperties();
} catch (err) {
  // TODO (developer) - Handle exception
  console.log('Failed with error %s', err.message);
}

スクリプト プロパティを手動で管理する

[プロジェクトの設定] ページから、Key-Value ペアの文字列として最大 50 個のカスタム プロパティを手動で追加できます。50 個を超えるプロパティを追加するには、上記のデータの保存で説明した方法で、プログラムで追加する必要があります。プロジェクト設定ページでスクリプト プロパティを設定する場合、スクリプト変数を参照することはできません。

スクリプト プロパティを追加する

1. Apps Script プロジェクトを開きます。
2. 左側にあるプロジェクト設定アイコン をクリックします。
3. 1 つ目のプロパティを追加するには、[スクリプト プロパティ] で [スクリプト プロパティを追加] をクリックします。
4. 2 つ目のプロパティとそれ以降のプロパティを追加するには、[スクリプト プロパティ] で [スクリプト プロパティを編集] > [スクリプト プロパティを追加] をクリックします。
5. [プロパティ] にキー名を入力します。
6. [値] にキーの値を入力します。
7. （省略可）プロパティをさらに追加するには、[スクリプト プロパティを追加] をクリックします。
8. [スクリプトのプロパティを保存] をクリックします。

スクリプト プロパティの編集

1. Apps Script プロジェクトを開きます。
2. 左側にあるプロジェクト設定アイコン をクリックします。
3. [スクリプト プロパティ] で [スクリプトのプロパティを編集] をクリックします。
4. 変更する各プロパティのキー名とキー値を変更します。
5. [スクリプトのプロパティを保存] をクリックします。

スクリプト プロパティの削除

1. Apps Script プロジェクトを開きます。
2. 左側にあるプロジェクト設定アイコン をクリックします。
3. [スクリプト プロパティ] で [スクリプトのプロパティを編集] をクリックします。
4. 削除するプロパティの横にある [削除] をクリックします。
5. [スクリプトのプロパティを保存] をクリックします。