Spreadsheet dapat memiliki beberapa sheet, dengan setiap sheet memiliki sejumlah baris atau kolom. Sel adalah lokasi di titik potong baris dan kolom tertentu, dan dapat berisi nilai data. Google Sheets API menyediakan resource spreadsheets.values
untuk memungkinkan 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 Rentang | 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 dengan
metode batchGet
dan batchUpdate
(masing-masing), karena 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 mengetahui informasi selengkapnya tentang ID spreadsheet dan notasi A1, lihat Ringkasan Google Sheets API.
Beberapa parameter kueri opsional mengontrol format output:
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 untuk 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 Pembacaan 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 terhadap permintaan ini ditampilkan sebagai
objek
ValueRange
.
Membaca beberapa rentang
Untuk membaca beberapa rentang nilai yang tidak berkelanjutan dari spreadsheet, gunakan permintaan spreadsheets.values.batchGet
yang memungkinkan Anda menentukan beberapa rentang yang akan 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 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 update batch,
parameter ini diperlukan dalam isi permintaan. ValueInputOption
mengontrol
cara data input harus ditafsirkan dan apakah string input akan diuraikan atau
tidak, seperti yang dijelaskan dalam tabel berikut:
ValueInputOption |
Deskripsi |
---|---|
RAW |
Input tidak diuraikan dan disisipkan sebagai string. Contohnya, {i>input<i} "=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 akan diuraikan sama persis seperti saat dimasukkan ke UI Spreadsheet. Misalnya, "1 Maret 2016" akan 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. 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
.
Secara default, ROWS
akan digunakan. Jika COLUMNS
ditentukan, setiap array dalam
akan ditulis ke kolom, bukan baris.
Saat memperbarui, nilai tanpa data akan dilewati. Untuk menghapus data, gunakan string kosong ("").
Menulis beberapa rentang
Jika ingin menulis beberapa rentang yang tidak berkelanjutan, 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 tertulis). Setiap objek ValueRange
menentukan
range
, majorDimension
, dan data inputnya sendiri.
Menambahkan 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
.
Secara default, ROWS
akan digunakan. Jika COLUMNS
ditentukan, setiap array 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 tabel berikutnya, dimulai dengan kolom pertama pada tabel. Misalnya, perhatikan Sheet1
yang terlihat seperti ini:
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 di sheet: A1:C2
, dan B4:D6
. Nilai yang ditambahkan akan
dimulai dari 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 berada dalam tabelB4:D6
.B2:D4
, karena tabel terakhir dalam rentang adalah tabelB4:D6
(meskipun 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 mulai menulis pada B7
:
A1
akan mulai menulis diA3
, karena berada di tabelA1:C2
.E4
akan mulai menulis diE4
, karena tidak ada dalam 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 {i>default<i}, {i>input<i} itu akan menimpa
data setelah tabel. Untuk menulis data baru ke dalam baris baru, gunakan
InsertDataOption
dan tentukan insertDataOption=INSERT_ROWS
.
Untuk mempelajari lebih lanjut batas sel dan baris di Spreadsheet, lihat File yang dapat disimpan di Google Drive.