Membaca & menulis metadata developer

Fitur metadata developer memungkinkan Anda mengaitkan metadata dengan berbagai entity dan lokasi dalam spreadsheet. Kemudian, Anda dapat membuat kueri metadata ini dan menggunakannya untuk menemukan objek yang terkait dengannya.

Anda dapat mengaitkan metadata dengan baris, kolom, sheet, atau spreadsheet.

Metadata developer memungkinkan Anda melakukan operasi seperti:

  • Mengaitkan data arbitrer dengan berbagai entitas dan lokasi dalam spreadsheet—Misalnya, mengaitkan totals dengan kolom D, atau responseId = 1234 dengan baris 7.

  • Temukan semua lokasi dan data yang terkait dengan kunci atau atribut metadata tertentu—Misalnya, jika diberi kunci totals yang terkait dengan kolom D atau diberi responseId, kembalikan semua baris dengan metadata responseId dan nilai metadata yang terkait dengannya.

  • Temukan semua data yang terkait dengan entitas atau lokasi tertentu—Misalnya, dengan kolom D, tampilkan semua metadata yang terkait dengan lokasi tersebut.

  • Mengambil nilai di lokasi dengan menentukan metadata terkait—Misalnya, jika diberi totals, menampilkan representasi nilai yang ada dalam kolom atau baris terkait atau jika diberi summary, menampilkan representasi resource Spreadsheet terkait.

  • Perbarui nilai di lokasi dengan menentukan metadata 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 penting metadata developer yang harus Anda pertimbangkan saat menggunakan Sheets API.

Metadata sebagai tag

Salah satu penggunaan metadata developer adalah tag yang memberi nama lokasi dalam 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 spreadsheet secara semantik ke kolom dalam alat atau database pihak ketiga, sehingga perubahan pada spreadsheet tidak akan merusak 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 = resp123 dengan baris
  • lastUpdated = 1477369882 dengan kolom.

Dengan ini, Anda dapat menyimpan dan mengakses properti bernama kustom yang terkait dengan area atau data tertentu dalam spreadsheet.

Metadata yang terlihat di project vs. dokumen

Untuk mencegah satu project developer mengganggu metadata project developer lain, ada 2 setelan metadata visibility: project dan document. Dengan menggunakan Sheets API, metadata project hanya dapat dilihat dan diakses dari project developer yang membuatnya. Metadata dokumen dapat diakses dari project developer mana pun yang memiliki akses ke dokumen.

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, sementara 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. Anda dapat secara opsional menentukan metadataValue atau metadataId eksplisit.

Jika Anda menentukan ID yang sudah digunakan, permintaan tidak akan berhasil. Jika Anda tidak memberikan ID, API akan menetapkannya.

Dalam contoh ini, kita memberikan kunci, nilai, dan baris dalam permintaan. Respons menampilkan nilai metadata developer ini, beserta 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 metadata developer.

Permintaan

Dalam contoh ini, kita memberikan ID spreadsheet dan ID metadata dalam permintaan. Respons 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 apa pun seperti kunci, nilai, lokasi, atau visibilitas.

Dalam contoh ini, kita memberikan beberapa ID metadata dalam permintaan. Respons 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 masker kolom yang menjelaskan kolom yang akan diperbarui.

Dalam contoh ini, kita memberikan ID metadata, ID sheet, dan kunci metadata baru dalam permintaan. Respons menampilkan nilai metadata developer ini, beserta 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 Anda hapus.

Dalam contoh ini, kami memberikan ID metadata dalam permintaan. Respons menampilkan nilai metadata developer untuk ID metadata.

Untuk mengonfirmasi bahwa metadata developer telah dihapus, gunakan metode spreadsheets.developerMetadata.get, dengan 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 Anda perbarui. Untuk melakukannya, gunakan metode yang sesuai di bawah dengan DataFilter yang cocok.

Mendapatkan nilai sel menurut metadata

Untuk mendapatkan nilai sel menurut metadata, gunakan metode spreadsheets.values.batchGetByDataFilter. Anda harus menentukan ID spreadsheet dan satu atau beberapa filter data yang cocok dengan metadata.

Dalam contoh ini, kami memberikan ID metadata dalam permintaan. Respons 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, kecuali daftar metadata yang cocok dengan filter data yang ditentukan menentukan sheet, data petak, dan resource objek lainnya dengan metadata yang ditampilkan. Jika includeGridData disetel ke benar (true), data petak yang berpotongan dengan rentang petak yang ditentukan juga ditampilkan untuk sheet.

Dalam contoh ini, kita memberikan ID metadata dan menetapkan includeGridData ke false dalam permintaan. Respons 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 menurut metadata

Untuk memperbarui 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.

Dalam contoh ini, kita memberikan ID metadata dan nilai baris yang diperbarui dalam permintaan. Respons 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.

Permintaan

Dalam contoh ini, kami memberikan ID metadata dalam permintaan. Respons 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 metadata yang dapat Anda simpan dalam spreadsheet. Batas ini diukur dalam karakter dan terdiri dari 2 komponen:

Item Alokasi batas penyimpanan
Spreadsheet 30.000 karakter
Setiap sheet dalam spreadsheet 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,spreadsheet dengan 3 halaman dapat berisi hingga 120.000 karakter metadata developer.

Setiap karakter dalam atribut kunci dan nilai objek developerMetadata dihitung dalam batas ini.