В этом документе рассматриваются некоторые методы повышения производительности вашего приложения. В некоторых случаях для иллюстрации представленных идей используются примеры из других API или универсальных API. Однако те же концепции применимы и к API Google Диска.
Сжатие с помощью gzip
Простой и удобный способ сократить пропускную способность, необходимую для каждого запроса, — включить сжатие gzip. Хотя это требует дополнительного процессорного времени для распаковки результатов, компромисс с сетевыми затратами обычно оправдывает себя.
Чтобы получить ответ, закодированный с помощью gzip, необходимо выполнить два действия: установить заголовок Accept-Encoding и изменить пользовательский агент, добавив строку gzip . Вот пример правильно сформированных HTTP-заголовков для включения сжатия gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Работа с частичными ресурсами
Еще один способ повысить производительность вызовов API — отправлять и получать только ту часть данных, которая вам интересна. Это позволяет приложению избегать передачи, анализа и хранения ненужных полей, что позволяет ему более эффективно использовать ресурсы, включая сеть, ЦП и память.
Существует два типа частичных запросов:
- Частичный ответ : запрос, в котором вы указываете, какие поля следует включить в ответ (используйте параметр запроса
fields). - Patch : запрос на обновление, при котором вы отправляете только те поля, которые хотите изменить (используйте HTTP-команду
PATCH).
Более подробная информация о подаче частичных запросов представлена в следующих разделах.
Частичный ответ
По умолчанию сервер отправляет полное представление ресурса после обработки запросов. Для повышения производительности вы можете попросить сервер отправлять только те поля, которые вам действительно нужны, и вместо этого получать частичный ответ .
Чтобы запросить частичный ответ, используйте параметр запроса fields , чтобы указать поля, которые нужно вернуть. Этот параметр можно использовать с любым запросом, возвращающим данные ответа.
Обратите внимание, что параметр fields влияет только на данные ответа; он не влияет на данные, которые необходимо отправить, если таковые имеются. Чтобы сократить объём данных, отправляемых при изменении ресурсов, используйте запрос на исправление .
Пример
Патч (частичное обновление)
Вы также можете избежать отправки ненужных данных при изменении ресурсов. Чтобы отправлять обновлённые данные только для тех полей, которые вы изменяете, используйте HTTP-команду PATCH . Семантика патча, описанная в этом документе, отличается (и проще), чем в старой реализации частичного обновления в GData.
Короткий пример ниже показывает, как использование патча минимизирует объем данных, которые необходимо отправить для выполнения небольшого обновления.
Пример
Обработка ответа на патч
После обработки корректного запроса на исправление API возвращает HTTP-код ответа 200 OK вместе с полным представлением изменённого ресурса. Если API использует ETag, сервер обновляет значения ETag после успешной обработки запроса на исправление, как это происходит с 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 Диска поддерживает пакетную обработку, что позволяет вашему клиенту объединять несколько вызовов API в один HTTP-запрос.
Примеры ситуаций, когда вам может понадобиться использовать пакетную обработку:
- Извлечение метаданных для большого количества файлов.
- Массовое обновление метаданных или свойств.
- Изменение прав доступа для большого количества файлов, например добавление нового пользователя или группы.
- Синхронизация локальных данных клиента в первый раз или после длительного отсутствия доступа к сети.
В каждом случае, вместо того, чтобы отправлять каждый вызов по отдельности, вы можете объединить их в один HTTP-запрос. Все внутренние запросы должны быть направлены к одному и тому же API Google.
Количество вызовов в одном пакетном запросе ограничено 100. Если вам необходимо сделать больше вызовов, используйте несколько пакетных запросов.
Примечание : пакетная система для API Google Drive использует тот же синтаксис, что и система пакетной обработки OData , но семантика отличается.
Дополнительные ограничения включают в себя:
- Пакетные запросы с более чем 100 вызовами могут вызвать ошибку.
- Длина URL-адреса для каждого внутреннего запроса ограничена 8000 символами.
- Google Drive не поддерживает пакетные операции с медиафайлами, ни загрузку, ни скачивание, ни экспорт файлов.
Подробности партии
Пакетный запрос состоит из нескольких вызовов API, объединённых в один HTTP-запрос, который можно отправить по batchPath указанному в документе API Discovery . Путь по умолчанию — /batch/ api_name / api_version . В этом разделе подробно описан синтаксис пакетного запроса; далее будет приведён пример .
Примечание : набор из n запросов, объединённых в пакет, учитывается в вашем лимите использования как n запросов, а не как один запрос. Пакетный запрос разделяется на набор запросов перед обработкой.
Формат пакетного запроса
Пакетный запрос — это один стандартный HTTP-запрос, содержащий несколько вызовов API Google Диска с использованием типа контента 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 . Эти методы не возвращают набор полей по умолчанию.