필드 마스크 작업

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

필드 마스크를 사용하여 읽기

프레젠테이션은 크며, 대개 읽기 요청에 의해 반환되는 프레젠테이션의 모든 부분이 필요하지는 않습니다. fields URL 매개변수를 사용하여 Slides API 응답에서 반환되는 부분을 제한할 수 있습니다. 최적의 성능을 얻으려면, 응답에 필요한 필드만 명시적으로 나열하면 됩니다.

필드 매개변수의 형식은 FieldMask의 JSON 인코딩과 동일합니다. 간단히 말하면, 서로 다른 복수의 필드는 쉼표로 구분되며 하위 필드는 점으로 구분됩니다. 필드 이름은 대문자로 구분(camelCase)하거나 밑줄로_구분하는 방식으로 지정할 수 있습니다. 편의상 동일 유형의 여러 하위 필드를 괄호 안에 나열할 수 있습니다.

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

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

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

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "i0",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "i1",
          "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에게 변경 중인 필드를 알려줍니다. 해당 업데이트 요청은 필드 마스크에 지정되지 않은 필드는 무시하고 현재 값을 그대로 둡니다.

또한 업데이트된 메시지에서 필드를 지정하는 대신에 필드 마스크에 필드를 추가하여 필드 설정을 해제할 수도 있습니다. 그러면 이전 필드 값이 삭제됩니다.

업데이트 필드 마스크에 대한 구문은 읽기 필드 마스크와 동일합니다. 또한 * 필드 마스크는 와일드카드로 취급되고 메시지에서 모든 필드를 지정하는 간편한 방법입니다.

다음 예시는 updateShapeProperties 요청을 사용하여 도형의 색 채우기를 DARK1 테마 색으로 변경하고 도형의 윤곽선 설정을 해제합니다.

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": elementId,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}

다음에 대한 의견 보내기...

도움이 필요하시나요? 지원 페이지를 방문하세요.