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

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

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

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

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

В приведенном ниже примере запроса 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 , содержащий компоненты, запрошенные в поле mask:

{
  "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, какие поля изменяются. Запрос на обновление игнорирует любые поля, не указанные в маске поля, оставляя их с текущими значениями.

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

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

Маска поля, обозначенная символом * , рассматривается как подстановочный знак и является сокращенным способом указания каждого поля в сообщении. Синтаксис подстановочных знаков может привести к нежелательным результатам при будущем обновлении API, поскольку поля только для чтения и вновь добавленные поля могут вызывать ошибки. В производственных приложениях всегда указывайте конкретные обновляемые поля в масках полей и избегайте использования подстановочных знаков * .

В следующем примере используется метод UpdateTextStyleRequest для выделения текста "Google Docs API" жирным шрифтом в 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
        },
      }
    }
  ],
}