필드 마스크 사용

필드 마스크는 API 호출자가 요청에서 반환하거나 업데이트해야 하는 필드를 나열하는 방법입니다. FieldMask를 사용하면 API가 불필요한 작업을 방지하고 성능을 개선할 수 있습니다. 필드 마스크는 Google Slides API의 읽기 및 업데이트 메서드 모두에 사용됩니다.

필드 마스크를 사용하지 않는 경우와 사용하는 경우 응답 본문에 반환되는 항목을 비교하려면 부분 리소스 작업을 참고하세요.

필드 마스크로 읽기

프레젠테이션은 클 수 있으며 읽기 요청에서 반환된 presentations 리소스의 모든 부분이 필요하지 않은 경우가 많습니다. fields URL 매개변수를 사용하여 Slides API 응답에서 반환되는 항목을 제한할 수 있습니다. 최적의 성능을 위해 답장에서 필요한 필드만 명시적으로 나열하세요.

fields 매개변수의 형식은 FieldMask의 JSON 인코딩과 동일합니다. 간단히 말해 여러 필드는 쉼표로 구분되고 하위 필드는 점으로 구분됩니다. 필드 이름은 camelCase 또는 separated_by_underscores로 지정할 수 있습니다. 편의를 위해 동일한 유형의 여러 하위 필드를 괄호 안에 나열할 수 있습니다.

다음 presentations.get 메서드 요청 예에서는 slides.pageElements(objectId,size,transform) 필드 마스크를 사용하여 프레젠테이션의 모든 슬라이드에서 pageElement 객체의 객체 ID(Size)와 변환만 가져옵니다.

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

이 메서드 호출에 대한 응답은 필드 마스크에 요청된 구성요소가 포함된 presentations 객체입니다.

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

필드 마스크로 업데이트

다른 필드는 변경하지 않고 객체의 특정 필드만 업데이트해야 하는 경우가 있습니다. presentations.batchUpdate 메서드 내의 업데이트 요청은 필드 마스크를 사용하여 변경되는 필드를 API에 알려줍니다. 업데이트 요청은 필드 마스크에 지정되지 않은 모든 필드를 무시하고 현재 값을 그대로 둡니다.

업데이트된 메시지에서 필드를 지정하지 않고 마스크에 필드를 추가하여 필드를 설정 해제할 수도 있습니다. 이렇게 하면 필드에 이전에 있던 값이 지워집니다.

업데이트 필드 마스크의 문법은 읽기 필드 마스크와 동일합니다.

다음 예에서는 UpdateShapePropertiesRequest 메서드를 사용하여 도형의 색상 채우기를 DARK1 테마 색상으로 변경하고 도형의 윤곽선을 설정 해제합니다.

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