Используйте маски полей

Маски полей позволяют вызывающим API перечислить поля, которые должен вернуть или обновить запрос. Использование FieldMask позволяет API избежать ненужной работы и повышает производительность. Маска поля используется как для методов чтения, так и для методов обновления в API Google Docs.

Читать с полевой маской

Документы могут быть большими, и часто вам не нужна вся часть ресурса Document возвращаемого запросом на чтение. Вы можете ограничить количество возвращаемых данных в ответе API Docs, используя параметр URL fields . Для достижения наилучшей производительности явно перечисляйте в ответе только необходимые поля .

Формат параметра fields совпадает с JSON-кодировкой FieldMask . Если коротко, несколько различных полей разделяются запятыми, а подполя — точками. Имена полей можно указывать в верблюжьем регистре или с использованием подчёркивания . Для удобства несколько подполей одного типа можно заключить в скобки.

В следующем примере запроса documents.get используется маска поля title,tabs(documentTab(body.content(paragraph))),revisionId для извлечения title документа, Paragraph объекта Body (из всех вкладок) и revisionId документа в документе:

GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId

Ответом на вызов этого метода является объект Document содержащий компоненты, запрошенные в маске поля:

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {},
            {
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

Обновление с маской поля

Иногда требуется обновить только определённые поля объекта, оставив остальные поля без изменений. Запросы на обновление внутри операции documents.batchUpdate используют маски полей, чтобы сообщить API, какие поля изменяются. Запрос на обновление игнорирует все поля, не указанные в маске, оставляя их с текущими значениями.

Вы также можете сбросить значение поля, не указывая его в обновлённом сообщении, а добавив поле в маску. Это удалит любое предыдущее значение поля.

Синтаксис обновления масок полей такой же, как и для чтения масок полей.

В следующем примере метод UpdateTextStyleRequest используется для выделения слов «API Google Docs» в документе полужирным шрифтом в range от 5 до 20:

POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID",
  "tabs": [
    {
      "documentTab": {
        "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
        },
      }
    }
  ],
}