Spreadsheet dapat memiliki beberapa sheet, dengan setiap sheet memiliki sejumlah baris
atau kolom. Sel adalah lokasi di
persimpangan baris dan kolom tertentu, dan dapat berisi nilai data. Google Sheets API menyediakan resource spreadsheets.values
untuk mengaktifkan pembacaan dan penulisan nilai.
Halaman ini menjelaskan dasar-dasar penggunaan resource spreadsheets.values
. Jika
perlu menyisipkan baris atau memperbarui format dan properti lainnya dalam
sheet, Anda harus menggunakan metode
spreadsheets.batchUpdate
yang dijelaskan dalam Mengupdate spreadsheet.
Metode
Resource spreadsheets.values
menyediakan metode berikut untuk membaca dan menulis nilai, masing-masing untuk tugas tertentu:
Akses Jarak Jauh | Reading | Penulisan |
---|---|---|
Rentang tunggal | spreadsheets.values.get |
spreadsheets.values.update |
Beberapa rentang | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
Menambahkan | spreadsheets.values.append |
Secara umum, sebaiknya gabungkan beberapa pembacaan atau update dengan metode batchGet
dan batchUpdate
(masing-masing), karena cara ini akan meningkatkan efisiensi.
Anda dapat menemukan contoh setiap metode ini di halaman contoh Pembacaan dasar dan Penulisan dasar. Untuk melihat semua contoh, lihat halaman ringkasan contoh.
Dibaca
Untuk membaca nilai data dari sheet, Anda memerlukan ID spreadsheet dan notasi A1 untuk rentang tersebut. Menentukan rentang tanpa ID sheet (A1:B2
) berarti permintaan dieksekusi pada sheet pertama dalam spreadsheet. Untuk informasi selengkapnya tentang ID spreadsheet dan notasi A1, lihat Ringkasan API Google Spreadsheet.
Beberapa parameter kueri opsional mengontrol format {i>output<i}:
Parameter Format | Nilai Default |
---|---|
majorDimension |
BARIS |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Perhatikan bahwa Anda hanya boleh menggunakan dateTimeRenderOption
jika valueRenderOption
bukan FORMATTED_VALUE
.
Tidak ada batasan eksplisit terkait jumlah data yang ditampilkan. Error tidak menampilkan data. Baris dan kolom kosong di akhir akan dihilangkan.
Metode get tunggal dan batch dijelaskan di bawah ini. Untuk contoh operasi baca dasar, lihat Bacaan dasar.
Membaca satu rentang
Untuk membaca satu rentang nilai dari spreadsheet, gunakan permintaan spreadsheets.values.get
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Respons atas permintaan ini ditampilkan sebagai
objek
ValueRange
.
Membaca beberapa rentang
Untuk membaca beberapa rentang nilai yang terputus dari spreadsheet, gunakan
permintaan spreadsheets.values.batchGet
yang memungkinkan Anda menentukan beberapa rentang untuk diambil:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Respons terhadap permintaan ini ditampilkan sebagai objek
BatchGetValuesResponse
yang berisi spreadsheetId
dan daftar
objek
ValueRange
.
Tulis
Untuk menulis ke sheet, Anda memerlukan ID spreadsheet, rentang sel dalam notasi A1, dan data yang ingin ditulis dalam objek isi permintaan yang sesuai. Untuk mengetahui informasi selengkapnya tentang ID spreadsheet dan notasi A1, lihat Ringkasan Google Sheets API.
Update memerlukan
parameter ValueInputOption
yang valid.
Untuk pembaruan tunggal, ini adalah parameter kueri wajib. Untuk batch update, parameter ini diperlukan dalam isi permintaan. ValueInputOption
mengontrol
cara penafsiran data input dan apakah string input akan diuraikan atau
tidak, seperti yang dijelaskan dalam tabel berikut:
ValueInputOption |
Deskripsi |
---|---|
RAW |
Input tidak diuraikan dan disisipkan sebagai string. Misalnya, input "=1+2" akan menempatkan string, bukan formula, "=1+2" di sel. (Nilai non-string seperti boolean atau angka selalu ditangani sebagai RAW .) |
USER_ENTERED |
Input diuraikan sama seperti jika dimasukkan ke dalam UI Spreadsheet. Misalnya, "Mar 1 2016" menjadi tanggal, dan "=1+2" menjadi formula. Format juga dapat disimpulkan, sehingga "$100.15" menjadi angka dengan pemformatan mata uang. |
Metode update tunggal dan batch dijelaskan di bawah ini. Untuk contoh operasi tulis dasar, lihat Penulisan dasar.
Menulis ke satu rentang
Untuk menulis data ke satu rentang, gunakan permintaan spreadsheets.values.update
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Isi permintaan update harus berupa objek ValueRange
, meskipun satu-satunya kolom yang wajib diisi adalah values
. Jika range
ditentukan, nilai tersebut harus cocok dengan rentang di URL. Dalam ValueRange
, Anda dapat secara opsional menentukan
majorDimension
-nya.
Secara default, ROWS
digunakan. Jika COLUMNS
ditentukan, setiap array bagian dalam akan ditulis ke kolom, bukan baris.
Saat mengupdate, nilai tanpa data akan dilewati. Untuk menghapus data, gunakan string kosong ("").
Menulis beberapa rentang
Jika ingin menulis beberapa rentang yang tidak berurutan, Anda dapat menggunakan permintaan spreadsheets.values.batchUpdate
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Isi permintaan update batch harus berupa objek BatchUpdateValuesRequest
, yang berisi ValueInputOption
dan daftar objek ValueRange
(satu untuk setiap rentang yang ditulis). Setiap objek ValueRange
menentukan
range
, majorDimension
, dan data inputnya sendiri.
Tambahkan nilai
Untuk menambahkan data setelah tabel data dalam sheet, gunakan
permintaan
spreadsheets.values.append
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Isi permintaan update harus berupa objek ValueRange
, meskipun satu-satunya kolom yang wajib diisi adalah values
. Jika range
ditentukan, nilai tersebut harus cocok dengan rentang di URL. Dalam ValueRange
, Anda dapat secara opsional menentukan
majorDimension
-nya.
Secara default, ROWS
digunakan. Jika COLUMNS
ditentukan, setiap array bagian dalam akan ditulis ke kolom, bukan baris.
Rentang input digunakan untuk menelusuri data yang ada dan menemukan "tabel" dalam
rentang tersebut. Nilai ditambahkan ke baris berikutnya pada tabel, dimulai dengan kolom pertama tabel. Misalnya, perhatikan Sheet1
yang terlihat seperti ini:
A | B | C | H | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
Ada 2 tabel dalam sheet: A1:C2
dan B4:D6
. Nilai yang ditambahkan akan
dimulai dari B7
untuk semua input range
berikut:
Sheet1
, karena akan memeriksa semua data dalam sheet dan menentukan bahwa tabel diB4:D6
adalah tabel terakhir.B4
atauC5:D5
, karena keduanya ada di tabelB4:D6
.B2:D4
, karena tabel terakhir dalam rentang adalah tabelB4:D6
(meskipun tabel ini juga berisi tabelA1:C2
).A3:G10
, karena tabel terakhir dalam rentang adalah tabelB4:D6
(meskipun dimulai sebelum dan berakhir setelahnya).
Input range
berikut tidak akan memulai penulisan di B7
:
A1
akan mulai menulis diA3
, karena berada di tabelA1:C2
.E4
akan mulai menulis diE4
, karena tidak ada di tabel mana pun. (A4
juga akan mulai menulis padaA4
karena alasan yang sama.)
Selain itu, Anda dapat memilih apakah ingin menimpa data yang ada setelah tabel atau menyisipkan baris baru untuk data baru. Secara default, input akan menimpa data setelah tabel. Untuk menulis data baru ke dalam baris baru, gunakan InsertDataOption
dan tentukan insertDataOption=INSERT_ROWS
.
Untuk mempelajari batas sel dan baris di Spreadsheet lebih lanjut, lihat File yang dapat Anda simpan di Google Drive.