Улучшить производительность

Сжатие с использованием gzip

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

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

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

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

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

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

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

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

Пример

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

Простой запрос: В этом 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 автора для каждого элемента в массиве items.

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

После обработки сервером корректного запроса, включающего параметр запроса 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 ), используйте эти параметры, чтобы уменьшить размер результатов каждого запроса до приемлемого уровня. В противном случае, преимущества в производительности, достигаемые за счет частичного ответа, могут быть не реализованы.