Маски полей — это способ для вызывающих API перечислить поля, которые запрос должен вернуть или обновить. Использование FieldMask позволяет API избежать ненужной работы и повышает производительность. Маска поля используется как для методов чтения, так и для методов обновления в API Документов Google.
Чтение с маской поля
Документы могут быть большими, и часто вам не нужна каждая часть ресурса Document , возвращаемая запросом на чтение. Вы можете ограничить то, что возвращается в ответе API Документов, используя параметр URL- fields . Для повышения производительности явно указывайте в ответе только те поля, которые вам нужны .
Формат параметра полей такой же, как кодировка JSON FieldMask . Короче говоря, несколько различных полей разделяются запятыми, а подполя — точкой. Имена полей могут быть указаны в CamelCase или Separated_by_underscores . Для удобства несколько подполей одного типа можно указать в круглых скобках.
В следующем примере запроса documents.get используется маска поля title,body.content(paragraph),revisionId для получения title документа, объекта « Paragraph Body и идентификатора 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"
}