Halaman ini diterjemahkan oleh Cloud Translation API.

Bermigrasi dari Sheets API v3

Jika Anda memiliki aplikasi yang berbasis pada Google Sheets API v3, Anda dapat bermigrasi ke Google Sheets API v4. Versi v4 berbasis JSON, sehingga lebih mudah digunakan antarmuka pengguna, dan menambahkan fungsionalitas dalam jumlah besar yang tidak mungkin pada versi v3.

Halaman ini menyediakan pemetaan antara perintah Sheets API v3 lama dan yang setara di Sheets API v4. Pemetaan ini terutama berfokus pada spreadsheets.values pengumpulan data, yang menyediakan fungsi baca dan tulis sel secara langsung. Aspek lain, seperti penambahan {i>sheet<i} atau pembaruan properti {i>sheet<i} ditangani oleh koleksi spreadsheet. Perhatikan bahwa struktur JSON v4 API tidak kompatibel dengan versi sebelumnya Struktur XML yang digunakan dalam v3.

Untuk informasi selengkapnya tentang resource yang tersedia di Sheets v4 API, lihat Referensi API.

Notasi dan persyaratan

API v3 mengacu pada sheet dalam spreadsheet tertentu sebagai "worksheet". Ini identik dengan istilah "sheets" yang digunakan oleh API v4.

API ini sering kali mengharuskan Anda menentukan ID spreadsheet dari {i>spreadsheet <i}yang sedang Anda kerjakan. Mereka juga sering kali memerlukan ID dari {i>sheet<i} sedang dimanipulasi. Nilai ini muncul sebagai bagian dari endpoint API URL, sebagai parameter kueri, atau sebagai bagian dari isi permintaan. Pada halaman ini, placeholder spreadsheetId dan sheetId merujuk pada masing-masing ID {i>spreadsheet <i}dan {i>sheet<i}. Saat menggunakan metode yang dijelaskan di halaman ini, menggantikan ID aktual di lokasi ini.

API v3 juga menetapkan ID ke baris yang diambil menggunakan feed daftar; ini diwakili di halaman ini oleh placeholder rowId.

Izinkan permintaan

Saat berjalan, aplikasi akan meminta pengguna untuk memberikan izin tertentu; dalam cakupan yang Anda tentukan dalam aplikasi menentukan izin akses 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 tidak perlu mengedit {i>sheet<i} atau properti {i>sheet<i} pengguna. Gunakan cakupan {i>spreadsheet<i} daripada Cakupan Drive jika aplikasi tidak memerlukan akses umum Drive.

Visibilitas

Di versi lama API, istilah visibilitas digunakan untuk merujuk ketersediaan {i>spreadsheet <i}tertentu.

API v3

Sheets API v3 mengekspresikan visibilitas secara langsung di endpoint-nya. public spreadsheet 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 visibilitas yang eksplisit. Panggilan API dilakukan menggunakan ID spreadsheet. Jika aplikasi tidak memiliki izin akses untuk mengakses {i>spreadsheet <i}tertentu, maka akan muncul pesan {i>error<i}. Sebaliknya panggilan 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; melainkan, memungkinkan Anda lebih mengontrol data apa yang ditampilkan.

API v3

Hanya ada dua kemungkinan setelan proyeksi di Sheets API v3. full proyeksi menampilkan semua informasi yang tersedia, sedangkan basic menampilkan {i>subset<i} data yang lebih kecil dan tetap (untuk {i>worksheet<i}, daftar, dan {i>feed<i} 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 diberikan oleh proyeksi basic bermanfaat untuk membuat kode lebih efisien, tetapi tidak dapat disesuaikan.

API v4

Meskipun Sheets API v4 dapat menampilkan set data lengkap, ini tidak menentukan subset yang setara dengan setelan visibilitas basic di Sheets API v3. Metode di spreadsheet membatasi jumlah data yang dikembalikan melalui penggunaan parameter kueri fields.

Misalnya, kueri berikut hanya mengembalikan judul semua {i>sheet<i} di {i>spreadsheet <i}tertentu:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title

Buat spreadsheet

API v3

Sheets API v3 tidak menyediakan sarana untuk membuat spreadsheet baru; sebagai gantinya, file Drive API Files.create dapat digunakan untuk membuat file {i>spreadsheet <i}baru. Opsi ini memerlukan aplikasi untuk mendeklarasikan cakupan https://www.googleapis.com/auth/drive.

API v4

Metode Drive API Files.create dapat juga digunakan dengan Sheets API v4, tetapi aplikasi harus menyediakan cakupan https://www.googleapis.com/auth/drive.

Sebagai alternatif yang setara, Sheets API v4 menyediakan spreadsheets.create , yang juga dapat menambahkan {i>sheet<i}, mengatur {i>spreadsheet<i} dan {i>sheet<i} properti, dan menambahkan rentang bernama. Misalnya, perintah berikut membuat {i>spreadsheet<i} dan memberinya nama "NewTitle":

POST https://sheets.googleapis.com/v4/spreadsheets

{
 "properties": {"title": "NewTitle"}
}

Membuat daftar spreadsheet untuk pengguna terautentikasi

API v3

Feed Sheets API v3 memungkinkan aplikasi mengambil daftar semua {i>spreadsheet<i} yang dapat diakses oleh pengguna yang diotentikasi. Feed spreadsheet endpoint adalah:

GET https://spreadsheets.google.com/feeds/spreadsheets/private/full

API v4

Sheets API v4 tidak menyediakan operasi khusus ini. Saran dari kami memigrasikan aplikasi Anda untuk menggunakan cakupan drive.file yang dikombinasikan dengan Alat Pilih Google untuk pemilihan spreadsheet.

Dalam kasus ketika listingan spreadsheet diperlukan, fitur ini 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'

Menggunakan metode files.list API Drive untuk menampilkan daftar semua spreadsheet pengguna memerlukan cakupan yang dibatasi.

Mengambil metadata sheet

Sheets API v3 menyediakan feed untuk mengakses metadata sheet yang ada di dalam {i>spreadsheet<i} tertentu (data baris dan sel dapat diakses melalui feed terpisah). {i>Metadata<i} mencakup informasi seperti judul {i>sheet<i} dan informasi ukuran.

Sheets API v4 spreadsheets.get menyediakan akses ke informasi ini, dan banyak lagi.

API v3

Feed lembar kerja dapat diakses dari endpoint API ini (menggunakan {i>header<i} otorisasi yang sesuai):

GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full

Respons atas permintaan ini memiliki struktur yang mirip dengan ini, dengan data setiap sheet yang dimuat 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

Class spreadsheets.get dapat digunakan untuk memperoleh properti sheet dan metadata lainnya, lebih dari yang tersedia menggunakan Sheets API v3. Jika Anda hanya ingin membaca properti sheet, tetapkan kueri includeGridData parameter ke false untuk mencegah penyertaan data sel spreadsheet:

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false

Spreadsheet berisi array Sheet objek; judul dan informasi ukuran {i>sheet<i} secara khusus dapat ditemukan pada SheetProperties dari 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 ini memungkinkan Anda menambahkan sheet baru ke spreadsheet yang sudah ada.

API v3

Sheets API v3 dapat menambahkan lembar kerja baru ke spreadsheet dengan membuat mengikuti permintaan POST (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 {i>sheet<i} baru dengan membuat AddSheet permintaan di spreadsheets.batchUpdate . Sebagai bagian dari isi permintaan, Anda bisa menentukan properti sheet untuk {i>sheet<i} baru; semua properti bersifat opsional. Sebuah kesalahan jika Anda memberikan yang digunakan untuk {i>sheet<i} yang sudah 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 memungkinkan hal ini, tetapi juga dapat digunakan untuk memperbarui properti sheet lainnya. Perhatikan bahwa mengurangi ukuran lembar dapat menyebabkan data dalam sel yang dipangkas menjadi 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 kirim 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 updateSheetProperties permintaan di spreadsheets.batchUpdate . Isi permintaan POST harus berisi properti yang akan diubah, dan parameter fields harus secara eksplisit mencantumkan properti tersebut (jika ingin memperbarui semua properti, gunakan fields:"*" sebagai singkatan untuk mencantumkan semuanya). Sebagai contoh, kode berikut menetapkan bahwa judul dan ukuran {i>sheet<i} properti harus diperbarui untuk {i>sheet<i} 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 spreadsheet Metode spreadsheets.get.

Menghapus sheet

Kedua API dapat menghapus sheet dari spreadsheet tertentu.

API v3

Untuk menghapus lembar kerja, mulailah dengan mengambil feed lembar kerja, lalu kirim permintaan DELETE di URL edit entri lembar kerja target.

DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version

API v4

Untuk menghapus {i>sheet<i}, buatlah DeleteSheet permintaan di spreadsheets.batchUpdate . Isi permintaan POST hanya boleh berisi sheetId untuk {i>sheet<i} yang akan dihapus. Contoh:

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate

{
  "requests": [
    {
      "deleteSheet": {
        "sheetId": sheetId
      }
    }
  ],
}

Untuk mengambil sheetId sheet individual, gunakan spreadsheet spreadsheets.get .

Mengambil data baris

Feed baris daftar adalah salah satu dari dua metode yang disediakan Sheets API v3 untuk mengakses data dalam sel spreadsheet (yang lainnya adalah feed sel). Tujuan feed baris ditujukan untuk mendukung operasi {i>spreadsheet<i} umum (membaca baris per baris, menambahkan baris, menyortir), tetapi membuat asumsi tertentu yang membuatnya tidak cocok untuk beberapa tugas. Secara khusus, feed daftar mengasumsikan bahwa baris kosong adalah feed penghentian, dan bahwa {i>header<i} wajib ada di baris pertama {i>sheet<i}.

Sebaliknya, Sheets API v4 tidak menggunakan metode akses yang spesifik per baris. Sebagai gantinya, data sel {i>sheet<i} diakses dengan mengacu pada rentang yang diperlukan menggunakan notasi A1. Tujuan rentang dapat berupa blok sel, seluruh baris, seluruh kolom, atau seluruh sheet. API juga dapat mengakses kumpulan sel yang terpisah.

API v3

Untuk menentukan URL feed berbasis daftar untuk lembar kerja tertentu, ambil feed lembar kerja dan temukan URL feed daftar di entri lembar kerja yang diinginkan.

Untuk mengambil feed berbasis daftar, kirim permintaan GET ke URL feed daftar, menggunakan {i>header<i} otorisasi yang sesuai. Contoh:

GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

Respons terhadap permintaan ini berisi, antara lain, entri sesuai dengan baris tertentu. Masing-masing sel direferensikan oleh nama-nama yang diberikan di baris {i>header <i}sheet (wajib). Misalnya, di sini merupakan 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.

Balik urutan:

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 struktur kueri (direferensikan oleh tajuk 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 menurut rentang menggunakan spreadsheets.values.get atau spreadsheets.values.batchGet metode. Misalnya, kode berikut menampilkan semua baris di "Sheet1":

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1

Respons atas 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 {i>sheet<i}.

Sheets API v4 tidak memiliki padanan untuk kueri urutan baris yang disediakan oleh Sheets API v3. Urutan terbalik itu mudah; sederhana memproses array values yang ditampilkan dalam urutan terbalik. Urutkan menurut kolom tidak didukung untuk pembacaan, tetapi ada kemungkinan untuk mengurutkan data dalam sheet (menggunakan SortRange permintaan, 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 di entri lembar kerja yang diinginkan.

Untuk menambahkan baris data, kirim permintaan POST ke URL postingan, menggunakan {i>header<i} otorisasi yang sesuai. Contoh:

POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full

Isi permintaan POST harus berisi entri untuk data baris untuk {i>add<i}, dengan sel individu yang dirujuk oleh {i>header <i}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 ditentukan.

API v4

Dengan Sheets API v4, Anda bisa menambahkan baris menggunakan spreadsheets.values.append . Contoh berikut menulis baris data baru di bawah baris terakhir tabel di "Sheet1" dari {i>spreadsheet<i}.

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1

{
   "values": [["Elizabeth", "2", "0.5", "60"]]
}

Selain itu, Sheets API v4 juga memungkinkan Anda properti dan pemformatan menggunakan atribut AppendCells permintaan di spreadsheets.batchUpdate.

Mengedit baris dengan data baru

Kedua API memungkinkan data baris diupdate dengan nilai baru.

API v3

Untuk mengedit baris data, periksa feed daftar untuk menemukan entri untuk baris yang ingin Anda perbarui. Perbarui konten entri itu sesuai kebutuhan. Pastikan nilai ID dalam entri yang Anda gunakan sama persis cocok dengan ID entri yang ada.

Setelah entri diperbarui, kirim permintaan PUT dengan entri sebagai ke URL edit yang diberikan dalam entri baris tersebut, menggunakan {i>header<i} 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 untuk baris yang ingin Anda mengedit dan menerbitkan spreadsheets.values.update untuk menimpa baris tersebut. Rentang yang ditentukan hanya perlu mengacu pada sel pertama di baris; API menyimpulkan sel-sel yang akan diupdate berdasarkan nilai yang disediakan bersama permintaan. Jika Anda menentukan rentang multi-sel, nilai yang Anda berikan harus muat dalam rentang itu; jika tidak, API akan menampilkan {i>error<i}.

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 memperbarui data baris dari spreadsheet.values.batchUpdate metode; akan lebih efisien menggunakan metode ini jika Anda membuat beberapa baris atau sel secara {i>update<i}.

Selain itu, Sheets API v4 juga memungkinkan Anda mengedit properti sel dan pemformatan sel menggunakan UpdateCells atau RepeatCell permintaan di spreadsheets.batchUpdate.

Menghapus baris

Kedua API mendukung penghapusan baris. Baris yang dihapus akan dibuang dari {i>spreadsheet<i}, dan baris di bawahnya terdorong ke atas menjadi satu.

API v3

Untuk menghapus baris, pertama-tama ambil baris yang akan dihapus dari feed daftar, lalu kirim permintaan DELETE ke URL edit yang disediakan dalam entri baris. URL ini 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 karena Anda mengambilnya, sertakan header HTTP If-Match yang berisi nilai ETag baris asli. Anda dapat menentukan nilai ETag baris dengan memeriksa atribut gd:etag elemen entri.

Jika Anda ingin menghapus baris, terlepas dari apakah orang lain sudah memperbarui baris sejak Anda mengambilnya, maka gunakan If-Match: * dan jangan sertakan ETag. (Dalam hal ini, Anda tidak perlu mengambil baris sebelum menghapusnya.)

API v4

Penghapusan baris dengan Sheets API v4 ditangani oleh spreadsheet.batchUpdate panggilan metode, menggunakan DeleteDimension permintaan. Permintaan ini juga dapat digunakan untuk menghapus kolom, dan untuk dan memilih untuk menghapus hanya sebagian baris atau kolom. Misalnya, berikut menghapus baris ke-6 dari suatu sheet dengan 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 di pada {i>spreadsheet<i}. Untuk akses baca, feed sel dapat menyediakan seluruh sheet konten atau rentang sel {i>sheet<i} 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 bisa mengambil kumpulan data sel apa pun dari sebuah sheet (termasuk beberapa rentang terpisah). Sheets API v3 hanya dapat menampilkan konten sel sebagai nilai input (seperti yang akan dimasukkan oleh pengguna di {i>keyboard<i}) dan/atau {i>output<i} dari 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 untuk lembar kerja tertentu, periksa metode 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 {i>header<i} otorisasi yang sesuai. Contoh:

GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full

Sel dirujuk menggunakan nomor baris dan kolom. Mengambil satu token spesifik rentang dapat dilakukan dengan menggunakan max-row, min-row, max-col, dan min-col parameter kueri. Misalnya, yang berikut ini mengambil semua sel dalam 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 dari sel yang diambil— nilai yang akan diketik pengguna ke dalam akun pengguna Google Sheets untuk memanipulasi sel. inputValue dapat berupa nilai literal atau formula. API juga terkadang menampilkan numericValue; misalnya, ketika formula menghasilkan angka. Misalnya, respons dapat menyertakan sel entri yang strukturnya mirip dengan 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 spreadsheets.values.get atau spreadsheets.values.batchGet masing-masing untuk rentang atau rentang minat. Misalnya, berikut mengembalikan sel-sel di kolom D dari "Sheet2", dimulai dengan baris 2, dalam urutan kolom utama dan menampilkan formula seperti yang dimasukkan (terakhir kosong sel dihilangkan):

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA

Respons atas 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 untuk menggunakan spreadsheet.values.batchGet jika Anda ingin mengambil beberapa rentang data sel. Jika Anda ingin mengakses properti sel seperti pemformatan, spreadsheet.get metode apa pun yang diperlukan.

Mengedit sel

Sheets API v3 memungkinkan Anda mengedit konten sel dengan mengeluarkan perintah PUT untuk feed sel dengan entri sel yang dimodifikasi sebagai isi permintaan.

Sebaliknya, Sheets API v4 menyediakan spreadsheets.values.update dan spreadsheets.values.batchUpdate metode untuk mengubah isi sel.

API v3

Untuk mengedit isi sel tunggal, temukan entri sel terlebih dahulu pada feed sel. Entri berisi URL edit. Perbarui entri untuk mencerminkan kontennya yang Anda inginkan untuk sel, lalu kirim permintaan PUT ke URL edit dengan entri sel yang diperbarui sebagai isi permintaan. Misalnya, berikut akan 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 sel tunggal di Sheets API v4 dapat dilakukan dengan 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 digunakan sebagaimana adanya (RAW). Sebagai contoh 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 spreadsheets.values.batchUpdate untuk menerbitkannya dalam satu permintaan.

Mengedit beberapa sel dengan permintaan batch

Kedua API ini menyediakan cara untuk membuat perubahan pada konten di beberapa sel dengan satu permintaan (batch). Sel-sel yang dirujuk oleh permintaan {i>batch <i}adalah tidak harus berada dalam rentang yang berdekatan.

Jika satu atau beberapa pengeditan sel gagal dalam batch, Sheets API v3 memungkinkan pengeditan lainnya berhasil. Namun, Sheets API v4 menampilkan error jika ada update batch yang gagal, dan tidak menerapkan satu pun dari update tersebut.

API v3

Untuk mengedit beberapa sel, ambil feed sel terlebih dahulu di lembar kerja tersebut. Entri berisi URL batch. Kirim POST ke URL ini, bersama dengan isi permintaan yang menjelaskan sel yang yang ingin diperbarui dan isi sel baru. Isi permintaan dan isi permintaan POST 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 secara unik dalam batch. Kolom batch:operation harus 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 sel melalui 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 ditulis ke {i>sheet<i} dimulai dengan sel tersebut sebagai koordinat kiri atas. Jika Anda menentukan rentang multi-sel, nilai yang Anda berikan harus sesuai rentang itu secara persis; jika tidak, API akan menampilkan error.