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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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