Mặt nạ trường (field mask) là 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 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 (field mask) đượ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ạ cho trường (field mask)
Các tài liệu có thể có kích thước lớn và thông thường, bạn không cần phải có tất cả phần của tài nguyên Document mà một 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. Để có hiệu suất tốt nhất, chỉ liệt kê rõ ràng các trường bạn cần trong câu trả lời.
Định dạng của tham số trường sẽ giống với phương thức mã hoá JSON củafieldMask. Được trình bày ngắn gọn, nhiều trường khác nhau được phân tách bằng dấu phẩy còn các trường phụ được phân tách bằng dấu chấm. Bạn có thể chỉ định tên trường bằng camelCase hoặc Split_by_underscore. Để thuận tiện, bạn có thể liệt kê nhiều trường phụ 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 (field mask) của title,body.content(paragraph),revisionId để tìm nạp title của tài liệu, Paragraph của đối tượng Body và revisionId của tài liệu đó trong một tài liệu:
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,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",
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": ""CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
"revisionId": "REVISION_ID"
}
Cập nhật bằng mặt nạ cho trường (field mask)
Đô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à không thay đổi các trường khác. Cập nhật các yêu cầu bên trong một thao tác documents.batchUpdate sẽ sử dụng mặt nạ trường để cho API biết 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 (field mask) và để lại các trường đó cùng 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, mà thêm trường đó vào mặt nạ. Thao tác này sẽ xoá mọi giá trị mà trường trước đó có.
Cú pháp cho mặt nạ trường cập nhật giống như đọc mặt nạ trường.
Ví dụ sau đây sử dụng UpdateTextStyleRequest để tạo kiểu in đậm cho các từ "API Google Tài liệu" trong tài liệu trong khoảng range 5 – 20:
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"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
},
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID"
}