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

Mặt nạ trường là một cách để người gọi API liệt kê các trường mà một yêu cầu sẽ trả về hoặc cập nhật. Việc sử dụng FieldMask giúp API tránh được những 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 Google Slides API.

Để so sánh những nội dung được trả về trong phần nội dung phản hồi khi bạn không sử dụng mặt nạ trường so với khi bạn sử dụng, hãy xem phần Làm việc với tài nguyên một phần.

Đọ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 presentations 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 Slides API bằng cách sử dụng tham số URL fields. Để có hiệu suất tốt nhất, hãy 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ố fields giống với mã hoá JSON của FieldMask. Nói tóm lại, 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 phương thức presentations.get sau đây sử dụng một mặt nạ trường slides.pageElements(objectId,size,transform) để chỉ tìm nạp mã nhận dạng đối tượng, Size và transform của một đố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 presentations 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 mà không thay đổi các trường khác. Các yêu cầu cập nhật trong phương thứ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 đó giữ nguyên 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 hãy 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 có trướ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 phương thức UpdateShapePropertiesRequest để thay đổi màu tô của một hình thành màu giao diện DARK1 và huỷ đặt đường viền của hình:

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