Spreadsheet dapat memiliki beberapa sheet, dengan setiap sheet memiliki sejumlah baris
atau kolom. Cell adalah lokasi di
perpotongan pada baris dan kolom tertentu, dan mungkin berisi nilai data. Tujuan
Google Sheets API menyediakan
spreadsheets.values
untuk memungkinkan pembacaan dan penulisan nilai.
Halaman ini menjelaskan dasar-dasar penggunaan resource spreadsheets.values
. Jika
Anda perlu menyisipkan baris atau memperbarui
format dan properti lainnya dalam
, Anda harus menggunakan
spreadsheets.batchUpdate
yang dijelaskan dalam Memperbarui spreadsheet.
Metode
Referensi spreadsheets.values
menyediakan metode berikut untuk membaca dan menulis nilai, masing-masing untuk
{i>specific task<i} (tugas spesifik):
Akses Jarak Jauh | Membaca | 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 pembaruan
Metode batchGet
dan batchUpdate
(masing-masing), seiring peningkatan
tim dan efisiensi.
Anda dapat menemukan contoh tiap metode ini di halaman read dan Basic menulis contoh halaman. Untuk melihat semua contoh, lihat ke contoh halaman ringkasan.
Baca
Untuk membaca nilai data dari {i>sheet<i}, Anda memerlukan ID {i>spreadsheet<i} dan A1
notasi untuk rentang. Menentukan rentang tanpa ID sheet (A1:B2
)
berarti permintaan dieksekusi pada sheet pertama dalam {i>spreadsheet<i}. Untuk selengkapnya
informasi tentang ID spreadsheet dan notasi A1, lihat Google Sheets API
Ringkasan.
Beberapa parameter kueri opsional mengontrol format {i>output<i}:
Parameter Format | Nilai Default |
---|---|
majorDimension |
BARIS |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
Perlu diketahui 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 dasar operasi baca, lihat Bacaan dasar.
Membaca satu rentang
Untuk membaca satu rentang nilai dari {i>spreadsheet<i}, gunakan
spreadsheets.values.get
permintaan:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Respons atas permintaan ini dikirimkan sebagai
ValueRange
.
Membaca beberapa rentang
Untuk membaca beberapa rentang nilai yang tak bersambung dari {i>spreadsheet<i}, gunakan
spreadsheets.values.batchGet
yang memungkinkan Anda menetapkan beberapa rentang untuk diambil:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Respons atas permintaan ini dikirimkan sebagai
BatchGetValuesResponse
objek yang berisi spreadsheetId
dan daftar
ValueRange
objek terstruktur dalam jumlah besar.
Tulis
Untuk menulis ke {i>sheet<i}, Anda memerlukan ID {i>spreadsheet<i}, rentang sel di A1 notasi, dan data yang ingin Anda tulis dalam isi permintaan yang sesuai . Untuk informasi selengkapnya tentang ID spreadsheet dan notasi A1, lihat Ringkasan Google Sheets API.
Update memerlukan
Parameter ValueInputOption
.
Untuk pembaruan tunggal, ini adalah parameter kueri wajib. Untuk kumpulan update,
parameter ini diperlukan dalam isi permintaan. Kontrol ValueInputOption
bagaimana data input harus ditafsirkan dan apakah string input diuraikan atau
tidak, seperti yang dijelaskan dalam tabel berikut:
ValueInputOption |
Deskripsi |
---|---|
RAW |
Input tidak diuraikan dan disisipkan sebagai string. Misalnya, input "=1+2" menempatkan {i>string<i}, bukan formula, "=1+2" dalam sel. (Nilai non-string seperti boolean atau angka selalu ditangani sebagai RAW .) |
USER_ENTERED |
Input diuraikan sama persis seolah-olah dimasukkan ke dalam UI Spreadsheet. Misalnya, "Mar 1 2016" menjadi tanggal, dan "=1+2" menjadi formula. Format juga dapat disimpulkan, jadi "$100,15" menjadi angka dengan pemformatan mata uang. |
Metode update tunggal dan batch dijelaskan di bawah ini. Untuk contoh dasar operasi tulis, lihat Penulisan dasar.
Menulis ke satu rentang
Untuk menulis data ke satu rentang, gunakan metode
spreadsheets.values.update
permintaan:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Isi permintaan pembaruan harus berupa
ValueRange
, meskipun satu-satunya bidang yang wajib diisi adalah values
. Jika range
ditentukan, maka
harus cocok dengan rentang dalam URL. Di ValueRange
, Anda dapat secara opsional menentukan
ini
majorDimension
.
Secara default, ROWS
akan 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 ("").
Menulis beberapa rentang
Jika Anda ingin menulis beberapa rentang yang terputus, Anda dapat menggunakan
spreadsheets.values.batchUpdate
permintaan:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Isi permintaan update batch harus berupa
BatchUpdateValuesRequest
objek, yang berisi ValueInputOption
dan daftar
ValueRange
objek (satu untuk setiap rentang yang ditulis). Setiap objek ValueRange
menentukan
range
, majorDimension
, dan data input.
Tambahkan nilai
Untuk menambahkan data setelah tabel data dalam sheet, gunakan metode
spreadsheets.values.append
permintaan:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
Isi permintaan pembaruan harus berupa
ValueRange
, meskipun satu-satunya bidang yang wajib diisi adalah values
. Jika range
ditentukan, maka
harus cocok dengan rentang dalam URL. Di ValueRange
, Anda dapat secara opsional menentukan
ini
majorDimension
.
Secara default, ROWS
akan digunakan. Jika COLUMNS
ditentukan, setiap array bagian dalam akan
ditulis ke kolom,
bukan baris.
Rentang input digunakan untuk mencari data yang ada dan menemukan "tabel" dalam
rentang tersebut. Nilai ditambahkan ke baris berikutnya pada tabel, dimulai dengan
kolom pertama dari tabel. Misalnya, perhatikan Sheet1
yang terlihat seperti:
A | B | C | D | 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 pukul B7
untuk semua input range
berikut:
Sheet1
, karena metode ini 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 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 Anda 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 metode
InsertDataOption
dan menentukan insertDataOption=INSERT_ROWS
.
Untuk mempelajari lebih lanjut batas sel dan baris di Spreadsheet, lihat File yang dapat Anda simpan di Google Drive.