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 và dùng siêu dữ liệu này để tìm các đối tượng liên kết với siêu dữ liệu này.
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 của 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 một 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á siêu dữ liệu hoặc thuộc tính cụ thể – Ví dụ: với khoá
totalsliên kết với cột D hoặcresponseId, 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 những 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ụ: trong trường hợp
totalssẽ trả về bản trình bày các giá trị có trong cột hoặc hàng liên kết, hoặc nếusummarytrả về giá trị đại diện của 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 được liên kết – Ví dụ: thay vì cập nhật các 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 một bảng tính.
Giới thiệu về siêu dữ liệu của 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 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ẻ có chức năng đặt tên cho một vị trí trong bảng tính chỉ bằng cách sử dụng khoá và 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 trang tính. Bạn có thể dùng thẻ để liên kết về mặ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à 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 = resp123với một hànglastUpdated = 1477369882với một cột.
Việc này cho phép bạn lưu trữ và truy cập vào các thuộc tính được đặt tên tuỳ chỉnh được liên kết với các khu vực hoặc dữ liệu cụ thể trong một bảng tính.
Siêu dữ liệu hiển thị dự án so với 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 dự án khác, bạn cần có 2 chế độ cài đặt visibility siêu dữ liệu: 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 qua dự án nhà phát triển đã tạo siêu dữ liệu đó. Bạn có thể truy cập vào siêu dữ liệu của 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 này.
Các truy vấn không chỉ định rõ ràng chế độ hiển thị sẽ trả về siêu dữ liệu tài liệu trùng khớp và siêu dữ liệu dự án trùng 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à không chỉ định trường mã nhận dạng, thì API sẽ chỉ định một trường hợp. Mã nhận dạng này có thể dùng để xác định siêu dữ liệu, trong khi khoá và các thuộc tính khác có thể dùng để xác định các bộ 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 cùng với metadataKey, location và visibility. Bạn có thể tuỳ ý chỉ định metadataValue hoặc metadataId rõ ràng.
Nếu bạn chỉ định một mã nhận dạng đã đượ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 thì API sẽ chỉ định mã đó.
Hiển thị ví dụ
Trong ví dụ này, chúng tôi cung cấp 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 dành cho 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 riêng biệt dành cho nhà phát triển, 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 dành cho nhà phát triển.
Hiển thị ví dụ
Yêu cầu
Trong ví dụ này, chúng tôi cung cấp mã bảng tính và mã siêu dữ liệu trong yêu cầu. Phản hồi này sẽ trả về các giá trị siêu dữ liệu dành cho 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 tôi cung cấp nhiều mã siêu dữ liệu trong yêu cầu. Phản hồi này sẽ trả về các giá trị siêu dữ liệu dành cho 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 một UpdateDeveloperMetadataRequest.
Bạn cần chỉ định một DataFilter nhắm mục tiêu siêu dữ liệu cần cập nhật, đối tượng DeveloperMetadata với các giá trị mới và 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 tôi 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 dành cho nhà phát triển này cùng với khoá siêu dữ liệu được 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 của nhà phát triển, hãy sử dụng phương thức batchUpdate và cung cấp một 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 tôi cung cấp mã siêu dữ liệu trong yêu cầu. Phản hồi này sẽ trả về các giá trị siêu dữ liệu dành cho nhà phát triển cho mã siêu dữ liệu.
Để xác nhận rằng siêu dữ liệu dành cho 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 cho biết "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ị được 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 hàng và cột bằng cách chỉ định siêu dữ liệu của nhà phát triển được liên kết và các giá trị mà bạn muốn cập nhật. Để làm điều này, hãy sử dụng phương thức thích hợp bên dưới với DataFilter phù hợp.
Lấy giá trị của ô theo siêu dữ liệu
Để nhận giá trị ô theo siêu dữ liệu, hãy sử dụng phương thức spreadsheets.values.batchGetByDataFilter. Bạn sẽ 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 tôi cung cấp mã siêu dữ liệu trong yêu cầu. Phản hồi trả về giá trị ô trong hàng (số kiểu máy, 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
}
}
]
}
]
}
Tải 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 dữ liệu con bằng cách sử dụng phương thức spreadsheets.getByDataFilter. Bạn sẽ 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 " GET của bảng tính" thông thường, ngoại trừ danh sách siêu dữ liệu khớp với các bộ lọc dữ liệu đã chỉ định sẽ xác định những trang tính, dữ liệu lưới và các 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 (đúng), thì dữ liệu lưới giao với các dải lướ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 tôi 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 sẽ cần chỉ định mã nhận dạng 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 tôi cung cấp mã siêu dữ liệu và các giá trị hàng đã cập nhật trong yêu cầu. Phản hồi trả về 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 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 tôi 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 ô đã được xoá.
{
"dataFilters": [
{
"developerMetadataLookup": {
"metadataId": metadataId
}
}
]
}
Đáp
{
"spreadsheetId": spreadsheetId,
"clearedRanges": [
"Sheet7!A7:Z7"
]
}
Hạn mức bộ nhớ siêu dữ liệu
Có giới hạn về tổng lượng siêu dữ liệu bạn có thể lưu trữ trong một bảng tính. Giới hạn này được đo bằng ký tự và do 2 thành phần tạo thành:
| 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 nhà phát triển.
Mỗi ký tự trong các thuộc tính khoá và giá trị của đối tượng developerMetadata đều được tính vào giới hạn này.