Повысить производительность

В этом документе рассматриваются некоторые методы, которые можно использовать для повышения производительности вашего приложения. В некоторых случаях для иллюстрации представленных идей используются примеры из других API или универсальных API. Однако те же концепции применимы и к API Google Таблиц.

Сжатие с помощью gzip

Простой и удобный способ сократить пропускную способность, необходимую для каждого запроса, — включить сжатие gzip. Хотя это требует дополнительного процессорного времени для распаковки результатов, компромисс с сетевыми затратами обычно оправдывает себя.

Чтобы получить ответ, закодированный с помощью gzip, необходимо выполнить два действия: установить заголовок Accept-Encoding и изменить пользовательский агент, добавив строку gzip . Вот пример правильно сформированных HTTP-заголовков для включения сжатия gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Работа с частичными ресурсами

Еще один способ повысить производительность вызовов API — запрашивать только ту часть данных, которая вам интересна. Это позволяет приложению избежать передачи, анализа и хранения ненужных полей, что позволяет ему более эффективно использовать ресурсы, включая сеть, ЦП и память.

Частичный ответ

По умолчанию сервер отправляет полное представление ресурса после обработки запросов. Для повышения производительности вы можете попросить сервер отправлять только те поля, которые вам действительно нужны, и вместо этого получать частичный ответ .

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

Пример

В следующем примере показано использование параметра fields с универсальным (вымышленным) «Demo» API.

Простой запрос: этот HTTP-запрос GET пропускает параметр fields и возвращает полный ресурс.

https://www.googleapis.com/demo/v1

Полный ответ о ресурсе: Полные данные о ресурсе включают в себя следующие поля, а также многие другие, которые были опущены для краткости.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

Запрос частичного ответа: Следующий запрос к этому же ресурсу использует параметр fields для значительного сокращения объема возвращаемых данных.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Частичный ответ: в ответ на запрос, указанный выше, сервер отправляет ответ, содержащий только информацию о типе вместе с урезанным массивом элементов, который включает только заголовок HTML и информацию о характеристиках длины для каждого элемента.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Обратите внимание, что ответ представляет собой объект JSON, который включает только выбранные поля и содержащие их родительские объекты.

Далее будут рассмотрены подробности форматирования параметра fields , а затем — более подробная информация о том, что именно возвращается в ответе.

Сводка синтаксиса параметров полей

Формат значения параметра запроса fields в некоторой степени основан на синтаксисе XPath. Поддерживаемый синтаксис описан ниже, а дополнительные примеры приведены в следующем разделе.

• Для выбора нескольких полей используйте список, разделенный запятыми.
• Используйте a/b для выбора поля b , вложенного в поле a ; используйте a/b/c для выбора поля c вложенного в b .
  

  Исключение: для ответов API, использующих обёртки "data", где ответ вложен в объект data , который выглядит как data: { ... } , не включайте " data " в спецификацию fields . Включение объекта данных вместе со спецификацией полей, например data/a/b приведёт к ошибке. Вместо этого используйте просто спецификацию fields , например, a/b .

• Используйте подселектор для запроса набора определенных подполей массивов или объектов, поместив выражения в скобки « ( ) ».

  Например, fields=items(id,author/email) возвращает только идентификатор элемента и адрес электронной почты автора для каждого элемента массива items. Вы также можете указать одно подполе, где fields=items(id) эквивалентно fields=items/id .

• При необходимости используйте подстановочные знаки при выборе полей.

  Например: fields=items/pagemap/* выбирает все объекты на карте страницы.

Дополнительные примеры использования параметра fields

Примеры ниже содержат описания того, как значение параметра fields влияет на ответ.

Примечание: Как и все значения параметров запроса, значение параметра fields должно быть закодировано в URL. Для удобства чтения в примерах в этом документе кодировка не указана.

Определите поля, которые вы хотите вернуть, или сделайте выбор полей .

Значение параметра запроса fields представляет собой список полей, разделённых запятыми, и каждое поле указывается относительно корня ответа. Таким образом, при выполнении операции со списком ответ представляет собой коллекцию, которая обычно включает массив ресурсов. Если выполняется операция, возвращающая один ресурс, поля указываются относительно этого ресурса. Если выбранное вами поле является массивом (или является его частью), сервер возвращает выбранную часть всех элементов массива.

Вот несколько примеров на уровне коллекций:

Примеры	Эффект
items	Возвращает все элементы массива items, включая все поля в каждом элементе, но не включает другие поля.
etag,items	Возвращает как поле etag , так и все элементы в массиве items.
items/title	Возвращает только поле title для всех элементов массива items. При возврате вложенного поля ответ включает в себя родительские объекты, которые его содержат. Родительские поля не включают в себя никакие другие дочерние поля, если только они не выбраны явно.
context/facets/label	Возвращает только поле label для всех членов массива facets , который сам по себе вложен в объект context .
items/pagemap/*/title	Для каждого элемента массива items возвращает только поле title (если оно есть) всех объектов, являющихся дочерними элементами pagemap .

Вот несколько примеров на уровне ресурсов:

Примеры	Эффект
title	Возвращает поле title запрошенного ресурса.
author/uri	Возвращает подполе uri объекта author в запрошенном ресурсе.
links/*/href	Возвращает поле href всех объектов, являющихся дочерними элементами links .

Запросите только части определенных полей, используя подвыборки .

По умолчанию, если в запросе указаны определённые поля, сервер возвращает объекты или элементы массива целиком. Вы можете указать ответ, включающий только определённые подполя. Это можно сделать, используя синтаксис подвыборки « ( ) », как в примере ниже.

Пример	Эффект
items(title,author/uri)	Возвращает только значения title и uri автора для каждого элемента в массиве элементов.

Обработка частичных ответов

После обработки сервером корректного запроса, включающего параметр запроса fields , он возвращает код статуса HTTP 200 OK вместе с запрошенными данными. Если параметр запроса fields содержит ошибку или недействителен по какой-либо другой причине, сервер возвращает код статуса HTTP 400 Bad Request вместе с сообщением об ошибке, сообщающим пользователю о причине ошибки в выборе полей (например, "Invalid field selection a/b" ).

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

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Частичный ответ выглядит так:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Примечание: Для API, поддерживающих параметры запросов для пагинации данных (например, maxResults и nextPageToken ), используйте эти параметры, чтобы уменьшить размер результатов каждого запроса до приемлемого. В противном случае выигрыш в производительности, возможный при частичном ответе, может быть не реализован.