Penulisan dasar

Google Sheets API memungkinkan Anda menulis nilai dan formula ke sel, rentang, rangkaian rentang, dan seluruh sheet. Contoh pada halaman ini mengilustrasikan cara beberapa operasi tulis umum dapat dilakukan dengan resource spreadsheets.values Sheets API.

Perhatikan bahwa Anda juga dapat menulis nilai sel menggunakan metode spreadsheet.batchUpdate, yang dapat berguna jika Anda ingin memperbarui pemformatan sel secara bersamaan atau properti lain yang tidak terpengaruh oleh resource spreadsheets.values. Misalnya, jika Anda ingin menyalin rentang sel dari satu sheet ke sheet lain sekaligus menimpa formula sel dan format sel, Anda dapat menggunakan metode UpdateCellsRequest dengan spreadsheet.batchUpdate.

Namun, untuk penulisan nilai sederhana, lebih mudah menggunakan metode spreadsheets.values.update atau metode spreadsheets.values.batchUpdate.

Contoh-contoh ini disajikan dalam bentuk permintaan HTTP dengan bahasa yang netral. Untuk mempelajari cara menerapkan operasi tulis dalam berbagai bahasa menggunakan library klien Google API, lihat Membaca & menulis nilai sel.

Dalam contoh ini, placeholder SPREADSHEET_ID menunjukkan tempat Anda akan memberikan ID spreadsheet, yang dapat ditemukan dari URL spreadsheet. Rentang yang akan ditulis ditentukan menggunakan notasi A1. Contoh rentang adalah Sheet1!A1:D5.

Menulis satu rentang

Mulai dengan spreadsheet kosong baru, contoh kode spreadsheets.values.update berikut menunjukkan cara menulis nilai ke rentang. Parameter kueri ValueInputOption diperlukan dan menentukan apakah nilai yang ditulis diurai (misalnya, apakah string dikonversi menjadi tanggal atau tidak).

Isi permintaan adalah objek ValueRange yang menjelaskan nilai rentang yang akan ditulis. Kolom majorDimension menunjukkan bahwa array adalah daftar nilai yang diatur menurut baris. Nilai yang ada dalam rentang target akan ditimpa.

Protokol permintaan ditampilkan di bawah ini.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

Respons terdiri dari objek UpdateValuesResponse, seperti yang satu ini:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

Sheet yang dihasilkan akan terlihat seperti berikut:

	A	B	C	D
1	Item	Biaya	Tersedia	Tanggal Pengiriman
2	Wheel	$20,50	4	3/1/2016
3	Pintu	$15	2	15/3/2016
4	Mesin	$100	1	20/3/2016
5	Total	$135,5	7	20/3/2016

Menulis secara selektif ke sebuah rentang

Saat menulis nilai ke suatu rentang, perubahan ke beberapa sel yang ada dapat dihindari dengan menetapkan elemen array yang sesuai ke null. Anda juga dapat menghapus sel dengan menulis string kosong ("") ke sel tersebut.

Mulai dengan sheet yang berisi data yang sama yang dihasilkan oleh contoh di atas, contoh kode spreadsheets.values.update berikut menunjukkan cara menulis nilai ke rentang B1:D4, secara selektif meninggalkan beberapa sel tidak berubah dan menghapus sel lainnya. Parameter kueri ValueInputOption diperlukan dan menentukan apakah nilai yang ditulis diurai (misalnya, apakah string dikonversi menjadi tanggal atau tidak).

Isi permintaan adalah objek ValueRange yang menjelaskan nilai rentang yang akan ditulis. Kolom majorDimension menunjukkan bahwa array adalah daftar nilai yang diatur menurut kolom.

Protokol permintaan ditampilkan di bawah ini.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

Kolom values di sini mencantumkan perubahan yang dibuat pada setiap kolom dalam rentang. Array pertama menunjukkan bahwa B1 akan dibiarkan tidak berubah (karena elemen array null), sedangkan B4 akan dihapus (string kosong). Nilai B2 dan B3 diupdate. Array ketiga melakukan operasi yang sama pada kolom D, sedangkan array kosong kedua menunjukkan bahwa kolom C akan dibiarkan tidak berubah.

Respons terdiri dari objek UpdateValuesResponse seperti yang satu ini:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

Sheet yang dihasilkan akan terlihat seperti berikut:

	A	B	C	D
1	Item	Biaya	Tersedia	Tanggal Pengiriman
2	Wheel	$1,00	4	4/1/2016
3	Pintu	$2	2	15/4/2016
4	Mesin		1
5	Total	$3,00	7	15/4/2016

Perhatikan bahwa baris "Totals", meskipun tidak langsung diubah oleh permintaan ini, akan berubah karena selnya berisi formula yang bergantung pada sel yang diubah.

Menulis ke beberapa rentang

Mulai dengan sheet kosong, contoh kode spreadsheets.values.batchUpdate berikut menunjukkan cara menulis nilai ke rentang Sheet1!A1:A4 dan Sheet1!B1:D2. Nilai yang ada dalam rentang target akan ditimpa. Isi permintaan terdiri dari objek ValueInputOption yang menunjukkan cara menafsirkan data input dan array objek ValueRange yang sesuai dengan setiap rentang yang ditulis. Kolom majorDimension menentukan apakah array yang disertakan ditafsirkan sebagai array kolom atau baris.

Protokol permintaan ditampilkan di bawah ini.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

Respons terdiri dari objek yang mencantumkan statistik sel yang diperbarui dan array objek UpdateValuesResponse, satu untuk setiap rentang yang diperbarui. Contoh:

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

Sheet yang dihasilkan akan terlihat seperti berikut:

	A	B	C	D
1	Item	Biaya	Tersedia	Tanggal Pengiriman
2	Wheel	$20,50	4	3/1/2016
3	Pintu
4	Mesin
5

Menulis nilai tanpa mengurai

Mulai dengan sheet kosong, contoh kode spreadsheets.values.update berikut menunjukkan cara menulis nilai ke rentang Sheet1!A1:E1, tetapi menggunakan parameter kueri RAW ValueInputOption untuk mencegah string yang ditulis diuraikan sebagai formula, boolean, atau angka. Nilai ini muncul sebagai string dan perataan teks dijustifikasi dalam sheet.

Isi permintaan adalah objek ValueRange yang menjelaskan nilai rentang yang akan ditulis. Kolom majorDimension menunjukkan bahwa array adalah daftar nilai yang diatur menurut baris. Nilai yang ada dalam rentang target akan ditimpa.

Protokol permintaan ditampilkan di bawah ini.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

Respons terdiri dari objek UpdateValuesResponse seperti yang satu ini:

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

Sheet yang dihasilkan akan terlihat seperti berikut:

	A	B	C	D	E
1	Data	123,45	TRUE	=MAX(D2:D4)	10
2

Perhatikan bahwa "BENAR" di tengah dan merupakan nilai boolean, sedangkan "123,45" diratakan ke kanan karena berupa angka, dan "10" diratakan ke kiri karena berupa string. Formula tidak diuraikan, dan juga muncul sebagai string.

Menambahkan nilai

Mulai dengan sheet seperti tabel di bawah ini:

	A	B	C	D
1	Item	Biaya	Tersedia	Tanggal Pengiriman
2	Wheel	$20,50	4	3/1/2016
3

Contoh kode spreadsheets.values.append berikut menunjukkan cara menambahkan dua baris nilai baru yang dimulai dengan baris 3. Parameter kueri ValueInputOption diperlukan dan menentukan apakah nilai yang ditulis diurai (misalnya, apakah string dikonversi menjadi tanggal atau tidak).

Isi permintaan adalah objek ValueRange yang menjelaskan nilai rentang yang akan ditulis. Kolom majorDimension menunjukkan bahwa array adalah daftar nilai yang diatur menurut baris.

Protokol permintaan ditampilkan di bawah ini.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

Respons terdiri dari objek AppendValuesResponse seperti yang satu ini:

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

Sheet yang dihasilkan akan terlihat seperti berikut:

	A	B	C	D
1	Item	Biaya	Tersedia	Tanggal Pengiriman
2	Wheel	$20,50	4	3/1/2016
3	Pintu	$15	2	15/3/2016
4	Mesin	$100	1	20/3/2016
5