Mặt nạ trường 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 được dùng cho cả phương thức đọc và cập nhật trong API Google Trang trình bày.
Đọc bằng mặt nạ trường
Các bản trình bày có thể có kích thước lớn và thường thì bạn không cần mọi phần của tài nguyên Presentation do 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 Trang trình bày bằng cách dùng tham số URL fields. Để có hiệu suất tốt nhất, hãy 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 giống với mã hoá JSON của Mặt nạ trường. Nói 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 trong camelCase hoặc Split_by_underscores. Để thuận tiện, bạn có thể liệt kê nhiều trường phụ từ cùng một loại trong dấu ngoặc đơn.
Ví dụ về yêu cầu presentations.get sau đây sử dụng mặt nạ trường của slides.pageElements(objectId,size,transform) để chỉ tìm nạp mã nhận dạng đối tượng, Size và biến đổi của đối tượng pageElement trên tất cả các trang trình bày trong một bản trình bày:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
Phản hồi cho lệnh gọi phương thức này là một đối tượng Presentation chứa các thành phần được yêu cầu trong mặt nạ trường:
{
"slides": [
{
"pageElements": [
{
"objectId": "OBJECT_ID",
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1
"translateX": 311708,
"translateY": 744575,
"unit": "EMU"
}
},
{
"objectId": "OBJECT_ID",
"size": {
"width": {
"magnitude": 3000000,
"unit": "EMU"
},
"height": {
"magnitude": 3000000,
"unit": "EMU"
}
},
"transform": {
"scaleX": 1,
"scaleY": 1
"translateX": 311700,
"translateY": 2834125,
"unit": "EMU"
}
}
]
}
]
}
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 một thao tác presentations.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, để 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 trước đó có.
Cú pháp của mặt nạ trường cập nhật giống như mặt nạ trường đọc.
Ví dụ sau sử dụng UpdateShapePropertiesRequest để thay đổi màu nền của một hình dạng thành màu giao diện DARK1 và huỷ đặt đường viền của hình dạng:
POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
{
"requests": [
{
"updateShapeProperties": {
"objectId": OBJECT_ID,
"shapeProperties": {
"shapeBackgroundFill": {
"solidFill": {
"color": {
"themeColor": "DARK1"
}
}
}
},
"fields": "shapeBackgroundFill.solidFill.color,outline"
}
}
]
}