Membaca & menulis nilai sel (original) (raw)

Langsung ke konten utama

• Beranda

• Google Sheets

  • Ringkasan
  • Panduan
  • Referensi
  • Contoh
  • Dukungan

• Semua produk

• Referensi

• Sheets API

• Ringkasan

• Membuat dan mengelola spreadsheet

• Membaca & amp; menulis nilai sel

• Memperbarui spreadsheet

• Format tanggal dan angka

• Smart chip

• Tabel

• Tabel pivot

• Pemformatan bersyarat

• Sheet yang Terhubung

• Menggunakan mask kolom

• Menggunakan Google Chart

• Bermigrasi dari Sheets API v3

• Perluas & amp; otomatiskan

• Pengaya

• Apps Script

Membaca & menulis nilai sel

Spreadsheet dapat memiliki beberapa sheet, dengan setiap sheet memiliki sejumlah baris atau kolom. Sel adalah lokasi di persimpangan baris dan kolom tertentu, dan mungkin berisi nilai data. Google Sheets API menyediakan resourcespreadsheets.valuesuntuk memungkinkan pembacaan dan penulisan nilai.

Halaman ini menjelaskan dasar-dasar penggunaan resource spreadsheets.values. Jika Anda perlu menyisipkan baris atau memperbarui pemformatan dan properti lainnya di sheet, Anda harus menggunakan metodespreadsheets.batchUpdateyang dijelaskan dalam Memperbarui spreadsheet.

Metode

Resourcespreadsheets.valuesmenyediakan metode berikut untuk membaca dan menulis nilai, masing-masing untuk tugas tertentu:

Secara umum, sebaiknya gabungkan beberapa pembacaan atau update dengan metodebatchGet dan batchUpdate (masing-masing), karena hal ini meningkatkan efisiensi.

Anda dapat menemukan contoh setiap metode ini di halaman contoh Basic reading dan Basic writing. Untuk melihat semua contoh, lihat halaman ringkasan contoh.

Baca

Untuk membaca nilai data dari sheet, Anda memerlukan ID spreadsheet dan notasi A1 untuk rentang. Menentukan rentang tanpa ID sheet (A1:B2) berarti permintaan dijalankan di 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:

Perhatikan bahwa Anda hanya boleh menggunakan dateTimeRenderOption jika valueRenderOptionbukan FORMATTED_VALUE.

Tidak ada batasan eksplisit untuk jumlah data yang ditampilkan. Error tidak menampilkan data. Baris dan kolom kosong di akhir tidak disertakan.

Metode pengambilan tunggal dan batch dijelaskan di bawah. Untuk contoh operasi baca dasar, lihat Membaca dasar.

Membaca rentang tunggal

Untuk membaca satu rentang nilai dari spreadsheet, gunakan permintaanspreadsheets.values.get:

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

Respons terhadap permintaan ini ditampilkan sebagai objekValueRange.

Membaca beberapa rentang

Untuk membaca beberapa rentang nilai yang tidak berurutan dari spreadsheet, gunakan permintaanspreadsheets.values.batchGetyang memungkinkan Anda menentukan beberapa rentang yang akan diambil:

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

Respons terhadap permintaan ini ditampilkan sebagai objekBatchGetValuesResponseyang berisi spreadsheetId dan daftar objekValueRange.

Tulis

Untuk menulis ke sheet, Anda memerlukan ID spreadsheet, rentang sel dalam notasi A1, dan data yang ingin Anda tulis dalam objek isi permintaan yang sesuai. Untuk mengetahui informasi selengkapnya tentang ID spreadsheet dan notasi A1, lihat Ringkasan Google Sheets API.

Pembaruan memerlukan parameterValueInputOption yang valid. Untuk update tunggal, ini adalah parameter kueri wajib. Untuk update batch, parameter ini diperlukan dalam isi permintaan. Kontrol ValueInputOptionmengontrol cara data input harus ditafsirkan dan apakah string input diuraikan atau tidak, seperti yang dijelaskan dalam tabel berikut:

Metode pembaruan 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 permintaanspreadsheets.values.update:

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

Isi permintaan update harus berupa objekValueRange, meskipun satu-satunya kolom yang wajib diisi adalah values. Jika range ditentukan, nilai tersebut harus cocok dengan rentang di URL. Di ValueRange, Anda dapat secara opsional menentukanmajorDimensionnya. Secara default, ROWS 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 berurutan, Anda dapat menggunakan permintaanspreadsheets.values.batchUpdate:

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

Isi permintaan update batch harus berupa objekBatchUpdateValuesRequest, yang berisi ValueInputOption dan daftar objekValueRange (satu untuk setiap rentang yang ditulis). Setiap objek ValueRange menentukanrange, majorDimension, dan data inputnya sendiri.

Tambahkan nilai

Untuk menambahkan data setelah tabel data dalam sheet, gunakan permintaanspreadsheets.values.append:

Apps Script

Java

JavaScript

Node.js

PHP

Python

Ruby

Isi permintaan update harus berupa objekValueRange, meskipun satu-satunya kolom yang wajib diisi adalah values. Jika range ditentukan, nilai tersebut harus cocok dengan rentang di URL. Di ValueRange, Anda dapat secara opsional menentukanmajorDimensionnya. Secara default, ROWS 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 berikutnya dalam tabel, dimulai dengan kolom pertama tabel. Misalnya, pertimbangkan Sheet1 yang terlihat seperti:

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 di B4:D6 adalah tabel terakhir.
• B4 atau C5:D5, karena keduanya ada dalam tabel B4:D6.
• B2:D4, karena tabel terakhir dalam rentang adalah tabel B4:D6 (meskipun juga berisi tabel A1:C2).
• A3:G10, karena tabel terakhir dalam rentang adalah tabel B4:D6 (meskipun dimulai sebelum dan berakhir setelahnya).

Input range berikut tidak akan mulai menulis pada B7:

• A1 akan mulai menulis pada A3, karena ada di tabel A1:C2.
• E4 akan mulai menulis di E4, karena tidak ada dalam tabel mana pun. (A4 juga akan mulai menulis pada A4 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, gunakanInsertDataOptiondan tentukan insertDataOption=INSERT_ROWS.

Untuk mempelajari lebih lanjut batas sel dan baris di Spreadsheet, lihatFile yang dapat Anda simpan di Google Drive.

Kecuali dinyatakan lain, konten di halaman ini dilisensikan berdasarkan Lisensi Creative Commons Attribution 4.0, sedangkan contoh kode dilisensikan berdasarkan Lisensi Apache 2.0. Untuk mengetahui informasi selengkapnya, lihat Kebijakan Situs Google Developers. Java adalah merek dagang terdaftar dari Oracle dan/atau afiliasinya.

Terakhir diperbarui pada 2026-04-01 UTC.