В этом документе описаны некоторые методы, которые можно использовать для повышения производительности вашего приложения. В некоторых случаях для иллюстрации представленных идей используются примеры из других API или универсальных API. Однако те же самые концепции применимы и к API Google Drive.
Сжатие с использованием gzip
Простой и удобный способ уменьшить пропускную способность, необходимую для каждого запроса, — это включить сжатие gzip. Хотя это требует дополнительного процессорного времени для распаковки результатов, компромисс с сетевыми издержками обычно очень оправдан.
Для получения ответа в формате gzip необходимо выполнить два действия: установить заголовок Accept-Encoding и изменить пользовательский агент таким образом, чтобы он содержал строку gzip . Вот пример правильно сформированных HTTP-заголовков для включения сжатия gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Работа с ограниченными ресурсами
Ещё один способ повысить производительность вызовов API — отправлять и получать только ту часть данных, которая вас интересует. Это позволяет вашему приложению избегать передачи, анализа и хранения ненужных полей, что позволяет более эффективно использовать ресурсы, включая сеть, процессор и память.
Существует два типа частичных запросов:
- Частичный ответ : Запрос, в котором вы указываете, какие поля следует включить в ответ (используйте параметр запроса
fields). - Patch : Запрос на обновление, в котором вы отправляете только те поля, которые хотите изменить (используйте HTTP-метод
PATCH).
Более подробная информация о подаче частичных запросов представлена в следующих разделах.
Частичный ответ
По умолчанию сервер после обработки запросов отправляет полное представление ресурса. Для повышения производительности вы можете попросить сервер отправлять только необходимые поля и получать вместо этого частичный ответ .
Чтобы запросить частичный ответ, используйте параметр запроса fields , чтобы указать поля, которые вы хотите получить. Этот параметр можно использовать с любым запросом, который возвращает данные ответа.
Обратите внимание, что параметр fields влияет только на данные ответа; он не влияет на данные, которые вам необходимо отправить, если таковые имеются. Чтобы уменьшить объем данных, отправляемых при изменении ресурсов, используйте запрос на исправление (patch request).
Патч (частичное обновление)
Также можно избежать отправки ненужных данных при изменении ресурсов. Чтобы отправлять обновленные данные только для конкретных полей, которые вы изменяете, используйте HTTP-метод PATCH . Семантика обновления, описанная в этом документе, отличается (и проще), чем та, что использовалась в более старой реализации частичного обновления в GData.
Приведённый ниже короткий пример показывает, как использование команды patch минимизирует объём данных, необходимых для внесения небольшого обновления.
Пример
Обработка ответа на обновление
После обработки действительного запроса на внесение изменений API возвращает HTTP-ответ с кодом 200 OK а также полное описание измененного ресурса. Если API использует ETags, сервер обновляет значения ETags после успешной обработки запроса на внесение изменений, как и в случае с PUT .
Запрос на исправление возвращает полное представление ресурса, если только вы не используете параметр fields для уменьшения объема возвращаемых данных.
Если запрос на изменение приводит к созданию нового состояния ресурса, которое является синтаксически или семантически некорректным, сервер возвращает HTTP-код состояния 400 Bad Request или 422 Unprocessable Entity , и состояние ресурса остается неизменным. Например, если вы попытаетесь удалить значение для обязательного поля, сервер вернет ошибку.
Альтернативная запись, если HTTP-метод PATCH не поддерживается.
Если ваш брандмауэр не разрешает HTTP-запросы PATCH , выполните HTTP-запрос POST и установите заголовок переопределения в PATCH , как показано ниже:
POST https://www.googleapis.com/... X-HTTP-Method-Override: PATCH ...
Разница между патчем и обновлением.
На практике, при отправке данных в запросе на обновление с использованием HTTP PUT , вам нужно отправлять только те поля, которые являются обязательными или необязательными; если вы отправляете значения для полей, которые задаются сервером, они игнорируются. Хотя это может показаться еще одним способом частичного обновления, у этого подхода есть некоторые ограничения. При обновлениях с использованием HTTP PUT запрос завершается с ошибкой, если вы не указываете обязательные параметры, и очищает ранее установленные данные, если вы не указываете необязательные параметры.
По этой причине использовать функцию patch гораздо безопаснее. Вы указываете данные только для тех полей, которые хотите изменить; поля, которые вы пропускаете, не очищаются. Единственное исключение из этого правила касается повторяющихся элементов или массивов: если вы пропускаете все из них, они остаются как есть; если вы указываете хотя бы один из них, весь набор заменяется тем набором, который вы указали.
Пакетные запросы
В этом документе показано, как объединять вызовы API в пакеты, чтобы уменьшить количество HTTP-соединений, которые должен устанавливать ваш клиент.
Этот документ посвящен выполнению пакетных запросов путем отправки HTTP-запроса. Если же вы используете клиентскую библиотеку Google для выполнения пакетных запросов, обратитесь к документации этой библиотеки .
Обзор
Каждое HTTP-соединение, устанавливаемое вашим клиентом, приводит к определенным накладным расходам. API Google Drive поддерживает пакетную обработку, позволяя вашему клиенту объединять несколько вызовов API в один HTTP-запрос.
Примеры ситуаций, когда может потребоваться пакетная обработка:
- Получение метаданных для большого количества файлов.
- Массовое обновление метаданных или свойств.
- Изменение прав доступа к большому количеству файлов, например, добавление нового пользователя или группы.
- Синхронизация локальных данных клиента впервые или после длительного пребывания в автономном режиме.
В каждом случае, вместо отправки каждого вызова по отдельности, вы можете объединить их в один HTTP-запрос. Все внутренние запросы должны направляться к одному и тому же API Google.
В одном пакетном запросе вы можете совершить не более 100 вызовов. Если вам необходимо совершить больше вызовов, используйте несколько пакетных запросов.
Примечание : Система пакетной обработки для API Google Drive использует тот же синтаксис, что и система пакетной обработки OData , но семантика отличается.
К дополнительным ограничениям относятся:
- Пакетные запросы, содержащие более 100 вызовов, могут привести к ошибке.
- Длина URL-адреса для каждого внутреннего запроса ограничена 8000 символами.
- Google Drive не поддерживает пакетную обработку медиафайлов, ни для загрузки, ни для скачивания, ни для экспорта файлов.
Детали партии
Пакетный запрос состоит из нескольких вызовов API, объединенных в один HTTP-запрос, который может быть отправлен по batchPath указанному в документе обнаружения API . Путь по умолчанию — /batch/ api_name / api_version . В этом разделе подробно описан синтаксис пакетного запроса; далее приведен пример .
Примечание : Пакет из n запросов, объединенных вместе, учитывается в вашем лимите использования как n запросов, а не как один запрос. Пакет запросов разбивается на несколько отдельных запросов перед обработкой.
Формат пакетного запроса
Пакетный запрос — это один стандартный HTTP-запрос, содержащий несколько вызовов API Google Drive с использованием типа содержимого multipart/mixed . Внутри этого основного HTTP-запроса каждая из его частей содержит вложенный HTTP-запрос.
Каждая часть начинается со своего HTTP-заголовка Content-Type: application/http . Она также может содержать необязательный заголовок Content-ID . Однако заголовки частей служат лишь для обозначения начала части; они отделены от вложенного запроса. После того, как сервер разделит пакетный запрос на отдельные запросы, заголовки частей игнорируются.
Тело каждой части запроса представляет собой полный HTTP-запрос, содержащий собственный глагол, URL-адрес, заголовки и сам запрос. HTTP-запрос должен содержать только путь к URL-адресу; полные URL-адреса в пакетных запросах не допускаются.
HTTP-заголовки для внешнего пакетного запроса, за исключением заголовков Content- , таких как Content-Type , применяются ко всем запросам в пакете. Если вы указываете определенный HTTP-заголовок как во внешнем запросе, так и в отдельном вызове, то значение заголовка отдельного вызова переопределяет значение заголовка внешнего пакетного запроса. Заголовки для отдельного вызова применяются только к этому вызову.
Например, если вы предоставляете заголовок Authorization для конкретного вызова, то этот заголовок применяется только к этому вызову. Если вы предоставляете заголовок Authorization для внешнего запроса, то этот заголовок применяется ко всем отдельным вызовам, если только они не переопределят его своими собственными заголовками Authorization.
Когда сервер получает пакетный запрос, он применяет параметры запроса и заголовки внешнего запроса (при необходимости) к каждой его части, а затем обрабатывает каждую часть так, как если бы это был отдельный HTTP-запрос.
Ответ на пакетный запрос
Ответ сервера представляет собой единый стандартный HTTP-ответ с типом содержимого multipart/mixed ; каждая часть является ответом на один из запросов в пакете, в том же порядке, что и запросы.
Подобно частям запроса, каждая часть ответа содержит полный HTTP-ответ, включая код состояния, заголовки и тело. И, как и в случае с частями запроса, каждой части ответа предшествует заголовок Content-Type , который отмечает начало этой части.
Если определенная часть запроса содержала заголовок Content-ID , то соответствующая часть ответа имеет совпадающий заголовок Content-ID , причем исходное значение предваряется строкой response- , как показано в следующем примере.
Примечание : Сервер может выполнять ваши вызовы в любом порядке. Не рассчитывайте на то, что они будут выполнены в том порядке, в котором вы их указали. Если вы хотите гарантировать выполнение двух вызовов в заданном порядке, вы не можете отправить их в одном запросе; вместо этого отправьте первый вызов отдельно, затем дождитесь ответа на первый вызов, прежде чем отправлять второй.
Пример
В следующем примере показано использование пакетной обработки данных с помощью API Google Drive.
Пример пакетного запроса
POST https://www.googleapis.com/batch/drive/v3 Accept-Encoding: gzip User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip) Content-Type: multipart/mixed; boundary=END_OF_PART Content-Length: 963--END_OF_PART Content-Length: 337 Content-Type: application/http content-id: 1 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id Authorization: Bearer authorization_token Content-Length: 70 Content-Type: application/json; charset=UTF-8
{ "emailAddress":"example@appsrocks.com", "role":"writer", "type":"user" } --END_OF_PART Content-Length: 353 Content-Type: application/http content-id: 2 content-transfer-encoding: binary
POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false Authorization: Bearer authorization_token Content-Length: 58 Content-Type: application/json; charset=UTF-8
{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--
Пример пакетного ответа
Это ответ на пример запроса из предыдущего раздела.
HTTP/1.1 200 OK Alt-Svc: quic=":443"; p="1"; ma=604800 Server: GSE Alternate-Protocol: 443:quic,p=1 X-Frame-Options: SAMEORIGIN Content-Encoding: gzip X-XSS-Protection: 1; mode=block Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk Transfer-Encoding: chunked X-Content-Type-Options: nosniff Date: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Vary: X-Origin Vary: Origin Expires: Fri, 13 Nov 2015 19:28:59 GMT--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-1
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "12218244892818058021i" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk Content-Type: application/http Content-ID: response-2
HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 Date: Fri, 13 Nov 2015 19:28:59 GMT Expires: Fri, 13 Nov 2015 19:28:59 GMT Cache-Control: private, max-age=0 Content-Length: 35
{ "id": "04109509152946699072k" }
--batch_6VIxXCQbJoQ_AATxy_GgFUk--
Возвращает определенные поля из запроса.
Если параметр fields не указан, сервер возвращает набор полей по умолчанию, специфичных для данного метода. Например, метод files.list возвращает только поля kind , id , name и mimeType .
Возвращаемые по умолчанию поля могут не соответствовать вашим потребностям. Если вы хотите указать, какие поля следует вернуть в ответе, используйте системный параметр fields . Дополнительную информацию см. в разделе «Возвращение определенных полей» .
Для всех методов ресурсов about , comments (кроме delete ) и replies (кроме delete ) необходимо задать параметр fields . Эти методы не возвращают набор полей по умолчанию.