Tính năng siêu dữ liệu dành cho nhà phát triển cho phép bạn liên kết siêu dữ liệu với nhiều thực thể và vị trí trong một bảng tính. Sau đó, bạn có thể truy vấn siêu dữ liệu này và sử dụng siêu dữ liệu đó để tìm các đối tượng được liên kết với siêu dữ liệu.
Bạn có thể liên kết siêu dữ liệu với hàng, cột, trang tính hoặc bảng tính.
Siêu dữ liệu dành cho nhà phát triển cho phép bạn thực hiện các thao tác như:
Liên kết dữ liệu tuỳ ý với nhiều thực thể và vị trí trong bảng tính – Ví dụ: liên kết
totalsvới cột D hoặcresponseId = 1234với hàng 7.Tìm tất cả vị trí và dữ liệu liên kết với một khoá hoặc thuộc tính siêu dữ liệu cụ thể – Ví dụ: với khoá
totalsliên kết với cột D hoặc vớiresponseId, hãy trả về tất cả các hàng có siêu dữ liệuresponseIdvà giá trị siêu dữ liệu liên kết với các hàng đó.Tìm tất cả dữ liệu liên kết với một thực thể hoặc vị trí cụ thể – Ví dụ: với cột D, hãy trả về tất cả siêu dữ liệu liên kết với vị trí đó.
Truy xuất các giá trị ở một vị trí bằng cách chỉ định siêu dữ liệu liên kết – Ví dụ: cho
totalstrả về nội dung đại diện cho các giá trị có trong cột hoặc hàng được liên kết hoặc chosummarytrả về nội dung đại diện cho tài nguyên Trang tính được liên kết.Cập nhật giá trị ở một vị trí bằng cách chỉ định siêu dữ liệu liên kết – Ví dụ: thay vì cập nhật giá trị trong một hàng thông qua ký hiệu A1, hãy cập nhật giá trị bằng cách chỉ định mã siêu dữ liệu.
Đọc và ghi siêu dữ liệu
Tài nguyên spreadsheets.developerMetadata cung cấp quyền truy cập vào siêu dữ liệu nhà phát triển liên kết với một vị trí hoặc đối tượng trong bảng tính.
Giới thiệu về siêu dữ liệu dành cho nhà phát triển
Phần này mô tả một số khía cạnh chính của siêu dữ liệu dành cho nhà phát triển mà bạn nên cân nhắc khi làm việc với API Trang tính.
Siêu dữ liệu dưới dạng thẻ
Một cách sử dụng siêu dữ liệu dành cho nhà phát triển là thẻ đặt tên cho một vị trí trong bảng tính chỉ bằng một khoá và một vị trí. Ví dụ: bạn có thể liên kết headerRow với một hàng cụ thể hoặc totals với một cột cụ thể trong một trang tính. Bạn có thể sử dụng thẻ để liên kết ngữ nghĩa các phần của bảng tính với các trường trong công cụ hoặc cơ sở dữ liệu của bên thứ ba, nhờ đó, các thay đổi đối với bảng tính sẽ không làm hỏng ứng dụng của bạn.
Siêu dữ liệu dưới dạng thuộc tính
Siêu dữ liệu được tạo bằng cách chỉ định một khoá, vị trí và một giá trị đóng vai trò là một cặp khoá-giá trị liên kết với vị trí đó trong một trang tính. Ví dụ: bạn có thể liên kết:
formResponseId = resp123có một hànglastUpdated = 1477369882có một cột.
Điều này cho phép bạn lưu trữ và truy cập các thuộc tính được đặt tên tuỳ chỉnh liên kết với các khu vực hoặc dữ liệu cụ thể trong bảng tính.
Siêu dữ liệu hiển thị của dự án so với siêu dữ liệu hiển thị của tài liệu
Để ngăn một dự án của nhà phát triển can thiệp vào siêu dữ liệu của một dự án khác, có 2 chế độ cài đặt siêu dữ liệu visibility: project và document. Khi sử dụng API Trang tính, siêu dữ liệu dự án chỉ hiển thị và truy cập được từ dự án nhà phát triển đã tạo siêu dữ liệu đó. Bạn có thể truy cập siêu dữ liệu tài liệu từ bất kỳ dự án nhà phát triển nào có quyền truy cập vào tài liệu đó.
Các truy vấn không chỉ định rõ chế độ hiển thị trả về siêu dữ liệu tài liệu khớp và siêu dữ liệu dự án khớp cho dự án nhà phát triển đưa ra yêu cầu.
Điểm đặc biệt
Các khoá siêu dữ liệu không nhất thiết phải là duy nhất, nhưng metadataId phải khác biệt. Nếu bạn tạo siêu dữ liệu và để trống trường mã nhận dạng, API sẽ chỉ định một mã nhận dạng. Bạn có thể dùng mã nhận dạng này để xác định siêu dữ liệu, còn khoá và các thuộc tính khác có thể được dùng để xác định tập hợp siêu dữ liệu.
Tạo siêu dữ liệu
Để tạo siêu dữ liệu, hãy sử dụng phương thức batchUpdate và cung cấp createDeveloperMetadataRequest bằng metadataKey, location và visibility. Bạn có thể tuỳ ý chỉ định metadataValue hoặc metadataId tường minh.
Nếu bạn chỉ định một mã đã được sử dụng, thì yêu cầu sẽ không thành công. Nếu bạn không cung cấp mã nhận dạng, API sẽ chỉ định mã nhận dạng.
Hiển thị ví dụ
Trong ví dụ này, chúng ta cung cấp một khoá, giá trị và một hàng trong yêu cầu. Phản hồi sẽ trả về các giá trị siêu dữ liệu của nhà phát triển này, cùng với mã siêu dữ liệu được chỉ định.
Yêu cầu
{
"requests": [
{
"createDeveloperMetadata": {
"developerMetadata": {
"location": {
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT",
"metadataKey": "Sales",
"metadataValue": "2022"
}
}
}
]
}Đáp
{
"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"
}
}
}
]
}Đọc một mục siêu dữ liệu
Để truy xuất một siêu dữ liệu nhà phát triển riêng biệt, hãy sử dụng phương thức spreadsheets.developerMetadata.get, chỉ định spreadsheetId chứa siêu dữ liệu và metadataId riêng biệt của siêu dữ liệu nhà phát triển.
Hiển thị ví dụ
Yêu cầu
Trong ví dụ này, chúng ta cung cấp mã nhận dạng bảng tính và mã nhận dạng siêu dữ liệu trong yêu cầu. Phản hồi trả về các giá trị siêu dữ liệu của nhà phát triển cho mã siêu dữ liệu.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/developerMetadata/metadataId
Đáp
{
"metadataId": metadataId,
"metadataKey": "Sales",
"metadataValue": "2022",
"location": {
"locationType": "ROW",
"dimensionRange": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 6,
"endIndex": 7
}
},
"visibility": "DOCUMENT"
}Đọc nhiều mục siêu dữ liệu
Để truy xuất nhiều mục siêu dữ liệu dành cho nhà phát triển, hãy sử dụng phương thức spreadsheets.developerMetadata.search. Bạn cần chỉ định một DataFilter khớp với mọi siêu dữ liệu hiện có trên mọi tổ hợp thuộc tính, chẳng hạn như khoá, giá trị, vị trí hoặc chế độ hiển thị.
Hiển thị ví dụ
Trong ví dụ này, chúng ta cung cấp nhiều mã siêu dữ liệu trong yêu cầu. Phản hồi trả về các giá trị siêu dữ liệu của nhà phát triển cho từng mã siêu dữ liệu.
Yêu cầu
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
},
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Đáp
{
"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
}
}
]
}
]
}Cập nhật siêu dữ liệu
Để cập nhật siêu dữ liệu của nhà phát triển, hãy sử dụng phương thức spreadsheets.batchUpdate và cung cấp UpdateDeveloperMetadataRequest.
Bạn cần chỉ định một DataFilter nhắm đến siêu dữ liệu cần cập nhật, một đối tượng DeveloperMetadata có các giá trị mới và một mặt nạ trường mô tả các trường cần cập nhật.
Hiển thị ví dụ
Trong ví dụ này, chúng ta cung cấp mã siêu dữ liệu, mã trang tính và khoá siêu dữ liệu mới trong yêu cầu. Phản hồi sẽ trả về các giá trị siêu dữ liệu của nhà phát triển này, cùng với khoá siêu dữ liệu đã cập nhật.
Yêu cầu
{
"requests": [
{
"updateDeveloperMetadata": {
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"developerMetadata": {
"location": {
"sheetId": sheetId
},
"metadataKey": "SalesUpdated"
},
"fields": "location,metadataKey"
}
}
]
}Đáp
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"updateDeveloperMetadata": {
"developerMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Xoá siêu dữ liệu
Để xoá siêu dữ liệu nhà phát triển, hãy sử dụng phương thức batchUpdate và cung cấp DeleteDeveloperMetadataRequest.
Bạn cần chỉ định DataFilter để chọn siêu dữ liệu mà bạn muốn xoá.
Hiển thị ví dụ
Trong ví dụ này, chúng ta cung cấp mã siêu dữ liệu trong yêu cầu. Phản hồi trả về các giá trị siêu dữ liệu của nhà phát triển cho mã siêu dữ liệu.
Để xác nhận siêu dữ liệu của nhà phát triển đã bị xoá, hãy sử dụng phương thức spreadsheets.developerMetadata.get, chỉ định mã siêu dữ liệu đã xoá. Bạn sẽ nhận được phản hồi mã trạng thái HTTP 404: Not Found, kèm theo thông báo "Không có siêu dữ liệu nhà phát triển nào có mã nhận dạng metadataId.
Yêu cầu
{
"requests": [
{
"deleteDeveloperMetadata": {
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
}
}
}
]
}Đáp
{
"spreadsheetId": spreadsheetId,
"replies": [
{
"deleteDeveloperMetadata": {
"deletedDeveloperMetadata": [
{
"metadataId": metadataId,
"metadataKey": "SalesUpdated",
"metadataValue": "2022",
"location": {
"locationType": "SHEET",
"sheetId": sheetId
},
"visibility": "DOCUMENT"
}
]
}
}
]
}Đọc và ghi các giá trị liên kết với siêu dữ liệu
Bạn cũng có thể truy xuất và cập nhật giá trị ô trong các hàng và cột bằng cách chỉ định siêu dữ liệu nhà phát triển liên kết và các giá trị bạn muốn cập nhật. Để thực hiện việc này, hãy sử dụng phương thức thích hợp bên dưới với một DataFilter phù hợp.
Lấy giá trị ô theo siêu dữ liệu
Để lấy giá trị ô theo siêu dữ liệu, hãy sử dụng phương thức spreadsheets.values.batchGetByDataFilter. Bạn cần chỉ định mã nhận dạng bảng tính và một hoặc nhiều bộ lọc dữ liệu khớp với siêu dữ liệu.
Hiển thị ví dụ
Trong ví dụ này, chúng ta cung cấp mã siêu dữ liệu trong yêu cầu. Phản hồi trả về các giá trị ô hàng (số mô hình, doanh số bán hàng hằng tháng) cho mã siêu dữ liệu.
Yêu cầu
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"majorDimension": "ROWS"
}Đáp
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{
"valueRange": {
"range": "Sheet7!A7:Z7",
"majorDimension": "ROWS",
"values": [
[
"W-24",
"74"
]
]
},
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
]
}Lấy bảng tính theo siêu dữ liệu
Khi truy xuất một bảng tính, bạn có thể trả về một tập hợp con dữ liệu bằng cách sử dụng phương thức spreadsheets.getByDataFilter. Bạn cần chỉ định mã nhận dạng bảng tính và một hoặc nhiều bộ lọc dữ liệu khớp với siêu dữ liệu.
Yêu cầu này hoạt động như một yêu cầu "tệp trang tính GET" thông thường, ngoại trừ danh sách siêu dữ liệu được so khớp bằng bộ lọc dữ liệu đã chỉ định sẽ xác định những trang tính, dữ liệu lưới và tài nguyên đối tượng khác có siêu dữ liệu được trả về. Nếu bạn đặt includeGridData thành true, thì dữ liệu lưới giao nhau với các dải ô đã chỉ định cũng sẽ được trả về cho trang tính.
Hiển thị ví dụ
Trong ví dụ này, chúng ta cung cấp mã siêu dữ liệu và đặt includeGridData thành false trong yêu cầu. Phản hồi trả về cả thuộc tính bảng tính và trang tính.
Yêu cầu
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
],
"includeGridData": false
}Đáp
{ "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 }
Cập nhật giá trị theo siêu dữ liệu
Để cập nhật các giá trị ô khớp với siêu dữ liệu cụ thể, hãy sử dụng phương thức spreadsheets.values.batchUpdateByDataFilter. Bạn cần chỉ định mã bảng tính, valueInputOption và một hoặc nhiều DataFilterValueRange khớp với siêu dữ liệu.
Hiển thị ví dụ
Trong ví dụ này, chúng ta cung cấp mã siêu dữ liệu và giá trị hàng đã cập nhật trong yêu cầu. Phản hồi trả về cả các thuộc tính và dữ liệu đã cập nhật cho mã siêu dữ liệu.
Yêu cầu
{
"data": [
{
"dataFilter": {
"developerMetadataLookup": {
"metadataId": metadataId
}
},
"majorDimension": "ROWS",
"values": [
[
"W-24",
"84"
]
]
}
],
"includeValuesInResponse": true,
"valueInputOption": "USER_ENTERED"
}Đáp
{
"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"
]
]
}
}
]
}Xoá giá trị theo siêu dữ liệu
Để xoá các giá trị ô khớp với siêu dữ liệu cụ thể, hãy sử dụng phương thức spreadsheets.values.batchClearByDataFilter. Bạn cần chỉ định một bộ lọc dữ liệu để chọn siêu dữ liệu mà bạn muốn xoá.
Hiển thị ví dụ
Yêu cầu
Trong ví dụ này, chúng ta cung cấp mã siêu dữ liệu trong yêu cầu. Phản hồi sẽ trả về mã nhận dạng bảng tính và các dải ô đã xoá.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}Đáp
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}Hạn mức bộ nhớ siêu dữ liệu
Tổng lượng siêu dữ liệu mà bạn có thể lưu trữ trong một bảng tính là có hạn. Giới hạn này được tính bằng ký tự và bao gồm 2 thành phần:
| Mục | Phân bổ hạn mức bộ nhớ |
|---|---|
| Bảng tính | 30.000 ký tự |
| Mỗi trang tính trong một bảng tính | 30.000 ký tự |
Bạn có thể lưu trữ tối đa 30.000 ký tự cho bảng tính. Ngoài ra, bạn có thể lưu trữ 30.000 ký tự cho mỗi trang tính trong một bảng tính (30.000 ký tự cho trang tính 1, 30.000 ký tự cho trang tính 2, v.v.). Vì vậy,một bảng tính có 3 trang có thể chứa tối đa 120.000 ký tự siêu dữ liệu dành cho nhà phát triển.
Mỗi ký tự trong thuộc tính khoá và giá trị của đối tượng developerMetadata được tính vào giới hạn này.