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

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

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

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

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

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

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

Пример

В следующем примере показано использование параметра fields с API Display & Video 360.

Простой запрос: этот HTTP-запрос GET опускает параметр fields и возвращает полный ресурс.

GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1

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

200 OK

{
 "advertisers": [
  {
   "name": "advertisers/1",
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  {
   "name": "advertisers/2",
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2",
   "entityStatus": "ENTITY_STATUS_ACTIVE",
   "updateTime": "2019-01-01T00:00:00.000000Z",
   "generalConfig": {
    "domainUrl": "http://example.com",
    "timeZone": "America/New_York",
    "currencyCode": "USD",
    "address": {
    }
   },
   "adServerConfig": {
    "thirdPartyOnlyConfig": {
    }
   },
   "creativeConfig": {
   },
   "dataAccessConfig": {
    "sdfConfig": {
     "sdfConfig": {
      "version": "VERSION_3_1"
     }
    }
   },
   "integrationDetails": {
   }
  },
  ...
 ],
 "nextPageToken": "..."
}

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

GET https://displayvideo.googleapis.com/v4/advertisers?partnerId=1&fields=advertisers(advertiserId,partnerId,displayName)

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

200 OK

{
 "advertisers": [
  {
   "advertiserId": "1",
   "partnerId": "1",
   "displayName": "Example Advertiser 1"
  },
  {
   "advertiserId": "2",
   "partnerId": "1",
   "displayName": "Example Advertiser 2"
  },
  ...
 ]
}

Обратите внимание, что ответ представляет собой объект JSON, который включает только выбранные поля и включающие их родительские объекты.

Подробности о форматировании параметра fields рассматриваются далее, а затем более подробная информация о том, что именно возвращается в ответе.

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

Формат значения параметра запроса fields во многом основан на синтаксисе XPath. Поддерживаемый синтаксис кратко описан ниже, а дополнительные примеры приведены в следующем разделе.

Используйте список, разделенный запятыми, чтобы выбрать несколько полей.
Используйте a/b , чтобы выбрать поле b , вложенное в поле a ; используйте a/b/c , чтобы выбрать поле c вложенное в b .
Используйте дополнительный селектор, чтобы запросить набор определенных подполей массивов или объектов, помещая выражения в круглые скобки " ( ) ".
Например: fields=advertisers(advertiserId,generalConfig/domainUrl) возвращает только идентификатор рекламодателя и URL-адрес домена для каждого элемента массива рекламодателей. Вы также можете указать одно подполе, где fields=advertisers(advertiserId) эквивалентны fields=advertisers/advertiserId .

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

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

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

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

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

Пример	Эффект
`advertisers`	Возвращает все элементы массива `advertisers` , включая все поля в каждом элементе, но не другие поля.
`advertisers,nextPageToken`	Возвращает поле `nextPageToken` и все элементы массива `advertisers` .
`advertisers/advertiserId`	Возвращает только `advertiserId` для всех элементов массива `advertisers` . Всякий раз, когда возвращается вложенное поле, ответ включает в себя включающие его родительские объекты. Родительские поля не включают в себя другие дочерние поля, если они также не выбраны явно.
`advertisers/generalConfig/domainUrl`	Возвращает поле `domainUrl` для объекта `generalConfig` , который сам вложен в массив `advertisers` .

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

Пример	Эффект
`advertiserId`	Возвращает поле `advertiserId` запрошенного ресурса.
`generalConfig/domainUrl`	Возвращает поле `domainUrl` для объекта `generalConfig` в запрошенном ресурсе.

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

По умолчанию, если в вашем запросе указаны определенные поля, сервер возвращает объекты или элементы массива целиком. Вы можете указать ответ, который включает только определенные подполя. Вы делаете это, используя синтаксис подвыбора " ( ) ", как в примере ниже.

Пример	Эффект
`advertisers(advertiserId,generalConfig/domainUrl)`	Возвращает только значения `advertiserId` и GeneralConfig `domainUrl` для каждого элемента массива `advertisers` .

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

После того как сервер обрабатывает действительный запрос, включающий параметр запроса fields , он отправляет обратно код состояния HTTP 200 OK вместе с запрошенными данными. Если в параметре запроса fields есть ошибка или он недействителен по другой причине, сервер возвращает код состояния HTTP 400 Bad Request вместе с сообщением об ошибке, сообщающим, что было неправильно с выбором полей (например, "Invalid field selection a/b" ).