Mặt nạ trường là một cách để phương thức gọi API liệt kê các trường mà yêu cầu sẽ trả về hoặc cập nhật. Việc sử dụng FieldMask cho phép API tránh thực hiện các công việc không cần thiết và cải thiện hiệu suất. Mặt nạ trường được dùng cho cả phương thức đọc và cập nhật trong API Google Tài liệu.
Đọc bằng mặt nạ trường
Tài liệu có thể có kích thước lớn và thường bạn không cần mọi phần của tài nguyên Document mà yêu cầu đọc trả về. Bạn có thể giới hạn nội dung được trả về trong phản hồi của API Tài liệu bằng cách sử dụng tham số URL fields. Để đạt được hiệu suất tốt nhất, hãy chỉ liệt kê rõ ràng những trường mà bạn cần trong thư trả lời.
Định dạng của tham số trường giống với mã hoá JSON của FieldMask. Nói ngắn gọn, nhiều trường khác nhau được phân tách bằng dấu phẩy và các trường con được phân tách bằng dấu chấm. Bạn có thể chỉ định tên trường theo kiểu camelCase hoặc separated_by_underscores. Để thuận tiện, bạn có thể liệt kê nhiều trường con thuộc cùng một loại trong dấu ngoặc đơn.
Ví dụ về yêu cầu documents.get sau đây sử dụng mặt nạ trường title,tabs(documentTab(body.content(paragraph))),revisionId để tìm nạp title của tài liệu, Paragraph của đối tượng Body (từ tất cả các thẻ) và revisionId của tài liệu trong tài liệu:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId
Phản hồi cho lệnh gọi phương thức này là một đối tượng Document chứa các thành phần được yêu cầu trong mặt nạ trường:
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
}
}
}
]
}Cập nhật bằng mặt nạ trường
Đôi khi, bạn chỉ cần cập nhật một số trường nhất định trong một đối tượng và giữ nguyên các trường khác. Các yêu cầu cập nhật bên trong thao tác documents.batchUpdate sử dụng mặt nạ trường để cho API biết những trường nào đang được thay đổi. Yêu cầu cập nhật sẽ bỏ qua mọi trường không được chỉ định trong mặt nạ trường, giữ lại các trường có giá trị hiện tại.
Bạn cũng có thể huỷ đặt một trường bằng cách không chỉ định trường đó trong thông báo đã cập nhật, nhưng thêm trường đó vào mặt nạ. Thao tác này sẽ xoá mọi giá trị mà trường này từng có.
Cú pháp cho mặt nạ trường cập nhật giống với mặt nạ trường đọc.
Ví dụ sau đây sử dụng UpdateTextStyleRequest để định kiểu cho từ "Google Docs API" trong tài liệu thành in đậm trong range 5–20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID",
"tabs": [
{
"documentTab": {
"body": {
"content": [
{
"endIndex": 1,
"sectionBreak": {
"sectionStyle": {
"columnSeparatorStyle": "NONE",
"contentDirection": "LEFT_TO_RIGHT",
"sectionType": "CONTINUOUS"
}
}
},
{
"startIndex": 1,
"endIndex": 59,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 5,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
},
{
"startIndex": 5,
"endIndex": 20,
"textRun": {
"content": "CONTENT",
"textStyle": {
"bold": true
}
}
},
{
"startIndex": 20,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
{
... // style details
},
}
}
],
}