Fitur metadata developer memungkinkan Anda mengaitkan metadata dengan berbagai entity dan lokasi di spreadsheet. Selanjutnya, Anda dapat membuat kueri metadata ini dan menggunakannya untuk menemukan objek yang terkait.
Anda dapat mengaitkan metadata dengan baris, kolom, sheet, atau spreadsheet.
Metadata developer memungkinkan Anda melakukan operasi seperti:
Mengaitkan data arbitrer dengan berbagai entity dan lokasi dalam spreadsheet—Misalnya, kaitkan
totalsdengan kolom D, atauresponseId = 1234dengan baris 7.Menemukan semua lokasi dan data yang terkait dengan atribut atau kunci metadata tertentu—Misalnya, dengan kunci
totalsyang terkait dengan kolom D atau denganresponseId, tampilkan semua baris dengan metadataresponseIddan nilai metadata yang terkait dengannya.Menemukan semua data yang terkait dengan entity atau lokasi tertentu—Misalnya, kolom D tertentu, menampilkan semua metadata yang terkait dengan lokasi tersebut.
Ambil nilai di lokasi dengan menentukan metadata terkait. Misalnya, jika
totalsmenampilkan representasi nilai yang ada dalam kolom atau baris terkait, atau jikasummarymenampilkan representasi resource Sheet terkait.Memperbarui nilai di lokasi dengan menentukan metadata yang terkait—Misalnya, daripada memperbarui nilai dalam baris melalui notasi A1, perbarui nilai dengan menunjukkan ID metadata.
Membaca & menulis metadata
Resource spreadsheets.developerMetadata memberikan akses ke metadata developer yang terkait dengan lokasi atau objek dalam spreadsheet.
Tentang metadata developer
Bagian ini menjelaskan beberapa aspek utama metadata developer yang harus Anda pertimbangkan saat menggunakan Sheets API.
Metadata sebagai tag
Salah satu penggunaan metadata developer adalah tag yang menyebutkan lokasi di spreadsheet hanya menggunakan kunci dan lokasi. Misalnya, Anda dapat mengaitkan headerRow dengan baris tertentu atau totals dengan
kolom tertentu dalam sheet. Tag dapat digunakan untuk mengikat bagian-bagian dari
spreadsheet secara semantik ke kolom pada database atau alat pihak ketiga, sehingga perubahan pada
spreadsheet tidak akan menghentikan aplikasi Anda.
Metadata sebagai properti
Metadata yang dibuat dengan menentukan kunci, lokasi, dan nilai berfungsi sebagai pasangan nilai kunci yang terkait dengan lokasi tersebut dalam sheet. Misalnya, Anda dapat mengaitkan:
formResponseId = resp123dengan barislastUpdated = 1477369882dengan kolom.
Dengan begitu, Anda dapat menyimpan dan mengakses properti bernama kustom yang terkait dengan area atau data tertentu di spreadsheet.
Metadata project vs. dokumen yang terlihat
Untuk mencegah satu project developer mengganggu metadata orang lain, ada
2 setelan visibility metadata: project dan document. Dengan Sheets API,
metadata project hanya dapat dilihat dan diakses dari project developer yang
membuatnya. Metadata dokumen dapat diakses dari semua project developer yang memiliki akses ke dokumen tersebut.
Kueri yang tidak secara eksplisit menentukan visibilitas akan menampilkan metadata dokumen yang cocok dan metadata project yang cocok untuk project developer yang membuat permintaan.
Keunikan
Kunci metadata tidak harus unik, tetapi metadataId harus
berbeda. Jika Anda membuat metadata dan membiarkan kolom ID-nya tidak ditentukan, API akan menetapkannya. ID ini dapat digunakan untuk mengidentifikasi
metadata, sedangkan kunci dan atribut lainnya dapat digunakan untuk mengidentifikasi kumpulan
metadata.
Membuat metadata
Untuk membuat metadata, gunakan metode
batchUpdate, dan berikan
createDeveloperMetadataRequest dengan metadataKey, location, dan visibility. Secara opsional, Anda dapat menentukan metadataValue atau metadataId eksplisit.
Jika Anda menentukan ID yang sudah digunakan, permintaan tidak akan berhasil. Jika Anda tidak memberikan ID, API akan memberikan ID tersebut.
Tampilkan contoh
Dalam contoh ini, kami memberikan kunci, nilai, dan baris dalam permintaan. Respons menampilkan nilai metadata developer ini, ditambah ID metadata yang ditetapkan.
Permintaan
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}
Respons
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
}
}
]
}
Membaca satu item metadata
Untuk mengambil satu metadata developer yang berbeda, gunakan metode spreadsheets.developerMetadata.get, dengan menentukan spreadsheetId yang berisi metadata dan metadataId unik dari metadata developer.
Tampilkan contoh
Permintaan
Dalam contoh ini, kami memberikan ID spreadsheet dan ID metadata dalam permintaan. Respons akan menampilkan nilai metadata developer untuk ID metadata.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
Respons
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}
Membaca beberapa item metadata
Untuk mengambil beberapa item metadata developer, gunakan metode spreadsheets.developerMetadata.search. Anda harus menentukan DataFilter yang cocok dengan metadata yang ada pada kombinasi properti seperti kunci, nilai, lokasi, atau visibilitas.
Tampilkan contoh
Dalam contoh ini, kami memberikan beberapa ID metadata dalam permintaan. Respons tersebut menampilkan nilai metadata developer untuk setiap ID metadata.
Permintaan
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Respons
{
"matchedDeveloperMetadata": [
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Revenue",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
},
{
"developerMetadata": {
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}
Update metadata
Untuk memperbarui metadata developer, gunakan
metode spreadsheets.batchUpdate
dan berikan
UpdateDeveloperMetadataRequest.
Anda harus menentukan
DataFilter
yang menargetkan metadata yang akan diperbarui, objek
DeveloperMetadata
dengan nilai baru, dan mask kolom
yang menjelaskan kolom yang akan diperbarui.
Tampilkan contoh
Dalam contoh ini, kami menyediakan ID metadata, ID sheet, dan kunci metadata baru dalam permintaan. Respons menampilkan nilai metadata developer ini, ditambah kunci metadata yang diperbarui.
Permintaan
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}
Respons
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Menghapus metadata
Untuk menghapus metadata developer, gunakan metode
batchUpdate, dan berikan
DeleteDeveloperMetadataRequest.
Anda harus menentukan DataFilter untuk memilih metadata yang ingin dihapus.
Tampilkan contoh
Dalam contoh ini, kami memberikan ID metadata dalam permintaan. Respons akan menampilkan nilai metadata developer untuk ID metadata.
Untuk mengonfirmasi bahwa metadata developer telah dihapus, gunakan metode spreadsheets.developerMetadata.get, yang menentukan ID metadata yang dihapus. Anda akan menerima respons kode status HTTP 404: Not Found, dengan pesan yang menyatakan "Tidak ada metadata developer dengan ID metadataId.
Permintaan
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}
Respons
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}
Membaca & menulis nilai yang terkait dengan metadata
Anda juga dapat mengambil dan memperbarui nilai sel dalam baris dan kolom dengan menentukan metadata developer terkait dan nilai yang ingin diperbarui. Untuk melakukannya, gunakan metode yang sesuai di bawah ini dengan
DataFilter yang cocok.
Mendapatkan nilai sel berdasarkan metadata
Untuk mendapatkan nilai sel melalui metadata, gunakan metode spreadsheets.values.batchGetByDataFilter. Anda harus menentukan ID spreadsheet dan satu atau beberapa filter data yang cocok dengan metadata.
Tampilkan contoh
Dalam contoh ini, kami memberikan ID metadata dalam permintaan. Respons tersebut menampilkan nilai sel baris (nomor model, penjualan bulanan) untuk ID metadata.
Permintaan
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}
Respons
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}
Mendapatkan spreadsheet berdasarkan metadata
Saat mengambil spreadsheet, Anda dapat menampilkan subset data menggunakan metode spreadsheets.getByDataFilter. Anda harus menentukan ID spreadsheet dan satu atau beberapa filter data yang cocok dengan metadata.
Permintaan ini berfungsi sebagai permintaan "spreadsheet GET" reguler, tetapi
daftar metadata yang cocok dengan filter data yang ditentukan menentukan sheet,
data petak, dan resource objek lain dengan metadata yang ditampilkan. Jika
includeGridData ditetapkan ke benar (true), data petak yang berpotongan dengan rentang petak yang ditentukan juga akan ditampilkan untuk sheet tersebut.
Tampilkan contoh
Dalam contoh ini, kami memberikan ID metadata dan menetapkan includeGridData ke salah dalam permintaan. Respons akan menampilkan properti spreadsheet dan sheet.
Permintaan
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}
Respons
{
"spreadsheetId": spreadsheetId,
"properties": {
"title": "Sales Sheet",
"locale": "en_US",
"autoRecalc": "ON_CHANGE",
"timeZone": "America/Los_Angeles",
"defaultFormat": {
"backgroundColor": {
"red": 1,
"green": 1,
"blue": 1
},
"padding": {
"top": 2,
"right": 3,
"bottom": 2,
"left": 3
},
"verticalAlignment": "BOTTOM",
"wrapStrategy": "OVERFLOW_CELL",
"textFormat": {
"foregroundColor": {},
"fontFamily": "arial,sans,sans-serif",
"fontSize": 10,
"bold": false,
"italic": false,
"strikethrough": false,
"underline": false,
"foregroundColorStyle": {
"rgbColor": {}
}
},
"backgroundColorStyle": {
"rgbColor": {
"red": 1,
"green": 1,
"blue": 1
}
}
},
"spreadsheetTheme": {
"primaryFontFamily": "Arial",
"themeColors": [
{
"colorType": "TEXT",
"color": {
"rgbColor": {}
}
},
{
"colorType": "BACKGROUND",
"color": {
"rgbColor": {
"red": 1,
"green": 1,
"blue": 1
}
}
},
{
"colorType": "ACCENT1",
"color": {
"rgbColor": {
"red": 0.25882354,
"green": 0.52156866,
"blue": 0.95686275
}
}
},
{
"colorType": "ACCENT2",
"color": {
"rgbColor": {
"red": 0.91764706,
"green": 0.2627451,
"blue": 0.20784314
}
}
},
{
"colorType": "ACCENT3",
"color": {
"rgbColor": {
"red": 0.9843137,
"green": 0.7372549,
"blue": 0.015686275
}
}
},
{
"colorType": "ACCENT4",
"color": {
"rgbColor": {
"red": 0.20392157,
"green": 0.65882355,
"blue": 0.3254902
}
}
},
{
"colorType": "ACCENT5",
"color": {
"rgbColor": {
"red": 1,
"green": 0.42745098,
"blue": 0.003921569
}
}
},
{
"colorType": "ACCENT6",
"color": {
"rgbColor": {
"red": 0.27450982,
"green": 0.7411765,
"blue": 0.7764706
}
}
},
{
"colorType": "LINK",
"color": {
"rgbColor": {
"red": 0.06666667,
"green": 0.33333334,
"blue": 0.8
}
}
}
]
}
},
"sheets": [
{
"properties": {
"sheetId": sheetId,
"title": "Sheet7",
"index": 7,
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 26
}
}
}
],
"spreadsheetUrl": spreadsheetUrl
}
Memperbarui nilai berdasarkan metadata
Untuk mengupdate nilai sel yang cocok dengan metadata tertentu, gunakan metode spreadsheets.values.batchUpdateByDataFilter. Anda harus menentukan ID spreadsheet, valueInputOption, dan satu atau beberapa DataFilterValueRange yang cocok dengan metadata.
Tampilkan contoh
Dalam contoh ini, kami memberikan ID metadata dan nilai baris yang diperbarui dalam permintaan. Respons tersebut menampilkan properti dan data yang diperbarui untuk ID metadata.
Permintaan
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}
Respons
{
"spreadsheetId": spreadsheetId,
"totalUpdatedRows": 1,
"totalUpdatedColumns": 2,
"totalUpdatedCells": 2,
"totalUpdatedSheets": 1,
"responses": [
{
"updatedRange": "Sheet7!A7:B7",
"updatedRows": 1,
"updatedColumns": 2,
"updatedCells": 2,
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"updatedData": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
}
]
}
Menghapus nilai menurut metadata
Untuk menghapus nilai sel yang cocok dengan metadata tertentu, gunakan metode spreadsheets.values.batchClearByDataFilter. Anda harus menentukan filter data untuk memilih metadata yang ingin dihapus.
Tampilkan contoh
Permintaan
Dalam contoh ini, kami memberikan ID metadata dalam permintaan. Respons akan menampilkan ID spreadsheet dan rentang yang dihapus.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Respons
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}
Batas penyimpanan metadata
Ada batasan jumlah total {i>metadata<i} yang dapat Anda simpan di {i>spreadsheet<i}. Batas ini diukur dalam karakter dan terdiri dari 2 komponen:
| Item | Alokasi batas penyimpanan |
|---|---|
| Spreadsheet | 30.000 karakter |
| Setiap {i>sheet<i} di dalam {i>spreadsheet<i} | 30.000 karakter |
Anda dapat menyimpan hingga 30.000 karakter untuk spreadsheet. Selain itu, Anda dapat menyimpan 30.000 karakter untuk setiap sheet dalam spreadsheet (30.000 untuk sheet satu, 30.000 untuk sheet 2, dan seterusnya). Jadi sebuah {i>spreadsheet<i} dengan 3 halaman dapat berisi hingga 120.000 karakter {i>metadata<i} pengembang.
Setiap karakter dalam atribut kunci dan nilai objek developerMetadata
akan dihitung dalam batas ini.