Layanan Properti

Layanan properti memungkinkan Anda menyimpan data sederhana dalam key-value pair yang dicakupkan ke satu skrip, satu pengguna skrip, atau satu dokumen yang menggunakan add-on. Peristiwa ini biasanya digunakan untuk menyimpan konfigurasi developer atau preferensi pengguna. Properti tidak pernah dibagikan di antara skrip.

Untuk melihat kuota harian dan batas penyimpanan untuk layanan Properti, lihat Kuota untuk Layanan Google.

Perbandingan toko properti

Objek global PropertiesService menawarkan tiga metode, yang masing-masing menampilkan objek Properties yang serupa, tetapi dengan hak akses yang berbeda, seperti yang ditunjukkan pada tabel berikut:

Properti Skrip Properti Pengguna Properti Dokumen
Metode untuk mengakses getScriptProperties() getUserProperties() getDocumentProperties()
Data yang dibagikan di antara Semua pengguna skrip, add-on, atau aplikasi web Pengguna skrip, add-on, atau aplikasi web saat ini Semua pengguna add-on dalam dokumen yang terbuka
Biasanya digunakan untuk Data konfigurasi seluruh aplikasi, seperti nama pengguna dan sandi untuk database eksternal developer Setelan khusus pengguna, seperti metrik atau unit imperial Data khusus dokumen, seperti URL sumber untuk diagram tersemat

Format data

Layanan Properties menyimpan semua data sebagai string dalam key-value pair. Jenis data yang belum menjadi string akan otomatis dikonversi menjadi string, termasuk metode yang terdapat dalam objek tersimpan.

Menyimpan data

Untuk menyimpan satu nilai, panggil metode Properties.setProperty(key, value) toko yang sesuai, seperti yang ditunjukkan dalam contoh berikut:

service/propertyService.gs
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);
}

Untuk menyimpan data secara massal, teruskan peta key-value pair ke Properties.setProperties(properties). Setiap key-value pair objek dalam parameter disimpan sebagai properti terpisah:

service/propertyService.gs
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);
}

Membaca data

Untuk mengambil satu nilai yang sebelumnya telah Anda simpan, panggil Properties.getProperty(key):

service/propertyService.gs
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);
}

Untuk mengambil semua nilai di penyimpanan properti saat ini, panggil Properties.getProperties():

service/propertyService.gs
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);
}

Mengubah data

Metode getProperty() dan getProperties() menampilkan salinan data yang tersimpan, bukan tampilan langsung, sehingga mengubah objek yang ditampilkan tidak akan memperbarui nilai di penyimpanan properti. Untuk memperbarui data di penyimpanan, cukup simpan lagi:

service/propertyService.gs
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);
}

Menghapus data

Untuk menghapus satu nilai, panggil Properties.deleteProperty(key):

service/propertyService.gs
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);
}

Untuk menghapus semua properti di toko saat ini, panggil Properties.deleteAllProperties():

service/propertyService.gs
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);
}

Mengelola properti skrip secara manual

Anda dapat menambahkan hingga lima puluh properti kustom secara manual, sebagai string di key-value pair, dari halaman setelan project. Untuk menambahkan lebih dari lima puluh properti, Anda perlu menambahkannya secara terprogram menggunakan metode yang dijelaskan di atas dalam Menyimpan data. Saat Anda menetapkan properti skrip dari halaman setelan project, Anda tidak dapat mereferensikan variabel skrip.

Menambahkan properti skrip

  1. Buka project Apps Script Anda.
  2. Di sebelah kiri, klik Setelan Project Ikon untuk setelan project.
  3. Untuk menambahkan properti pertama, di bagian Script Properties, klik Add script property.
  4. Untuk menambahkan properti kedua dan berikutnya, di bagian Properti Skrip, klik Edit properti skrip > Tambahkan properti skrip.
  5. Untuk Properti, masukkan nama kunci.
  6. Untuk Nilai, masukkan nilai kunci.
  7. (Opsional) Untuk menambahkan properti lainnya, klik Tambahkan properti skrip.
  8. Klik Simpan properti skrip.

Edit properti skrip

  1. Buka project Apps Script Anda.
  2. Di sebelah kiri, klik Setelan Project Ikon untuk setelan project.
  3. Di bagian Properti Skrip, klik Edit properti skrip.
  4. Buat perubahan pada nama kunci dan nilai kunci untuk setiap properti yang ingin Anda ubah.
  5. Klik Simpan properti skrip.

Hapus properti skrip

  1. Buka project Apps Script Anda.
  2. Di sebelah kiri, klik Setelan Project Ikon untuk setelan project.
  3. Di bagian Properti Skrip, klik Edit properti skrip.
  4. Di samping properti yang ingin Anda hapus, klik Hapus .
  5. Klik Simpan properti skrip.