Sử dụng mặt nạ trường

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 trả lại hoặc cập nhật. 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 pháp đọc và cập nhật trong API Google Trang trình bày.

Đọc bằng mặt nạ trường

Bản trình bày có thể lớn và thường bạn không cần bao gồm tất cả các phần của Presentation được yêu cầu đọc trả về. Bạn có thể giới hạn dữ liệu được trả về trong một Phản hồi của API Trang trình bày, sử dụng tham số URL fields. Tốt nhất hiệu suất chỉ liệt kê rõ ràng những 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 và các trường phụ được phân tách được phân tách bằng dấu chấm. Bạn có thể chỉ định tên trường theo quy tắc camelCase hoặc separated_by_underscores. Để thuận tiện, nhiều trường phụ từ cùng một type (loại) có thể được liệt kê trong dấu ngoặc đơn.

presentations.get sau đây Ví dụ về yêu cầu sử dụng mặt nạ trường của slides.pageElements(objectId,size,transform) để chỉ tìm nạp mã đối tượng Size và chuyển đổi trong một pageElement đối tượng trên tất cả trang trình bày trong 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 trong khi vẫn giữ nguyên các trường khác không thay đổi. Cập nhật yêu cầu bên trong một presentations.batchUpdate hoạt động sử dụng mặt nạ trường để cho API biết những trường nào đang được thay đổi. Chiến lược phát hành đĩa đơn yêu cầu cập nhật sẽ bỏ qua mọi trường chưa được chỉ định trong mặt nạ trường, để chúng với giá trị hiện tại.

Bạn cũng có thể bỏ thiết lập 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 này 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 đây sử dụng phương thức UpdateShapePropertiesRequest để thay đổi màu nền của hình dạng thành màu giao diện DARK1 và bỏ đặt dàn ý:

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