필드 마스크를 사용하면 API 호출자가 요청이 반환하거나 업데이트해야 하는 필드를 나열할 수 있습니다. FieldMask를 사용하면 API에서 불필요한 작업을 피하고 성능을 개선할 수 있습니다. 필드 마스크는 Google Docs API의 read 및 update 메서드에 모두 사용됩니다.
필드 마스크를 사용하여 읽기
문서는 클 수 있으며, 종종 읽기 요청에서 반환된 Document 리소스의 모든 부분이 필요하지는 않습니다. fields URL 매개변수를 사용하여 Docs API 응답에서 반환되는 항목을 제한할 수 있습니다. 최상의 성능을 위해 답장에 필요한 필드만 명시적으로 나열하세요.
필드 매개변수의 형식은 FieldMask의 JSON 인코딩과 동일합니다. 간단히 말해 다른 여러 필드는 쉼표로 구분되고 하위 필드는 점으로 구분됩니다. 필드 이름은 camelCase 또는 밑줄로_구분하여 지정할 수 있습니다. 편의상 동일한 유형의 여러 하위 필드를 괄호 안에 나열할 수 있습니다.
다음 documents.get 요청 예에서는 title,body.content(paragraph),revisionId 필드 마스크를 사용하여 문서의 title, Body 객체의 Paragraph, 문서 내 문서의 revisionId를 가져옵니다.
GET https://docs.googleapis.com/v1/documents/documentId?fields=title,body.content(paragraph),revisionId
이 메서드 호출에 대한 응답은 필드 마스크에서 요청된 구성요소를 포함하는 Document 객체입니다.
{
"title": ""TITLE",
"body": {
"content": [
{},
{
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 59,
"textRun": {
"content": ""CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
"revisionId": "REVISION_ID"
}
필드 마스크를 사용하여 업데이트
객체의 특정 필드만 업데이트하고 다른 필드는 변경하지 않고 그대로 두어야 하는 경우가 있습니다. documents.batchUpdate 작업 내 업데이트 요청은 필드 마스크를 사용하여 변경되는 필드를 API에 알립니다. 업데이트 요청은 필드 마스크에 지정되지 않은 필드를 무시하고 현재 값을 유지합니다.
업데이트된 메시지에 필드를 지정하지 않고 마스크에 필드를 추가하여 필드 설정을 해제할 수도 있습니다. 이렇게 하면 이전에 필드에 있던 값이 삭제됩니다.
업데이트 필드 마스크 구문은 읽기 필드 마스크와 동일합니다.
다음 예에서는 UpdateTextStyleRequest를 사용하여 문서 내 'Google Docs API'의 스타일을 range 5~20 내에서 굵게 표시합니다.
POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
"title": "TITLE",
"body": {
"content": [
{
"endIndex": 1,
"sectionBreak": {
"sectionStyle": {
"columnSeparatorStyle": "NONE",
"contentDirection": "LEFT_TO_RIGHT",
"sectionType": "CONTINUOUS"
}
}
},
{
"startIndex": 1,
"endIndex": 59,
"paragraph": {
"elements": [
{
"startIndex": 1,
"endIndex": 5,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
},
{
"startIndex": 5,
"endIndex": 20,
"textRun": {
"content": "CONTENT",
"textStyle": {
"bold": true
}
}
},
{
"startIndex": 20,
"endIndex": 59,
"textRun": {
"content": "CONTENT",
"textStyle": {}
}
}
],
"paragraphStyle": {
"namedStyleType": "NORMAL_TEXT",
"direction": "LEFT_TO_RIGHT"
}
}
}
]
},
{
... // style details
},
"revisionId": "REVISION_ID",
"suggestionsViewMode": "SUGGESTIONS_INLINE",
"documentId": "DOCUMENT_ID"
}