Đọc, ghi và tìm kiếm siêu dữ liệu

Tính năng siêu dữ liệu 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 bảng tính. Sau đó, bạn có thể truy vấn siêu dữ liệu này và dùng siêu dữ liệu đó để tìm các đối tượng mà siêu dữ liệu được liên kết.

Bạn có thể liên kết siêu dữ liệu với các hàng, cột, trang tính hoặc bảng tính.

Giới thiệu về siêu dữ liệu

Sau đây là một số khía cạnh chính của siêu dữ liệu mà bạn nên cân nhắc khi làm việc với API Trang tính:

1. Siêu dữ liệu dưới dạng thẻ: Một cách sử dụng siêu dữ liệu của nhà phát triển là thẻ. Thẻ này chỉ dùng khoá và vị trí để đặt tên cho một vị trí trong bảng tính. 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ể dùng thẻ để liên kết theo ngữ nghĩa các phần của bảng tính với các trường trong một công cụ hoặc cơ sở dữ liệu của bên thứ ba, nhờ đó, những thay đổi đối với bảng tính sẽ không làm hỏng ứng dụng của bạn.

2. 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ị hoạt động như một cặp khoá-giá trị được 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 = resp123 có một hàng
   • lastUpdated = 1477369882 có một cột

   Điều này cho phép bạn lưu trữ và truy cập vào các thuộc tính tuỳ chỉnh được đặt tên liên kết với các khu vực hoặc dữ liệu cụ thể trong bảng tính.

3. Siêu dữ liệu hiển thị của 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, có hai 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 project chỉ hiển thị và có thể truy cập được từ dự án Google Cloud đã tạo siêu dữ liệu đó. Bạn có thể truy cập vào siêu dữ liệu document từ bất kỳ dự án Google Cloud nào có quyền truy cập vào tài liệu.

   Các truy vấn không chỉ định rõ visibility sẽ trả về siêu dữ liệu document trùng khớp và siêu dữ liệu project trùng khớp cho dự án Google Cloud đưa ra yêu cầu.

   Đừng sử dụng siêu dữ liệu nhà phát triển mà dự án có thể thấy làm cơ chế bảo mật hoặc để lưu trữ các khoá bí mật. Siêu dữ liệu có thể được hiển thị cho người dùng có quyền xem tài liệu.

4. Tính duy nhất: 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. Bạn có thể dùng mã nhận dạng này để xác định siêu dữ liệu, trong khi các khoá và thuộc tính khác có thể dùng để xác định các tập hợp siêu dữ liệu.

   Mặc dù bạn có thể chỉ định `metadataId` của riêng mình khi tạo siêu dữ liệu, nhưng bạn nên cho phép API Trang tính chỉ định một mã nhận dạng cho bạn.

5. Trả về siêu dữ liệu thông qua các yêu cầu API: Đối tượng DataFilter là một phần của lệnh gọi API, mô tả dữ liệu sẽ được chọn hoặc trả về từ một yêu cầu API.

   Một đối tượng DataFilter chỉ có thể chỉ định một loại tiêu chí lọc để xác định vị trí dữ liệu:

   • developerMetadataLookup: Chọn dữ liệu được liên kết với siêu dữ liệu nhà phát triển được chỉ định khớp với tiêu chí.

   • a1Range: Chọn dữ liệu khớp với phạm vi ký hiệu A1 được chỉ định. Ví dụ: Sheet1!A1:B10.

   • gridRange: Chọn dữ liệu khớp với dải ô lưới đã chỉ định bằng cách sử dụng chỉ mục dựa trên 0. Ví dụ: Sheet1!A3:B4 == sheetId: 123456, startRowIndex: 2, endRowIndex: 4, startColumnIndex: 0, endColumnIndex: 2.

   Để lọc theo nhiều vị trí hoặc tiêu chí, bạn có thể sử dụng nhiều đối tượng DataFilter trong một yêu cầu API duy nhất. Cung cấp một mảng hoặc danh sách các đối tượng DataFilter cho một yêu cầu hàng loạt như phương thức spreadsheets.values.batchGetByDataFilter. Mọi dải ô khớp với bất kỳ bộ lọc dữ liệu nào trong yêu cầu sẽ được trả về hoặc sửa đổi.

   Để biết thêm thông tin, hãy xem phần Đọc và ghi các giá trị được liên kết với siêu dữ liệu.

Trường hợp sử dụng

Sau đây là một số ví dụ về trường hợp sử dụng để quản lý siêu dữ liệu:

• 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 totals với cột D hoặc responseId = 1234 vớ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ụ: cho khoá totals liên kết với cột D hoặc cho responseId, trả về tất cả các hàng có siêu dữ liệu responseId và 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ụ: cho cột D, 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ị tại một vị trí bằng cách chỉ định siêu dữ liệu được liên kết: Ví dụ: cho totals, hãy trả về một biểu thị của các giá trị có trong cột hoặc hàng được liên kết hoặc cho summary, hãy trả về một biểu thị của Tài nguyên Trang tính được liên kết.

• Cập nhật các 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 các giá trị bằng cách cho biết 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 được liên kết với một vị trí hoặc đối tượng trong bảng tính. Bạn có thể dùng siêu dữ liệu nhà phát triển để liên kết dữ liệu tuỳ ý với nhiều phần của bảng tính. Siêu dữ liệu vẫn được liên kết tại những vị trí đó khi bạn chỉnh sửa bảng tính.

Tạo siêu dữ liệu

Để tạo siêu dữ liệu, hãy sử dụng phương thức batchUpdate trên tài nguyên spreadsheets và cung cấp CreateDeveloperMetadataRequest với các giá trị metadataKey, location và visibility từ tài nguyên spreadsheets.developerMetadata. Bạn có thể tuỳ ý chỉ định một metadataValue hoặc một metadataId tường minh.

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, API sẽ chỉ định một mã nhận dạng.

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

Đáp

{
  "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"
        }
      }
    }
  ]
}

Đọc một mục siêu dữ liệu

Để truy xuất một siêu dữ liệu riêng biệt duy nhất của 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 duy nhất của siêu dữ liệu nhà phát triển.

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 này trả về các giá trị siêu dữ liệu nhà phát triển cho mã siêu dữ liệu.

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

Đáp

{
  "metadataId": METADATA_ID,
  "metadataKey": "Sales",
  "metadataValue": "2022",
  "location": {
    "locationType": "ROW",
    "dimensionRange": {
      "sheetId": SHEET_ID,
      "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 của nhà phát triển, hãy sử dụng phương thức spreadsheets.developerMetadata.search. Bạn phải 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 khả năng hiển thị.

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 trả về các giá trị siêu dữ liệu nhà phát triển cho từng mã siêu dữ liệu.

Yêu cầu

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

Đáp

{
  "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
          }
        }
      ]
    }
  ]
}

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 phải chỉ định một DataFilter nhắm đến siêu dữ liệu cần cập nhật, một tài nguyên spreadsheets.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.

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

Đáp

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "updateDeveloperMetadata": {
        "developerMetadata": [
          {
            "metadataId": METADATA_ID,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": SHEET_ID
            },
            "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 DeleteDeveloperMetadataRequest. Bạn phải chỉ định một DataFilter để chọn siêu dữ liệu mà bạn muốn xoá.

Trong ví dụ này, chúng ta cung cấp mã nhận dạng siêu dữ liệu trong yêu cầu. Phản hồi này trả về các giá trị siêu dữ liệu nhà phát triển cho mã siêu dữ liệu.

Để xác nhận rằng 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 đã bị 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ã METADATA_ID.

Yêu cầu

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

Đáp

{
  "spreadsheetId": SPREADSHEET_ID,
  "replies": [
    {
      "deleteDeveloperMetadata": {
        "deletedDeveloperMetadata": [
          {
            "metadataId": METADATA_ID,
            "metadataKey": "SalesUpdated",
            "metadataValue": "2022",
            "location": {
              "locationType": "SHEET",
              "sheetId": SHEET_ID
            },
            "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 các hàng và cột bằng cách chỉ định siêu dữ liệu liên kết của nhà phát triển và các giá trị bạn muốn cập nhật. Để làm việc này, hãy sử dụng một trong các phương thức sau với DataFilter phù hợp.

Nhận 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 phải 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.

Trong ví dụ này, chúng ta cung cấp mã nhận dạng siêu dữ liệu trong yêu cầu. Phản hồi này trả về các giá trị ô hàng (số hiệu mẫu, doanh số hằng tháng) cho mã nhận dạng siêu dữ liệu.

Yêu cầu

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

Đáp

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

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 phải 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 "spreadsheet GET" 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 được 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 includeGridData được đặt thành true, thì dữ liệu lưới giao với các dải ô lưới được chỉ định cũng được trả về cho trang tính. Trường includeGridData sẽ bị bỏ qua nếu bạn đặt một mặt nạ trường trong yêu cầu.

Trong ví dụ này, chúng ta cung cấp mã nhận dạng siêu dữ liệu và đặt includeGridData thành false trong yêu cầu. Phản hồi trả về cả bảng tính và các thuộc tính của trang tính.

Yêu cầu

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

Đáp

{
  "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
}

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 dùng phương thức spreadsheets.values.batchUpdateByDataFilter. Bạn phải chỉ định mã bảng tính, valueInputOption và một hoặc nhiều giá trị DataFilterValueRange khớp với siêu dữ liệu.

Trong ví dụ này, chúng ta 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ả các thuộc tính và dữ liệu đã cập nhật cho mã nhận dạng siêu dữ liệu.

Yêu cầu

{
  "data": [
    {
      "dataFilter": {
        "developerMetadataLookup": {
          "metadataId": METADATA_ID
        }
      },
      "majorDimension": "ROWS",
      "values": [
        [
          "W-24",
          "84"
        ]
      ]
    }
  ],
  "includeValuesInResponse": true,
  "valueInputOption": "USER_ENTERED"
}

Đáp

{
  "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"
          ]
        ]
      }
    }
  ]
}

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 phải chỉ định một bộ lọc dữ liệu để chọn siêu dữ liệu mà bạn muốn xoá.

Yêu cầu

Trong ví dụ này, chúng ta cung cấp mã nhận dạng siêu dữ liệu trong yêu cầu. Phản hồi này trả về mã nhận dạng bảng tính và các dải ô đã xoá.

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

Đáp

{
  "spreadsheetId": SPREADSHEET_ID,
  "clearedRanges": [
    "Sheet7!A7:Z7"
  ]
}

Hạn mức lưu trữ siêu dữ liệu

Có một giới hạn về tổng lượng siêu dữ liệu mà bạn có thể lưu trữ trong một bảng tính. Giới hạn này được đo bằng số 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 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 trong bảng tính (30.000 cho trang một, 30.000 cho trang hai, v.v.). Vì vậy,một bảng tính có 3 trang tính có thể chứa tối đa 120.000 ký tự siêu dữ liệu.

Mỗi ký tự trong các trường metadataKey và metadataValue của tài nguyên spreadsheets.developerMetadata được tính vào giới hạn này.

Chủ đề có liên quan

• Áp dụng bộ lọc cho dữ liệu trên Google Trang tính
• Quản lý khả năng hiển thị dữ liệu bằng bộ lọc
• Hạn mức sử dụng