Membaca, menulis, dan menelusuri metadata

Fitur metadata memungkinkan Anda mengaitkan metadata dengan berbagai entitas dan lokasi dalam spreadsheet. Anda kemudian dapat mengkueri metadata ini dan menggunakannya untuk menemukan objek yang terkait dengannya.

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

Tentang metadata

Berikut ini dijelaskan beberapa aspek utama metadata 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 bertindak sebagai key-value pair 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 versus dokumen: Untuk mencegah satu developer project mengganggu metadata project developer lainnya, ada dua setelan metadata visibility: project dan document. Dengan menggunakan Sheets API, metadata project hanya terlihat dan dapat diakses dari project Google Cloud yang membuatnya. Metadata document dapat diakses dari project Google Cloud mana pun yang memiliki akses ke dokumen.

Kueri yang tidak secara eksplisit menentukan visibility akan menampilkan metadata document yang cocok dan metadata project yang cocok untuk project Google Cloud yang membuat permintaan.

Jangan gunakan metadata developer yang terlihat di project sebagai mekanisme keamanan atau untuk menyimpan rahasia. Metadata mungkin diekspos kepada pengguna yang memiliki akses lihat-saja ke dokumen.
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.

Meskipun Anda dapat menentukan `metadataId` sendiri saat membuat metadata, sebaiknya izinkan Sheets API menetapkannya untuk Anda.
Menampilkan metadata melalui permintaan API: Objek DataFilter adalah bagian dari panggilan API yang menjelaskan data yang akan dipilih atau ditampilkan dari permintaan API.

Satu objek DataFilter hanya dapat menentukan satu jenis kriteria filter untuk menemukan data:
- developerMetadataLookup: Memilih data yang terkait dengan metadata developer yang ditentukan yang cocok dengan kriteria.
- a1Range: Memilih data yang cocok dengan rentang notasi A1 yang ditentukan. Misalnya, Sheet1!A1:B10.
- gridRange: Memilih data yang cocok dengan rentang petak yang ditentukan menggunakan indeks berbasis nol. Misalnya, Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2.
Untuk memfilter di beberapa lokasi atau kriteria, Anda dapat menggunakan beberapa DataFilter objek dalam satu permintaan API. Berikan array atau daftar objek DataFilter ke permintaan batch seperti spreadsheets.values.batchGetByDataFilter metode. Rentang apa pun yang cocok dengan salah satu filter data dalam permintaan akan ditampilkan atau diubah.

Untuk mengetahui informasi selengkapnya, lihat Membaca dan menulis nilai yang terkait dengan metadata.

Kasus penggunaan

Berikut adalah beberapa contoh kasus penggunaan untuk mengelola metadata:

Mengaitkan data arbitrer dengan berbagai entitas dan lokasi dalam spreadsheet: Misalnya, mengaitkan totals dengan kolom D, atau responseId = 1234 dengan baris 7.
Menemukan semua lokasi dan data yang terkait dengan kunci atau atribut metadata tertentu: Misalnya, dengan kunci totals yang terkait dengan kolom D atau dengan responseId, tampilkan semua baris dengan metadata responseId dan nilai metadata yang terkait dengannya.
Menemukan 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, dengan totals, tampilkan representasi nilai yang terdapat dalam kolom atau baris terkait atau dengan summary, tampilkan representasi resource Sheet terkait.
Memperbarui nilai di lokasi dengan menentukan metadata terkait: Misalnya, alih-alih memperbarui nilai dalam baris melalui notasi A1, perbarui nilai dengan menunjukkan ID metadata.

Membaca dan menulis metadata

Resource spreadsheets.developerMetadata memberikan akses ke metadata yang terkait dengan lokasi atau objek dalam spreadsheet. Metadata developer dapat digunakan untuk mengaitkan data arbitrer dengan berbagai bagian spreadsheet. Metadata tetap terkait di lokasi tersebut saat spreadsheet diedit.

Membuat metadata

Untuk membuat metadata, gunakan batchUpdate metode pada spreadsheets resource, dan berikan CreateDeveloperMetadataRequest dengan metadataKey, location, dan visibility nilai dari spreadsheets.developerMetadata resource. Anda dapat secara opsional menentukan metadataValue atau metadataId eksplisit.

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

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": SHEET_ID,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT",
          "metadataKey": "Sales",
          "metadataValue": "2022"
        }
      }
    }
  ]
}

Respons

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "createDeveloperMetadata": {
        "developerMetadata": {
          "metadataId": METADATA_ID,
          "metadataKey": "Sales",
          "metadataValue": "2022",
          "location": {
            "locationType": "ROW",
            "dimensionRange": {
              "sheetId": SHEET_ID,
              "dimension": "ROWS",
              "startIndex": 6,
              "endIndex": 7
            }
          },
          "visibility": "DOCUMENT"
        }
      }
    }
  ]
}

Membaca satu item metadata

Untuk mengambil satu metadata developer yang berbeda, gunakan spreadsheets.developerMetadata.get metode, dengan menentukan spreadsheetId yang berisi metadata dan developer metadata unik metadataId.

Permintaan

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

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/developerMetadata/METADATA_ID

Respons

{
  "metadataId": METADATA_ID,
  "metadataKey": "Sales",
  "metadataValue": "2022",
  "location": {
    "locationType": "ROW",
    "dimensionRange": {
      "sheetId": SHEET_ID,
      "dimension": "ROWS",
      "startIndex": 6,
      "endIndex": 7
    }
  },
  "visibility": "DOCUMENT"
}

Membaca beberapa item metadata

Untuk mengambil beberapa item metadata developer, gunakan spreadsheets.developerMetadata.search metode. Anda harus menentukan DataFilter yang cocok dengan metadata yang ada pada kombinasi properti apa pun seperti kunci, nilai, lokasi, atau visibilitas.

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

Permintaan

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    },
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ]
}

Respons

{
  "matchedDeveloperMetadata": [
    {
      "developerMetadata": {
        "metadataId": METADATA_ID,
        "metadataKey": "Revenue",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": SHEET_ID
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    },
    {
      "developerMetadata": {
        "metadataId": METADATA_ID,
        "metadataKey": "Sales",
        "metadataValue": "2022",
        "location": {
          "locationType": "SHEET",
          "sheetId": SHEET_ID
        },
        "visibility": "DOCUMENT"
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    }
  ]
}

Memperbarui metadata

Untuk memperbarui metadata developer, gunakan metode spreadsheets.batchUpdate dan berikan UpdateDeveloperMetadataRequest. Anda harus menentukan DataFilter yang menargetkan metadata yang akan diperbarui, resource spreadsheets.developerMetadata dengan nilai baru, dan mask kolom yang menjelaskan kolom yang akan diperbarui.

Dalam contoh ini, kami memberikan 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": METADATA_ID
            }
          }
        ],
        "developerMetadata": {
          "location": {
            "sheetId": SHEET_ID
          },
          "metadataKey": "SalesUpdated"
        },
        "fields": "location,metadataKey"
      }
    }
  ]
}

Respons

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "updateDeveloperMetadata": {
        "developerMetadata": [
          {
            "metadataId": METADATA_ID,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": SHEET_ID
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

Menghapus metadata

Untuk menghapus metadata developer, gunakan batchUpdate metode, dan berikan DeleteDeveloperMetadataRequest. Anda harus menentukan DataFilter untuk memilih metadata yang ingin dihapus.

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 spreadsheets.developerMetadata.get metode, dengan menentukan ID metadata yang dihapus. Anda akan menerima respons kode status HTTP 404: Not Found, dengan pesan yang menyatakan "No developer metadata with ID METADATA_ID.

Permintaan

{
  "requests": [
    {
      "deleteDeveloperMetadata": {
        "dataFilter": {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      }
    }
  ]
}

Respons

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "deleteDeveloperMetadata": {
        "deletedDeveloperMetadata": [
          {
            "metadataId": METADATA_ID,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": SHEET_ID
            },
            "visibility": "DOCUMENT"
          }
        ]
      }
    }
  ]
}

Membaca dan menulis nilai yang terkait dengan metadata

Anda juga dapat mengambil dan memperbarui nilai sel di baris dan kolom dengan menentukan metadata developer terkait dan nilai yang ingin Anda perbarui. Untuk melakukannya, gunakan salah satu metode berikut dengan yang cocok DataFilter.

Mendapatkan nilai sel berdasarkan metadata

Untuk mendapatkan nilai sel berdasarkan 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": METADATA_ID
      }
    }
  ],
  "majorDimension": "ROWS"
}

Respons

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "valueRange": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "74"
          ]
        ]
      },
      "dataFilters": [
        {
          "developerMetadataLookup": {
            "metadataId": METADATA_ID
          }
        }
      ]
    }
  ]
}

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.

Fungsi permintaan ini sama dengan 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 ditetapkan ke true, data petak yang berpotongan dengan rentang petak yang ditentukan juga akan ditampilkan untuk sheet. Kolom includeGridData akan diabaikan jika mask kolom ditetapkan dalam permintaan.

Dalam contoh ini, kami memberikan ID metadata dan menetapkan includeGridData ke false dalam permintaan. Respons menampilkan properti spreadsheet dan sheet.

Permintaan

{
  "dataFilters": [
    {
      "developerMetadataLookup": {
        "metadataId": METADATA_ID
      }
    }
  ],
  "includeGridData": false
}

Respons

{
  "spreadsheetId": SPREADSHEET_ID,
  "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": SHEET_ID,
        "title": "Sheet7",
        "index": 7,
        "sheetType": "GRID",
        "gridProperties": {
          "rowCount": 1000,
          "columnCount": 26
        }
      }
    }
  ],
  "spreadsheetUrl": SPREADSHEET_URL
}

Memperbarui nilai berdasarkan metadata

Untuk memperbarui nilai sel yang cocok dengan metadata tertentu, gunakan spreadsheets.values.batchUpdateByDataFilter metode. Anda harus menentukan ID spreadsheet, valueInputOption, dan satu atau beberapa DataFilterValueRange nilai yang cocok dengan metadata.

Dalam contoh ini, kami 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": METADATA_ID
        }
      },
      "majorDimension": "ROWS",
      "values": [
        [
          "W-24",
          "84"
        ]
      ]
    }
  ],
  "includeValuesInResponse": true,
  "valueInputOption": "USER_ENTERED"
}

Respons

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 1,
  "totalUpdatedColumns": 2,
  "totalUpdatedCells": 2,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "updatedRange": "Sheet7!A7:B7",
      "updatedRows": 1,
      "updatedColumns": 2,
      "updatedCells": 2,
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": METADATA_ID
        }
      },
      "updatedData": {
        "range": "Sheet7!A7:Z7",
        "majorDimension": "ROWS",
        "values": [
          [
            "W-24",
            "84"
          ]
        ]
      }
    }
  ]
}

Menghapus nilai berdasarkan 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": METADATA_ID
      }
    }
  ]
}

Respons

{
  "spreadsheetId": SPREADSHEET_ID,
  "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 dua 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 dua, dan seterusnya). Jadi,spreadsheet dengan tiga sheet dapat berisi hingga 120.000 karakter metadata.

Setiap karakter di kolom metadataKey dan metadataValue dari resource spreadsheets.developerMetadata dihitung dalam batas ini.

Membaca, menulis, dan menelusuri metadata Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Tentang metadata

Kasus penggunaan

Membaca dan menulis metadata

Membuat metadata

Membaca satu item metadata

Membaca beberapa item metadata

Memperbarui metadata

Menghapus metadata

Membaca dan menulis nilai yang terkait dengan metadata

Mendapatkan nilai sel berdasarkan metadata

Mendapatkan spreadsheet berdasarkan metadata

Memperbarui nilai berdasarkan metadata

Menghapus nilai berdasarkan metadata

Batas penyimpanan metadata

Topik terkait

Membaca, menulis, dan menelusuri metadata