Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

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

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

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

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

Существует два типа частичных запросов:

Частичный ответ : запрос, в котором вы указываете, какие поля включить в ответ (используйте параметр запроса fields ).
Исправление : запрос на обновление, при котором вы отправляете только те поля, которые хотите изменить (используйте HTTP-команду PATCH ).

Более подробная информация о выполнении частичных запросов представлена в следующих разделах.

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

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

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

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

Пример

В следующем примере показано использование параметра fields с универсальным (вымышленным) «Демо» 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 » в спецификацию fields . Включение объекта данных со спецификацией полей, например data/a/b приводит к ошибке. Вместо этого просто используйте спецификацию fields , например a/b .
Используйте дополнительный селектор, чтобы запросить набор определенных подполей массивов или объектов, помещая выражения в круглые скобки " ( ) ".
Например: fields=items(id,author/email) возвращает только идентификатор элемента и адрес электронной почты автора для каждого элемента массива элементов. Вы также можете указать одно подполе, где fields=items(id) эквивалентны fields=items/id .
При необходимости используйте подстановочные знаки при выборе полей.
Например: fields=items/pagemap/* выбирает все объекты в карте страниц.

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

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

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

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

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

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

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

Патч (частичное обновление)

Вы также можете избежать отправки ненужных данных при изменении ресурсов. Чтобы отправлять обновленные данные только для определенных полей, которые вы меняете, используйте команду HTTP PATCH . Семантика исправлений, описанная в этом документе, отличается (и проще), чем для старой реализации частичного обновления GData.

Короткий пример ниже показывает, как использование патча сводит к минимуму объем данных, которые необходимо отправить для создания небольшого обновления.

Пример

В этом примере показан простой запрос на исправление для обновления только заголовка общего (вымышленного) ресурса API «Демо». Ресурс также имеет комментарий, набор характеристик, статус и многие другие поля, но этот запрос отправляет только поле title , поскольку это единственное поле, которое модифицируется:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Ответ:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

Сервер возвращает код состояния 200 OK вместе с полным представлением обновленного ресурса. Поскольку в запрос на исправление было включено только поле title , это единственное значение, которое отличается от предыдущего.

Примечание. Если вы используете параметр fields частичного ответа в сочетании с патчем, вы можете еще больше повысить эффективность запросов на обновление. Запрос на исправление только уменьшает размер запроса. Частичный ответ уменьшает размер ответа. Поэтому, чтобы уменьшить объем данных, отправляемых в обоих направлениях, используйте запрос исправления с параметром fields .

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

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

Добавить: Чтобы добавить поле, которого еще нет, укажите новое поле и его значение.
Изменить: Чтобы изменить значение существующего поля, укажите поле и установите для него новое значение.
Удалить: Чтобы удалить поле, укажите поле и установите для него значение null . Например, "comment": null . Вы также можете удалить весь объект (если он изменяем), установив для него значение null . Если вы используете клиентскую библиотеку Java API , вместо этого используйте Data.NULL_STRING ; подробности см. в разделе JSON null .

Примечание о массивах: запросы на исправления, содержащие массивы, заменяют существующий массив предоставленным вами. Вы не можете изменять, добавлять или удалять элементы массива по частям.

Использование патча в цикле чтения-изменения-записи

Будет полезно начать с получения частичного ответа с данными, которые вы хотите изменить. Это особенно важно для ресурсов, использующих ETag, поскольку для успешного обновления ресурса необходимо указать текущее значение ETag в HTTP-заголовке If-Match . После получения данных вы можете изменить значения, которые хотите изменить, и отправить измененное частичное представление обратно с запросом на исправление. Вот пример, в котором предполагается, что демонстрационный ресурс использует ETags:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Это частичный ответ:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

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

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

Сервер отвечает кодом состояния HTTP 200 OK и частичным представлением обновленного ресурса:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Создание запроса на исправление напрямую

Для некоторых запросов на исправления вам необходимо основывать их на ранее полученных данных. Например, если вы хотите добавить элемент в массив и не хотите потерять ни один из существующих элементов массива, вы должны сначала получить существующие данные. Аналогично, если API использует ETag, вам необходимо отправить предыдущее значение ETag вместе с вашим запросом, чтобы успешно обновить ресурс.

Примечание. Вы можете использовать HTTP-заголовок "If-Match: *" чтобы принудительно пройти исправление, когда используются ETags. Если вы сделаете это, вам не нужно будет выполнять чтение перед записью.

Однако в других ситуациях вы можете создать запрос на исправление напрямую, без предварительного получения существующих данных. Например, вы можете легко настроить запрос на исправление, который обновляет поле до нового значения или добавляет новое поле. Вот пример:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

При этом запросе, если поле комментария имеет существующее значение, новое значение перезаписывает его; в противном случае ему будет присвоено новое значение. Аналогично, если была характеристика объема, ее значение перезаписывается; если нет, то он создается. Поле точности, если оно установлено, удаляется.

Обработка ответа на патч

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

По этой причине гораздо безопаснее использовать патч. Вы предоставляете данные только для тех полей, которые хотите изменить; поля, которые вы пропускаете, не очищаются. Единственное исключение из этого правила возникает с повторяющимися элементами или массивами: если вы опустите их все, они останутся такими, какие есть; если вы предоставите какой-либо из них, весь набор будет заменен предоставленным вами набором.

Пакетные запросы

В этом документе показано, как группировать вызовы API, чтобы уменьшить количество HTTP-соединений, которые должен выполнить ваш клиент.

Этот документ посвящен пакетному запросу путем отправки HTTP-запроса. Если вместо этого вы используете клиентскую библиотеку Google для выполнения пакетного запроса, см. документацию клиентской библиотеки .

Обзор

Каждое HTTP-соединение, которое создает ваш клиент, приводит к определенным затратам. API Google Диска поддерживает пакетную обработку, что позволяет вашему клиенту помещать несколько вызовов API в один HTTP-запрос.

Примеры ситуаций, когда вы можете использовать пакетную обработку:

Получение метаданных для большого количества файлов.
Массовое обновление метаданных или свойств.
Изменение разрешений для большого количества файлов, например добавление нового пользователя или группы.
Синхронизация данных локального клиента в первый раз или после длительного отсутствия в сети.

В каждом случае вместо отправки каждого вызова отдельно вы можете сгруппировать их в один HTTP-запрос. Все внутренние запросы должны направляться к одному и тому же API Google.

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

Примечание . Пакетная система API Google Диска использует тот же синтаксис, что и система пакетной обработки OData , но семантика отличается.

Дополнительные ограничения включают в себя:

Пакетные запросы с более чем 100 вызовами могут вызвать ошибку.
Длина URL-адреса для каждого внутреннего запроса ограничена 8000 символами.
Google Диск не поддерживает пакетные операции с мультимедиа ни для загрузки, ни для скачивания, ни для экспорта файлов.

Детали партии

Пакетный запрос состоит из нескольких вызовов API, объединенных в один HTTP-запрос, который можно отправить по batchPath указанному в документе обнаружения API . Путь по умолчанию — /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 как во внешнем запросе, так и в отдельном вызове, то значение заголовка отдельного вызова переопределяет значение заголовка внешнего пакетного запроса. Заголовки отдельного вызова применяются только к этому вызову.

Например, если вы предоставляете заголовок авторизации для определенного вызова, этот заголовок применяется только к этому вызову. Если вы предоставляете заголовок авторизации для внешнего запроса, то этот заголовок применяется ко всем отдельным вызовам, если только они не переопределяют его собственными заголовками авторизации.

Когда сервер получает пакетный запрос, он применяет параметры запроса и заголовки внешнего запроса (при необходимости) к каждой части, а затем обрабатывает каждую часть, как если бы это был отдельный HTTP-запрос.

Ответ на пакетный запрос

Ответ сервера представляет собой один стандартный ответ HTTP с multipart/mixed типом контента; каждая часть является ответом на один из запросов в пакетном запросе в том же порядке, что и запросы.

Как и части запроса, каждая часть ответа содержит полный ответ HTTP, включая код состояния, заголовки и тело. И, как и частям запроса, каждой части ответа предшествует заголовок Content-Type , который отмечает начало части.

Если данная часть запроса имела заголовок Content-ID , то соответствующая часть ответа имеет соответствующий заголовок Content-ID , где исходному значению предшествует строка response- , как показано в следующем примере.

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

Пример

В следующем примере показано использование пакетной обработки с помощью Google Drive API.

Пример пакетного запроса

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--

Возвращать определенные поля из запроса

По умолчанию сервер возвращает набор полей ресурсов по умолчанию, специфичный для используемого метода. Например, метод files.list может возвращать только id , name и mimeType . Эти поля могут быть не теми полями, которые вам нужны. Если вам нужно вернуть другие поля, обратитесь к разделу Возврат определенных полей для файла .

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

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

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

Существует два типа частичных запросов:

Частичный ответ : запрос, в котором вы указываете, какие поля включить в ответ (используйте параметр запроса fields ).
Исправление : запрос на обновление, при котором вы отправляете только те поля, которые хотите изменить (используйте HTTP-команду PATCH ).

Более подробная информация о выполнении частичных запросов представлена в следующих разделах.

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

Пример

В следующем примере показано использование параметра fields с универсальным (вымышленным) «Демо» 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",
    ...
  },
  ...
  ]
}

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"
    }
  },
  ...
  ]
}

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

Используйте список, разделенный запятыми, чтобы выбрать несколько полей.
Используйте 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/* выбирает все объекты в карте страниц.

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

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

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

Примеры	Эффект
`items`	Возвращает все элементы массива items, включая все поля в каждом элементе, но не другие поля.
`etag,items`	Возвращает поле `etag` и все элементы массива items.
`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.

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

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"
    }
  },
  ...
  ]
}

Патч (частичное обновление)

Пример

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Ответ:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

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

Добавить: Чтобы добавить поле, которого еще нет, укажите новое поле и его значение.
Изменить: Чтобы изменить значение существующего поля, укажите поле и установите для него новое значение.
Удалить: Чтобы удалить поле, укажите поле и установите для него значение null . Например, "comment": null . Вы также можете удалить весь объект (если он изменяем), установив для него значение null . Если вы используете клиентскую библиотеку Java API , вместо этого используйте Data.NULL_STRING ; подробности см. в разделе JSON null .

Использование патча в цикле чтения-изменения-записи

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Это частичный ответ:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

Сервер отвечает кодом состояния HTTP 200 OK и частичным представлением обновленного ресурса:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Создание запроса на исправление напрямую

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

Обработка ответа на патч

Если запрос на исправление приводит к новому состоянию ресурса, которое является синтаксически или семантически недопустимым, сервер возвращает код состояния HTTP 400 Bad Request или 422 Unprocessable Entity , а состояние ресурса остается неизменным. Например, если вы пытаетесь удалить значение для требуемого поля, сервер возвращает ошибку.

Альтернативная нотация, когда патч HTTP -глагол не поддерживается

Если ваш брандмауэр не разрешает запросы HTTP PATCH , то выполните запрос POST HTTP и установите заголовок переопределения в PATCH , как показано ниже:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

Разница между патчем и обновлением

На практике, когда вы отправляете данные для запроса на обновление, который использует глагол HTTP PUT , вам нужно только отправлять те поля, которые являются либо необходимыми, либо необязательными; Если вы отправляете значения для полей, которые установлены сервером, они игнорируются. Хотя это может показаться еще одним способом сделать частичное обновление, этот подход имеет некоторые ограничения. С помощью обновлений, которые используют PUT HTTP, запрос сбой, если вы не предоставляете требуемые параметры, и он очищает ранее устанавливающие данные, если вы не предоставляете дополнительные параметры.

По этой причине гораздо безопаснее использовать патч. Вы поставляете данные только для поля, которые хотите изменить; Поля, которые вы опускаете, не очищены. Единственное исключение из этого правила происходит с повторяющимися элементами или массивами: если вы опустите их все, они остаются такими, какие они есть; Если вы предоставите какой -либо из них, весь набор заменяется набором, который вы предоставляете.

Партийные запросы

В этом документе показано, как собирать API, чтобы сократить количество HTTP -соединений, которые должен сделать ваш клиент.

Этот документ специально связан с тем, чтобы сделать пакетный запрос путем отправки HTTP -запроса. Если вместо этого вы используете клиентскую библиотеку Google, чтобы сделать пакетный запрос, см. Документацию клиентской библиотеки .

Обзор

Каждое http -соединение, которое ваш клиент дает результаты в определенном количестве накладных расходов. API Google Drive поддерживает партии, чтобы позволить вашему клиенту поместить несколько вызовов API в один HTTP -запрос.

Примеры ситуаций, когда вы можете использовать пакет:

Получение метаданных для большого количества файлов.
Обновление метаданных или свойств в объеме.
Изменение разрешений для большого количества файлов, таких как добавление нового пользователя или группы.
Синхронизация данных локального клиента впервые или после того, как он был офлайн в течение длительного времени.

В каждом случае, вместо того, чтобы отправлять каждый вызов отдельно, вы можете объединить их в один HTTP -запрос. Все внутренние запросы должны перейти в один и тот же Google API.

Вы ограничены 100 звонками в одном партийном запросе. Если вы должны делать больше вызовов, чем это, используйте несколько запросов на пакетный.

ПРИМЕЧАНИЕ . Пакетная система для API Google Drive использует тот же синтаксис, что и система обработки партии ODATA , но семантика отличается.

Дополнительные ограничения включают:

Пакетные запросы с более чем 100 вызовами могут вызвать ошибку.
Есть ограничение в 8000 символов по длине URL -адреса для каждого внутреннего запроса.
Google Drive не поддерживает пакетные операции для медиа, как для загрузки, ни для загрузки, ни для экспорта файлов.

Партийные детали

Пакетный запрос состоит из нескольких вызовов API, объединенных в один HTTP -запрос, который может быть отправлен в batchPath указанный в документе API Discovery . Путь по умолчанию /batch/ api_name / api_version . В этом разделе подробно описывается пакетный синтаксис; Позже есть пример .

ПРИМЕЧАНИЕ . Набор запросов n , пакетный, подсчитывается к вашему лимиту использования в виде запросов n , а не как один запрос. Запрос партии разделен на набор запросов перед обработкой.

Формат пакетного запроса

Пометный запрос - это единственный стандартный HTTP -запрос, содержащий несколько вызовов Google Drive API, используя тип multipart/mixed Content. В рамках этого основного HTTP -запроса каждая из частей содержит вложенный HTTP -запрос.

Каждая часть начинается с собственного Content-Type: application/http http. Он также может иметь дополнительный заголовок Content-ID . Тем не менее, заголовки деталей просто там, чтобы отметить начало части; Они отделены от вложенного запроса. После того, как сервер разворачивает пакетный запрос на отдельные запросы, заголовки деталей игнорируются.

Тело каждой части представляет собой полный HTTP -запрос с собственным глаголом, URL, заголовками и телом. HTTP -запрос должен содержать только часть пути URL; Полные URL -адреса не допускаются в пакетных запросах.

Заголовки HTTP для запроса внешней партии, за исключением заголовков Content- таких как Content-Type , применяются к каждому запросу в партии. Если вы указываете заданный заголовок HTTP как во внешнем запросе, так и в отдельном вызове, то значение заголовка отдельного вызова переопределяет значение заголовка запроса внешней партии. Заголовки для отдельного вызова применяются только к этому вызову.

Например, если вы предоставляете заголовок авторизации для конкретного вызова, этот заголовок относится только к этому вызову. Если вы предоставляете заголовок авторизации для внешнего запроса, то этот заголовок применяется ко всем индивидуальным вызовам, если они не переопределяют его собственными заголовками авторизации.

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

{ "domain":"appsrocks.com", "role":"reader", "type":"domain" } --END_OF_PART--

Пример пакетного ответа

Это ответ на пример запроса в предыдущем разделе.

--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--

Вернуть конкретные поля из запроса

По умолчанию сервер возвращает набор полей ресурсов по умолчанию, специфичные для используемого метода. id name mimeType files.list . Эти поля не могут быть точными полями, которые вам нужны. Если вам нужно вернуть другие поля, обратитесь к возврату конкретных полей для файла .