Jika Anda memiliki aplikasi yang sudah ada berdasarkan Google Sheets API v3, Anda dapat bermigrasi ke Google Sheets API v4. Versi v4 ini berbasis JSON, memiliki antarmuka yang lebih mudah digunakan, dan menambahkan sejumlah besar fungsionalitas yang tidak mungkin dilakukan di versi v3.
Halaman ini menyediakan pemetaan antara perintah Sheets API v3 yang lama dan operasi yang setara di Sheets API v4. Pemetaan ini sebagian besar berfokus pada koleksi spreadsheets.values, yang menyediakan fungsi baca dan tulis sel langsung. Aspek lainnya, seperti menambahkan sheet atau memperbarui properti sheet ditangani oleh koleksi spreadsheet. Perlu diketahui bahwa struktur JSON API v4 API tidak kompatibel dengan struktur XML yang digunakan di v3.
Untuk mengetahui informasi selengkapnya tentang resource yang tersedia di Sheets v4 API, lihat Referensi API.
Notasi dan ketentuan
API v3 mengacu pada sheet dalam spreadsheet tertentu sebagai "worksheet". Ini identik dengan istilah "sheets" yang digunakan API v4.
API ini sering kali mengharuskan Anda menentukan ID spreadsheet dari spreadsheet yang sedang Anda kerjakan. Mereka juga sering kali memerlukan ID sheet yang dimanipulasi. Nilai ini muncul sebagai bagian dari URL endpoint API, sebagai parameter kueri, atau sebagai bagian dari isi permintaan. Di halaman ini, placeholder spreadsheetId dan sheetId masing-masing merujuk pada ID spreadsheet dan sheet. Saat menggunakan metode yang dijelaskan di halaman ini, ganti ID aktual di lokasi tersebut.
API v3 juga menetapkan ID ke baris yang diambil menggunakan feed daftar; hal ini direpresentasikan di halaman ini oleh placeholder rowId.
Izinkan permintaan
Saat aplikasi Anda berjalan, aplikasi akan meminta pengguna untuk memberikan izin tertentu; cakupan yang Anda tetapkan dalam aplikasi akan menentukan izin mana yang diminta.
API v3
Sheets API v3 beroperasi dengan satu cakupan otorisasi:
https://spreadsheets.google.com/feeds
yang merupakan alias untuk
https://www.googleapis.com/auth/spreadsheets
Salah satu format cakupan dapat digunakan.
API v4
Sheets API v4 menggunakan satu atau beberapa kumpulan cakupan berikut:
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
Gunakan cakupan hanya baca jika aplikasi Anda tidak perlu mengedit properti sheet atau sheet pengguna. Gunakan cakupan spreadsheet, bukan cakupan Drive jika aplikasi tidak memerlukan akses Drive umum.
Visibilitas
Pada API versi lama, istilah visibilitas digunakan untuk merujuk pada ketersediaan spreadsheet tertentu.
API v3
Sheets API v3 menyatakan visibilitas secara langsung di endpoint-nya. Spreadsheet public
telah "Dipublikasikan ke Web" sehingga dapat diakses oleh
API tanpa otorisasi, sedangkan spreadsheet private
memerlukan
autentikasi. Visibilitas ditentukan di endpoint setelah
ID spreadsheet:
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
API v4
Di Sheets API v4 yang baru, tidak ada deklarasi eksplisit visibilitas. Panggilan API dilakukan menggunakan ID spreadsheet. Jika aplikasi tidak memiliki izin untuk mengakses spreadsheet yang ditentukan, error akan ditampilkan. Jika tidak, panggilan akan dilanjutkan.
Proyeksi
Istilah proyeksi digunakan oleh Sheets API v3 untuk merujuk pada kumpulan data yang ditampilkan oleh panggilan API tertentu—baik semuanya maupun subset tetap yang ditentukan dalam API. Sheets API v4 tidak menggunakan proyeksi; tetapi memberi Anda lebih banyak kontrol atas data yang ditampilkan.
API v3
Hanya ada dua setelan proyeksi yang memungkinkan di Sheets API v3. Proyeksi full
menampilkan semua informasi yang tersedia, sedangkan basic
menampilkan subset data yang lebih kecil dan tetap (untuk lembar kerja, daftar, dan feed sel).
Seperti visibilitas, proyeksi harus ditentukan di endpoint API
(setelah setelan visibilitas):
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
Subset data yang lebih kecil yang disediakan oleh proyeksi basic
berguna
untuk membuat kode lebih efisien, tetapi tidak dapat disesuaikan.
API v4
Meskipun Sheets API v4 dapat menampilkan set data lengkap, Sheets API v3 tidak akan menentukan subset tetap
yang serupa dengan setelan visibilitas basic
di Sheets API v3.
Metode dalam koleksi spreadsheet membatasi jumlah data yang ditampilkan melalui penggunaan parameter kueri fields.
Misalnya, kueri berikut hanya menampilkan judul semua sheet dalam spreadsheet tertentu:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
Buat spreadsheet
API v3
Sheets API v3 tidak menyediakan cara untuk membuat spreadsheet baru;
sebagai gantinya, metode Drive API Files.create
dapat digunakan untuk membuat file spreadsheet baru. Hal ini mengharuskan
aplikasi mendeklarasikan cakupan https://www.googleapis.com/auth/drive
.
API v4
Metode Drive API Files.create juga dapat
digunakan dengan Sheets API v4, tetapi mengharuskan aplikasi untuk menyediakan
cakupan https://www.googleapis.com/auth/drive
.
Sebagai alternatif yang setara, Sheets API v4 menyediakan metode spreadsheets.create, yang juga dapat secara opsional menambahkan sheet, menetapkan properti spreadsheet dan sheet, serta menambahkan rentang bernama. Misalnya, perintah berikut akan membuat spreadsheet baru dan memberinya nama "NewTitle":
POST https://sheets.googleapis.com/v4/spreadsheets
{ "properties": {"title": "NewTitle"} }
Mencantumkan spreadsheet untuk pengguna yang diautentikasi
API v3
Feed Sheets API v3 memungkinkan aplikasi mengambil daftar semua spreadsheet yang dapat diakses oleh pengguna yang diautentikasi. Endpoint feed {i>spreadsheet<i} adalah:
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
API v4
Sheets API v4 tidak menyediakan operasi spesifik ini. Sebaiknya migrasikan aplikasi untuk menggunakan cakupan drive.file yang dikombinasikan dengan Alat Pilih Google untuk pemilihan spreadsheet.
Jika diperlukan untuk mencantumkan spreadsheet, spreadsheet tersebut dapat direplikasi melalui metode Drive API Files.list menggunakan kueri mimeType
:
GET https://www.googleapis.com/drive/v3/files ?q=mimeType='application/vnd.google-apps.spreadsheet'
Penggunaan metode files.list Drive API untuk mencantumkan semua spreadsheet pengguna memerlukan cakupan yang dibatasi.
Mengambil metadata sheet
Sheets API v3 menyediakan feed untuk mengakses metadata sheet yang terdapat dalam spreadsheet tertentu (data baris dan sel diakses melalui feed terpisah). Metadata ini mencakup informasi seperti informasi ukuran dan judul sheet.
Metode spreadsheets.get Sheets API v4 menyediakan akses ke informasi ini, dan banyak lagi.
API v3
Feed lembar kerja dapat diakses dari endpoint API ini (menggunakan header otorisasi yang sesuai):
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
Respons terhadap permintaan ini memiliki struktur yang mirip dengan ini, dengan
setiap data sheet terdapat dalam <entry>
terpisah:
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
API v4
Metode spreadsheets.get dapat digunakan untuk memperoleh properti sheet dan metadata lainnya, jauh lebih banyak daripada yang tersedia menggunakan Sheets API v3. Jika Anda hanya ingin membaca properti sheet, tetapkan parameter kueri includeGridData
ke false
untuk mencegah penyertaan data sel spreadsheet:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Respons Spreadsheet
berisi array objek Sheet
;
judul sheet dan informasi ukuran secara khusus dapat ditemukan
pada elemen SheetProperties
objek ini. Contoh:
{ "spreadsheetId": spreadsheetId, "sheets": [ {"properties": { "sheetId": sheetId, "title": "Sheet1", "index": 0, "gridProperties": { "rowCount": 100, "columnCount": 20, "frozenRowCount": 1, "frozenColumnCount": 0, "hideGridlines": false }, ... }, ... }, ... ], ... }
Menambahkan sheet ke spreadsheet
Kedua API memungkinkan Anda menambahkan sheet baru ke spreadsheet yang ada.
API v3
Sheets API v3 dapat menambahkan lembar kerja baru ke spreadsheet dengan membuat permintaan POST
berikut (diautentikasi). Anda dapat menentukan ukuran
sheet baru:
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
API v4
Anda dapat menambahkan sheet baru dengan membuat permintaan AddSheet di metode spreadsheets.batchUpdate. Sebagai bagian dari isi permintaan, Anda dapat menentukan properti sheet untuk sheet baru; semua properti bersifat opsional. Akan terjadi error jika memberikan judul yang digunakan untuk sheet yang ada.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [{ "addSheet": { "properties": { "title": "Expenses", "sheetType": "GRID", "gridProperties": { "rowCount": 50, "columnCount": 10 } } } }], }
Mengubah judul dan ukuran sheet
Sheets API v3 memungkinkan Anda memperbarui judul dan ukuran sheet. Sheets API v4 juga memungkinkan Anda, tetapi juga dapat digunakan untuk memperbarui properti sheet lainnya. Perhatikan bahwa mengurangi ukuran sheet dapat menyebabkan data dalam sel yang dipangkas akan dihapus tanpa peringatan.
API v3
Untuk mengubah judul atau ukuran lembar kerja, mulailah dengan mengambil feed lembar kerja dan menemukan entri lembar kerja yang diinginkan, yang berisi URL edit
.
Perbarui metadata lembar kerja dan kirimkan sebagai isi permintaan PUT
ke URL edit. Contoh:
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
API v4
Untuk memperbarui ukuran, judul, dan properti sheet lainnya, buat permintaan updateSheetProperties di metode spreadsheets.batchUpdate. Isi permintaan POST
harus berisi properti yang akan diubah, dan parameter fields
harus mencantumkan properti tersebut secara eksplisit (jika Anda ingin mengupdate semua properti, gunakan fields:"*"
sebagai singkatan untuk mencantumkan semuanya). Misalnya, kode berikut menentukan bahwa properti ukuran dan judul sheet
harus diupdate untuk sheet dengan ID yang diberikan:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "updateSheetProperties": { "properties": { "sheetId": sheetId, "title": "Expenses", "gridProperties": { "rowCount": 45, "columnCount": 15, } }, "fields": "title,gridProperties(rowCount,columnCount)" } } ], }
Untuk mengambil sheetId sheet, gunakan metode spreadsheets.get spreadsheet.
Menghapus sheet
API dapat menghapus sheet dari spreadsheet yang diberikan.
API v3
Untuk menghapus lembar kerja, mulailah dengan mengambil feed lembar kerja, lalu kirim permintaan DELETE
pada URL edit
dari entri lembar kerja target.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
API v4
Untuk menghapus sheet, buat permintaan DeleteSheet di metode spreadsheets.batchUpdate. Isi permintaan POST
hanya boleh berisi sheetId untuk
sheet yang akan dihapus. Contoh:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteSheet": { "sheetId": sheetId } } ], }
Untuk mengambil sheetId setiap sheet, gunakan metode spreadsheets.get spreadsheet.
Mengambil data baris
Feed baris daftar adalah salah satu dari dua metode yang disediakan Sheets API v3 untuk mengakses data dalam sel spreadsheet (metode satunya lagi adalah feed sel). Feed baris dimaksudkan untuk mendukung operasi spreadsheet umum (membaca baris demi baris, menambahkan baris, mengurutkan), tetapi membuat asumsi tertentu yang membuatnya tidak cocok untuk beberapa tugas. Secara khusus, feed daftar mengasumsikan bahwa baris kosong adalah penghentian feed, dan bahwa header wajib ada di baris pertama sheet.
Sebaliknya, Sheets API v4 tidak menggunakan metode akses yang spesifik untuk baris. Sebagai gantinya, data sel sheet diakses dengan mereferensikan rentang tertentu yang diperlukan menggunakan notasi A1. Rentang dapat berupa blok sel, seluruh baris, seluruh kolom, atau seluruh sheet. API juga dapat mengakses kumpulan sel yang terpisah-pisah.
API v3
Untuk menentukan URL feed berbasis daftar untuk lembar kerja tertentu, ambil feed lembar kerja dan temukan URL feed daftar dalam entri lembar kerja yang diinginkan.
Untuk mengambil feed berbasis daftar, kirim permintaan GET
ke URL feed daftar,
menggunakan header otorisasi yang sesuai. Contoh:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Respons terhadap permintaan ini berisi, antara lain, entri yang sesuai dengan baris tertentu. Masing-masing sel dirujuk oleh nama yang diberikan di baris header sheet (wajib). Misalnya, berikut ini adalah entri baris tunggal:
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>10</gsx:hours>
<gsx:items>2</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
Secara default, baris yang ditampilkan dalam feed daftar ditampilkan dalam urutan baris. Sheets API v3 menyediakan parameter kueri untuk mengubah urutan tersebut.
Urutan terbalik:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
Mengurutkan berdasarkan kolom tertentu:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full ?orderby=column:lastname
Sheets API v3 juga memungkinkan pemfilteran baris tertentu melalui kueri terstruktur (direferensikan melalui header kolom):
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full ?sq=age>25%20and%20height<175
API v4
Dengan Sheets API v4, baris dapat diambil berdasarkan rentang menggunakan metode spreadsheets.values.get atau spreadsheets.values.batchGet. Misalnya, kode berikut akan menampilkan semua baris dalam "Sheet1":
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
Respons terhadap permintaan ini memiliki struktur yang mirip dengan:
{ "range": "Sheet1", "majorDimension": "ROWS", "values": [["Name", "Hours", "Items", "IPM"], ["Bingley", "10", "2", "0.0033"], ["Darcy", "14", "6", "0.0071"]] }
Sel kosong setelahnya tidak disertakan dalam respons saat mengambil seluruh baris, kolom, atau sheet.
Sheets API v4 tidak memiliki padanan untuk parameter kueri urutan baris yang disediakan oleh Sheets API v3. Urutan terbalik tidaklah mudah; cukup
proses array values
yang ditampilkan dalam urutan terbalik. Urutan berdasarkan kolom tidak
didukung untuk pembacaan, tetapi Anda dapat mengurutkan data dalam sheet (menggunakan
permintaan SortRange),
lalu membacanya.
Sheets API v4 saat ini tidak memiliki padanan langsung untuk kueri terstruktur Sheets API v3. Namun, Anda dapat mengambil data yang relevan dan mengurutkannya sesuai kebutuhan dalam aplikasi Anda.
Menambahkan baris data baru
Anda dapat menambahkan baris data baru ke sheet menggunakan salah satu API.
API v3
Untuk menentukan URL feed berbasis daftar untuk lembar kerja tertentu, ambil feed lembar kerja dan temukan URL postingan dalam entri lembar kerja yang diinginkan.
Untuk menambahkan baris data, kirim permintaan POST
ke URL postingan,
menggunakan header otorisasi yang sesuai. Contoh:
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
Isi permintaan POST
harus berisi entri untuk data baris yang akan
ditambahkan, dengan setiap sel yang dirujuk oleh header kolom:
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
Baris baru ditambahkan ke akhir sheet yang ditetapkan.
API v4
Dengan Sheets API v4, Anda dapat menambahkan baris menggunakan metode spreadsheets.values.append. Contoh berikut menulis baris data baru di bawah tabel terakhir dalam "Sheet1" sebuah spreadsheet.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Selain itu, Sheets API v4 juga memungkinkan Anda menambahkan sel dengan properti dan pemformatan tertentu menggunakan permintaan AppendCells di spreadsheets.batchUpdate.
Mengedit baris dengan data baru
Kedua API memungkinkan data baris diperbarui dengan nilai baru.
API v3
Untuk mengedit baris data, periksa feed daftar guna menemukan entri untuk baris yang ingin Anda perbarui. Perbarui isi entri tersebut sesuai kebutuhan. Pastikan nilai ID dalam entri yang Anda gunakan sama persis dengan ID entri yang ada.
Setelah entri diupdate, kirim permintaan PUT
dengan entri tersebut sebagai
isi permintaan ke URL edit
yang diberikan dalam entri baris tersebut,
menggunakan header otorisasi yang sesuai. Contoh:
PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>20</gsx:hours>
<gsx:items>4</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
API v4
Dengan Sheets API v4, Anda dapat mengedit baris menggunakan notasi A1 baris yang ingin diedit dan mengeluarkan permintaan spreadsheets.values.update untuk menimpa baris tersebut. Rentang yang ditentukan hanya perlu merujuk ke sel pertama dalam baris; API menyimpulkan sel yang akan diperbarui berdasarkan nilai yang diberikan dengan permintaan. Jika Anda menetapkan rentang multi-sel, nilai yang Anda berikan harus muat dalam rentang tersebut. Jika tidak, API akan menampilkan error.
Contoh permintaan dan isi permintaan berikut menambahkan data ke baris keempat "Sheet1":
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{ "values": [["Elizabeth", "2", "0.5", "60"]] }
Anda juga dapat mengupdate data baris dari metode spreadsheet.values.batchUpdate karena akan lebih efisien menggunakan metode ini jika Anda melakukan beberapa update baris atau sel.
Selain itu, Sheets API v4 juga memungkinkan Anda mengedit properti sel dan memformat sel menggunakan permintaan UpdateCells atau RepeatCell di spreadsheets.batchUpdate.
Menghapus baris
Kedua API mendukung penghapusan baris. Baris yang dihapus akan dihapus dari {i>spreadsheet<i}, dan baris di bawahnya akan didorong ke atas satu baris.
API v3
Untuk menghapus baris, pertama-tama ambil baris yang akan dihapus dari feed daftar, lalu kirim permintaan DELETE
ke URL edit
yang disediakan di entri baris.
Ini adalah URL yang sama dengan yang digunakan untuk memperbarui baris.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
Jika ingin memastikan bahwa Anda tidak menghapus baris yang telah diubah oleh klien lain sejak Anda mengambilnya, sertakan header HTTP If-Match yang berisi nilai ETag baris asli. Anda dapat menentukan nilai ETag baris asli dengan memeriksa atribut gd:etag elemen entri.
Jika ingin menghapus baris, terlepas dari apakah orang lain telah memperbaruinya atau belum sejak Anda mengambilnya, gunakan If-Match: * dan jangan sertakan ETag. (Dalam hal ini, Anda tidak perlu mengambil baris tersebut sebelum menghapusnya.)
API v4
Penghapusan baris dengan Sheets API v4 ditangani oleh panggilan metode spreadsheet.batchUpdate menggunakan permintaan DeleteDimension. Permintaan ini juga dapat digunakan untuk menghapus kolom, dan developer memilih untuk menghapus bagian baris atau kolom saja. Misalnya, perintah berikut menghapus baris ke-6 pada sheet yang memiliki ID yang diberikan (indeks baris berbasis nol, dengan startIndex inklusif dan endIndex eksklusif):
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{ "requests": [ { "deleteDimension": { "range": { "sheetId": sheetId, "dimension": "ROWS", "startIndex": 5, "endIndex": 6 } } } ], }
sheetId sheet dapat diambil menggunakan metode spreadsheet.get.
Mengambil data sel
Sheets API v3 menyediakan feed sel untuk akses dasar ke semua data yang disimpan dalam
spreadsheet. Untuk akses baca, feed sel dapat menyediakan seluruh konten sheet atau rentang sel sheet yang ditentukan oleh sekumpulan parameter kueri, tetapi hanya sebagai blok tunggal. Rentang yang terpisah harus diambil secara terpisah menggunakan permintaan GET
tambahan.
Sheets API v4 dapat mengambil kumpulan data sel apa pun dari sheet (termasuk beberapa rentang yang terpisah). Sheets API v3 hanya dapat menampilkan konten sel sebagai nilai input (sebagaimana yang akan dimasukkan oleh pengguna pada keyboard) dan/atau output formula (jika numerik); Sheets API v4 memberikan akses penuh ke nilai, formula, pemformatan, hyperlink, validasi data, dan properti lainnya.
API v3
Untuk menentukan URL feed berbasis sel bagi lembar kerja tertentu, periksa feed lembar kerja dan temukan URL feed sel di entri lembar kerja yang diinginkan.
Untuk mengambil feed berbasis sel, kirim permintaan GET
ke URL feed sel,
menggunakan header otorisasi yang sesuai. Contoh:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
Sel-sel{i> <i}direferensikan menggunakan nomor baris dan kolom. Pengambilan satu rentang
tertentu dapat dilakukan menggunakan parameter kueri max-row
, min-row
, max-col
, dan
min-col
. Misalnya, perintah berikut akan mengambil semua sel di kolom 4 (D), dimulai dengan baris 2:
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full ?min-row=2&min-col=4&max-col=4
Sheets API v3 menampilkan inputValue
sel yang diambil—nilai yang akan diketikkan pengguna ke dalam antarmuka pengguna Google Spreadsheet
untuk memanipulasi sel. inputValue
dapat berupa nilai literal atau formula. API terkadang juga menampilkan numericValue
; misalnya,
jika formula menghasilkan angka. Sebagai contoh, respons dapat menyertakan entri sel
yang serupa strukturnya dengan yang berikut ini:
<entry gd:etag='"ImB5CBYSRCp7"'>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
<updated>2006-11-17T18:27:32.543Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#cell"/>
<title type="text">D4</title>
<content type="text">5</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
<gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
numericValue="5.0">5</gs:cell>
</entry>
API v4
Ambil data sel dengan memanggil metode spreadsheets.values.get atau spreadsheets.values.batchGet untuk masing-masing rentang yang diinginkan. Misalnya, contoh berikut menampilkan sel dalam kolom D pada "Sheet2", yang dimulai dengan baris 2, dalam urutan kolom-utama dan formula yang ditampilkan seperti yang dimasukkan (sel-sel kosong berikutnya dihilangkan):
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
Respons terhadap permintaan ini serupa strukturnya dengan:
{ "spreadsheetId": spreadsheetId, "valueRanges": [ {"range": "Sheet2!D2:D", "majorDimension": "COLUMNS", "values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]] }] }
Lebih efisien menggunakan spreadsheet.values.batchGet jika Anda ingin mengambil beberapa rentang data sel. Jika Anda ingin mengakses properti sel seperti pemformatan, metode spreadsheet.get diperlukan.
Mengedit sel
Sheets API v3 memungkinkan Anda mengedit konten sel dengan mengeluarkan perintah PUT
ke
feed sel dengan entri sel yang dimodifikasi sebagai isi permintaan.
Sebaliknya, Sheets API v4 menyediakan metode spreadsheets.values.update dan spreadsheets.values.batchUpdate untuk mengubah konten sel.
API v3
Untuk mengedit konten sel tunggal, pertama-tama temukan entri sel di feed sel.
Entri berisi URL edit. Perbarui entri tersebut untuk mencerminkan konten
yang Anda inginkan untuk sel tersebut, lalu kirimkan permintaan PUT
ke URL edit
dengan entri sel yang diperbarui sebagai isi permintaan. Misalnya, contoh berikut
memperbarui sel D2 (R2C4) agar berisi formula SUM
:
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
API v4
Pengeditan satu sel di Sheets API v4 dapat dilakukan dengan metode spreadsheets.values.update. Metode ini memerlukan parameter kueri ValueInputOption
, yang menentukan apakah data input diperlakukan seolah-olah dimasukkan ke dalam UI Spreadsheet (USER_ENTERED
), atau dibiarkan tidak diurai dan dianggap apa adanya (RAW
). Misalnya, berikut ini akan memperbarui sel D2 dengan formula:
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}
Jika Anda melakukan beberapa pengeditan sel, gunakan metode spreadsheets.values.batchUpdate untuk mengeluarkannya dalam satu permintaan.
Mengedit beberapa sel dengan permintaan batch
Kedua API menyediakan cara untuk membuat perubahan pada konten beberapa sel dengan satu permintaan (batch). Sel yang dirujuk oleh permintaan batch tidak harus berada dalam rentang yang bersambung.
Jika satu atau beberapa pengeditan sel dalam batch gagal, Sheets API v3 memungkinkan pengeditan lainnya agar berhasil. Namun, Sheets API v4 akan menampilkan error jika salah satu batch update yang gagal, dan tidak menerapkan update apa pun dalam kasus tersebut.
API v3
Untuk mengedit beberapa sel, pertama-tama ambil feed sel untuk lembar kerja tersebut. Entri tersebut berisi URL batch. Kirim permintaan POST
ke URL ini, bersama dengan isi permintaan yang menjelaskan sel yang
ingin diperbarui dan konten sel baru. Permintaan POST
dan isi permintaan
memiliki struktur yang mirip dengan berikut ini:
POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
<entry>
<batch:id>request1</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
<gs:cell row="2" col="4" inputValue="newData"/>
</entry>
...
<entry>
<batch:id>request2</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
<gs:cell row="5" col="2" inputValue="moreInfo"/>
</entry>
</feed>
Kolom batch:id
harus mengidentifikasi permintaan dalam batch secara unik.
Kolom batch:operation
harus berupa update
untuk pengeditan sel. gs:cell
mengidentifikasi sel menurut nomor baris dan kolom, serta memberikan data baru
untuk disisipkan di sana. id
berisi URL lengkap ke sel yang akan diperbarui.
link
harus memiliki atribut href
yang berisi jalur lengkap ke
ID sel. Semua kolom ini wajib diisi untuk setiap entri.
API v4
Sheets API v4 menyediakan pengeditan batch atas nilai-nilai sel melalui metode spreadsheets.values.batchUpdate.
Pengeditan beberapa sel dapat dilakukan dengan mengeluarkan permintaan POST
dengan
perubahan data yang ditentukan dalam isi permintaan. Contoh:
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{ "valueInputOption": "USER_ENTERED" "data": [ {"range": "D4", "majorDimension": "ROWS", "values": [["newData"]] }, {"range": "B5", "majorDimension": "ROWS", "values": [["moreInfo"]] } ] }
Jika Anda menentukan satu sel sebagai rentang, semua nilai yang diberikan akan ditulis ke sheet, dimulai dengan sel tersebut sebagai koordinat kiri atas. Jika Anda menentukan rentang multi-sel, nilai yang Anda berikan harus benar-benar pas dengan rentang tersebut. Jika tidak, API akan menampilkan error.