Halaman ini diterjemahkan oleh Cloud Translation API.

Bermigrasi dari Sheets API v3

Jika Anda memiliki aplikasi yang berdasarkan pada Google Sheets API v3, Anda dapat melakukan migrasi ke Google Sheets API v4. Versi v4 ini berbasis JSON, memiliki antarmuka yang lebih mudah digunakan, dan menambahkan cukup banyak fungsi yang tidak mungkin dilakukan di versi v3.

Halaman ini menyediakan pemetaan antara perintah Sheets API v3 yang lama dan operasi padanannya di Sheets API v4. Pemetaan tersebut terutama berfokus pada kumpulan spreadsheets.values, yang menyediakan fungsi baca dan tulis sel secara langsung. Aspek lainnya, seperti penambahan sheet atau pembaruan properti sheet ditangani oleh kumpulan spreadsheet. Perhatikan bahwa struktur JSON v4 API tidak kompatibel-mundur dengan struktur XML yang digunakan di v3.

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

Notasi dan istilah

v3 API merujuk pada sheet dalam spreadsheet tertentu sebagai "worksheet". Ini sinonim dengan istilah "sheet" yang digunakan v4 API.

API ini sering kali mengharuskan Anda menentukan ID spreadsheet spreadsheet yang sedang Anda tangani. API ini 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, gantilah ID aktual di lokasi ini.

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

Izinkan permintaan

Saat aplikasi Anda dijalankan, aplikasi tersebut akan meminta pengguna untuk memberikan izin tertentu; cakupan yang Anda tetapkan di aplikasi akan menentukan izin mana yang diminta.

v3 API

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 set 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 sheet atau properti sheet pengguna. Gunakan cakupan spreadsheet, bukan cakupan Drive, jika aplikasi tidak memerlukan akses umum ke Drive.

Visibilitas

Di API versi lama, istilah visibilitas digunakan untuk merujuk pada ketersediaan spreadsheet tertentu.

v3 API

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 ditetapkan 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 dibuat menggunakan ID spreadsheet. Jika aplikasi tidak memiliki izin untuk mengakses spreadsheet yang ditentukan, error akan ditampilkan. Jika tidak, panggilan akan dilanjutkan.

Proyeksi

Istilah projection 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; sebaliknya, API ini memberi Anda kontrol yang lebih besar atas data yang ditampilkan.

v3 API

Hanya ada dua setelan proyeksi yang memungkinkan di Sheets API v3. Proyeksi full menampilkan semua informasi yang tersedia, sedangkan basic menampilkan subset data tetap yang lebih kecil (untuk feed worksheet, daftar, dan 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, API ini tidak menentukan subset tetap yang serupa dengan setelan visibilitas basic di Sheets API v3. Metode dalam koleksi spreadsheet membatasi jumlah data yang ditampilkannya 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

v3 API

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 secara opsional juga dapat menambahkan sheet, menetapkan spreadsheet dan properti sheet, serta menambahkan rentang bernama. Misalnya, kode berikut membuat spreadsheet baru dan memberinya nama "NewTitle":

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

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

Mencantumkan spreadsheet untuk pengguna yang diautentikasi

v3 API

Feed Sheets API v3 memungkinkan aplikasi mengambil daftar semua spreadsheet yang dapat diakses oleh pengguna yang diautentikasi. Endpoint feed spreadsheet adalah:

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

API v4

Sheets API v4 tidak menyediakan operasi spesifik ini. Sebaiknya migrasikan aplikasi Anda untuk menggunakan cakupan drive.file bersama dengan Google Picker untuk pemilihan spreadsheet.

Jika diperlukan, spreadsheet listingan 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 Drive API untuk mencantumkan semua spreadsheet pengguna memerlukan cakupan dibatasi.

Mengambil metadata sheet

Sheets API v3 menyediakan feed untuk mengakses metadata sheet yang dimuat dalam spreadsheet yang diberikan (data baris dan sel diakses melalui feed terpisah). Metadata ini menyertakan informasi seperti judul sheet dan informasi ukuran.

Metode spreadsheets.get Sheets API v4 menyediakan akses ke informasi ini, dan lainnya.

v3 API

Feed worksheet 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 serupa dengan ini, dengan setiap data sheet 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

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 di bagian 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.

v3 API

Sheets API v3 dapat menambahkan worksheet 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 propertinya opsional. Bukanlah tindakan yang tepat bila memberikan judul yang sudah digunakan untuk sheet.

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

{
  "requests": [{
      "addSheet": {
          "properties": {
            "title": "Expenses",
            "sheetType": "GRID",
            "gridProperties": {
              "rowCount": 50,
              "columnCount": 10
            }
          }
      }
  }],
}

Mengubah ukuran dan judul sheet

Sheets API v3 memungkinkan Anda mengupdate ukuran dan judul sheet; Sheets API v4 juga memperbolehkannya, tetapi bisa juga digunakan untuk mengupdate properti sheet lainnya. Perhatikan bahwa mengurangi ukuran sheet dapat menyebabkan data dalam sel yang dipangkas terhapus tanpa peringatan.

v3 API

Untuk mengubah judul atau ukuran worksheet, mulailah dengan mengambil feed worksheet dan menemukan entri worksheet yang diinginkan, yang berisi URL edit. Perbarui metadata worksheet 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 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 memperbarui semua properti, gunakan fields:"*" sebagai cara pintas untuk mencantumkan semuanya). Misalnya, kode berikut menentukan bahwa properti ukuran dan judul sheet harus diperbarui 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 bisa menghapus sheet dari spreadsheet yang diberikan.

v3 API

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

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

API v4

Untuk menghapus sheet, buat permintaan DeleteSheet dalam 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 per 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 header wajib tersebut ada di baris pertama sheet.

Sebaliknya, Sheets API v4 tidak menggunakan metode akses yang spesifik untuk suatu baris. Sebagai gantinya, data sel sheet diakses dengan mereferensikan rentang tertentu yang diperlukan menggunakan notasi A1. Rentang tersebut dapat berupa blok sel, seluruh baris, seluruh kolom, atau seluruh sheet. API juga dapat mengakses kumpulan sel yang terpisah-pisah.

v3 API

Untuk menentukan URL feed berbasis daftar bagi worksheet yang diberikan, ambil feed worksheet dan temukan URL feed daftar dalam entri worksheet 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 direferensikan oleh nama yang disediakan dalam baris header sheet (wajib). Misalnya, berikut 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

Urutan berdasar 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 di "Sheet1":

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

Respons terhadap permintaan ini memiliki struktur yang serupa dengan:

{
  "range": "Sheet1",
  "majorDimension": "ROWS",
  "values": [["Name", "Hours", "Items", "IPM"],
             ["Bingley", "10", "2", "0.0033"],
             ["Darcy", "14", "6", "0.0071"]]
}

Sel kosong di akhir 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 sulit; cukup proses array values yang ditampilkan dalam urutan terbalik. Urutan berdasar kolom tidak didukung untuk pembacaan, tetapi Anda dapat mengurutkan data di 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 di aplikasi Anda.

Menambahkan baris data baru

Anda dapat menambahkan baris data baru ke sheet menggunakan salah satu API.

v3 API

Untuk menentukan URL feed berbasis daftar bagi worksheet yang diberikan, ambil feed worksheet dan temukan URL postingan dalam entri worksheet 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 direferensikan 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 ditentukan.

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 di "Sheet1" 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 diupdate dengan nilai baru.

v3 API

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

Setelah entri diupdate, kirim permintaan PUT dengan entri tersebut sebagai isi permintaan ke URL edit yang disediakan di 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 dari baris yang ingin Anda edit 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 memilih untuk menetapkan rentang multi-sel, nilai yang Anda berikan harus sesuai 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 memperbarui data baris dari metode spreadsheet.values.batchUpdate; lebih efisien menggunakan metode ini jika Anda melakukan beberapa pembaruan baris atau sel.

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

Menghapus baris

Kedua API mendukung penghapusan baris. Baris yang dihapus akan dihapus dari spreadsheet, dan baris di bawahnya akan terdorong naik satu baris.

v3 API

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. Ini adalah URL yang sama dengan yang digunakan untuk mengupdate baris.

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

Jika Anda ingin memastikan bahwa Anda tidak menghapus baris yang telah diubah oleh klien lain sejak Anda mengambilnya, sertakan header If-Match HTTP yang berisi nilai ETag baris asli. Anda dapat menentukan nilai ETag baris asli dengan memeriksa atribut gd:etag elemen entri.

Jika Anda ingin menghapus baris, terlepas dari apakah orang lain telah mengupdatenya atau tidak 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 serta memilih untuk menghapus bagian baris atau kolom saja. Misalnya, kode berikut akan menghapus baris ke-6 dari 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 spreadsheet. Untuk akses baca, feed sel dapat menyediakan seluruh konten sheet atau rentang sel sheet yang ditentukan oleh kumpulan parameter kueri, tetapi hanya sebagai satu blok—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-pisah). Sheets API v3 hanya dapat menampilkan konten sel sebagai nilai input (seperti yang akan dimasukkan oleh pengguna di keyboard) dan/atau output formula (jika numerik); Sheets API v4 memberikan akses penuh ke nilai, formula, pemformatan, hyperlink, validasi data, dan properti lainnya.

v3 API

Untuk menentukan URL feed berbasis sel bagi worksheet yang diberikan, periksa feed worksheet dan temukan URL feed sel dalam entri worksheet 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 ditunjukkan menggunakan nomor baris dan kolom. Pengambilan satu rentang tertentu dapat dilakukan dengan menggunakan parameter kueri max-row, min-row, max-col, dan min-col. Misalnya, kode berikut akan mengambil semua sel di kolom 4 (D), mulai 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 antarmuka pengguna Google Spreadsheet untuk memanipulasi sel. inputValue dapat berupa nilai literal atau formula. API juga terkadang menampilkan numericValue; misalnya, saat formula menghasilkan angka. Misalnya, 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 rentang atau rentang yang diinginkan. Misalnya, kode berikut akan menampilkan sel di kolom D "Sheet2", mulai dari baris 2, dalam urutan kolom utama dan menampilkan formula seperti yang dimasukkan (sel kosong di akhir 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.

v3 API

Untuk mengedit konten sel tunggal, terlebih dahulu temukan entri sel dalam feed sel. Entri tersebut berisi URL edit. Update entri untuk mencerminkan konten yang Anda inginkan untuk sel tersebut, lalu keluarkan permintaan PUT ke URL edit dengan entri sel yang diupdate sebagai isi permintaan. Misalnya, kode 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 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 diuraikan dan diambil apa adanya (RAW). Misalnya, hal berikut 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 membuat beberapa pengeditan sel, gunakan metode spreadsheets.values.batchUpdate untuk mengeluarkannya dalam satu permintaan.

Mengedit beberapa sel sekaligus 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 ada satu atau beberapa pengeditan sel yang gagal dalam batch, Sheets API v3 memungkinkan pengeditan lainnya tetap berlanjut. Namun, Sheets API v4 akan menampilkan error jika ada update batch yang gagal, dan tidak akan menerapkan satu pun dari update itu.

v3 API

Untuk mengedit beberapa sel, terlebih dahulu ambil feed sel untuk worksheet. Entri tersebut berisi URL batch. Kirim permintaan POST ke URL ini, bersama isi permintaan yang menjelaskan sel yang ingin Anda perbarui dan konten sel baru. Permintaan POST dan isi permintaan memiliki struktur yang mirip dengan berikut:

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 menyediakan 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 sekaligus 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 memilih untuk menetapkan rentang multi-sel, nilai yang Anda berikan harus sesuai dengan rentang tersebut secara persis; jika tidak, API akan menampilkan error.