Здесь описано, как можно повысить эффективность приложения. В некоторых случаях используются примеры из общих и других API, однако те же принципы применимы и к Google Forms API.
Сжатие с помощью 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)
Частичный ответ. В ответ на указанный выше запрос сервер отправляет только информацию о поле kind и массив парных данных items, включающих только заголовки HTML и сведения о длине.
200 OK
{
"kind": "demo",
"items": [{
"title": "First title",
"characteristics": {
"length": "short"
}
}, {
"title": "Second title",
"characteristics": {
"length": "long"
}
},
...
]
}Обратите внимание на то, что ответ представляет собой объект JSON, включающий только выбранные поля и их родительские объекты.
Далее рассказывается о форматировании параметра fields, а также более подробно рассматривается содержание ответа.
Краткая информация о синтаксисе параметра fields
Формат значения параметра запроса fields основан на синтаксисе XPath. Его основные принципы перечислены ниже. В следующем разделе также представлены дополнительные примеры.
- Чтобы выбрать несколько полей, перечислите их через запятую.
- Формат
a/bпозволяет выбрать полеb, вложенное в полеa, а форматa/b/c– полеc, вложенное в полеb.
Исключение. Для ответов API, в которых используются контейнеры
data(то есть ответ вложен в объектdata: { ... }), не включайте объектdataв спецификациюfields, напримерdata/a/b, так как это приведет к ошибке. Вместо этого примените спецификациюfieldsвидаa/b. - Используйте подселектор, чтобы запросить набор определенных подполей массивов или объектов. Для этого поместите выражения в скобки: "
( )".Пример:
fields=items(id,author/email)возвращает только адреса электронной почты авторов и идентификаторы всех элементов в массиве. Вы также можете указать одно подполе, гдеfields=items(id)эквивалентноfields=items/id. - При выборе полей можно использовать подстановочные знаки.
Пример:
fields=items/pagemap/*выбирает все объекты, содержащиеся в данных формата PageMap.
Другие примеры использования параметра fields
Из следующих примеров видно, как значение параметра fields влияет на ответ.
Примечание. Как и все остальные значения параметров запроса, значение fields должно быть закодировано. В целях наглядности в приведенных здесь примерах кодировка не используется.
- Определите, какие поля вы хотите получить, или выберите их.
- Значение параметра
fieldsпредставляет собой список разделенных запятыми полей, каждое из которых определено относительно корневой части запроса. Таким образом, при выполнении операции list ответ будет представлять собой коллекцию, которая обычно содержит массив ресурсов. Если вы выполняете операцию, возвращающую один ресурс, поля необходимо определить относительно него. Если выбранное поле представляет собой массив или входит в него, сервер возвращает выбранную часть всех элементов массива.
Несколько примеров на уровне коллекций:
Примеры Результат itemsВозвращает все элементы из массива items, в том числе все поля для каждого элемента, но не другие поля. etag,itemsВозвращает поле etagи все элементы массива.items/titleВозвращает только поле titleдля всех элементов массива.
При возврате вложенного поля в ответ включаются также его родительские объекты. Если для родительского объекта явным образом не выбраны другие дочерние поля, они не возвращаются.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), можно использовать такие параметры для сокращения числа результатов по каждому запросу. В остальных случаях применение частичных ответов может не дать никаких преимуществ.