Использование REST для вызова API

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

В этом документе описывается, как использовать JSON API пользовательского поиска.

Сделать запрос

REST, или передача репрезентативного состояния , в JSON API пользовательского поиска несколько отличается от традиционного REST. Вместо предоставления доступа к ресурсам API предоставляет доступ к службе. В результате API предоставляет единый URI, который действует как конечная точка службы.

Вы можете получить результаты для определенного поиска, отправив HTTP- GET на его URI. Вы передаете детали поискового запроса в качестве параметров запроса. Формат URI пользовательского поиска JSON API:

https://www.googleapis.com/customsearch/v1?[parameters]

Для каждого поискового запроса требуются три запроса [parameters] :

  • Ключ API . Используйте key параметр запроса для идентификации вашего приложения .

  • Идентификатор программируемой поисковой системы — используйте cx , чтобы указать программируемую поисковую систему, которую вы хотите использовать для выполнения этого поиска. Поисковая система должна быть создана с помощью Панели управления . Примечание. Идентификатор поисковой системы (cx) может иметь другой формат (например, 8ac1ab64606d234f1).

  • Поисковый запрос — используйте параметр запроса q , чтобы указать поисковое выражение.

Все остальные параметры запроса являются необязательными.

Вот пример запроса, который ищет лекции в тестовой программируемой поисковой системе:

GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures

Параметры запроса

Есть два типа параметров, которые вы можете передать в своем запросе:

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

Все значения параметров должны быть закодированы в URL.

Параметры запроса API

Параметры запроса, которые применяются конкретно к JSON API пользовательского поиска и определяют ваш поисковый запрос, приведены в справке .

Стандартные параметры запроса

Параметры запроса, применимые ко всем операциям JSON API пользовательского поиска, задокументированы в разделе Системные параметры .

Данные ответа

Если запрос выполнен успешно, сервер отвечает кодом состояния HTTP 200 OK и данными ответа в формате JSON. Вы можете посмотреть структуру данных ответа в справочнике .

Данные ответа представляют собой объект JSON, который включает три типа свойств:

  • Метаданные, описывающие запрошенный поиск (и, возможно, связанные поисковые запросы)
  • Метаданные, описывающие программируемую поисковую систему
  • Результаты поиска

Подробное описание каждого свойства смотрите в ссылке .

Метаданные поискового запроса

Метаданные поиска включают:

  • url , которое содержит информацию о шаблоне OpenSearch , используемом для результатов, возвращаемых в этом запросе.
  • Свойство queries , представляющее собой массив объектов, описывающих характеристики возможных поисков. Имя каждого объекта в массиве — это либо имя роли запроса OpenSearch , либо одна из двух настраиваемых ролей, определенных этим API: previousPage и nextPage . Возможные объекты роли запроса включают:
    • request : метаданные, описывающие запрос для текущего набора результатов.
      • Эта роль всегда присутствует в ответе.
      • Это всегда массив с одним элементом.
      • nextPage : метаданные, описывающие запрос для использования на следующей странице результатов.
        • Эта роль отсутствует, если текущие результаты являются последней страницей. Примечание. Этот API возвращает только первые 100 результатов.
        • Когда он присутствует, это всегда массив только с одним элементом.
    • previousPage страница : метаданные, описывающие запрос для использования на предыдущей странице результатов.
      • Не присутствует, если текущие результаты являются первой страницей.
      • Когда он присутствует, это всегда массив только с одним элементом.

Метаданные поисковой системы

Свойство context содержит метаданные, описывающие поисковую систему, выполнившую поисковый запрос. Он включает имя поисковой системы и любые фасетные объекты , которые она предоставляет для уточнения поиска.

Результаты поиска

Массив items содержит фактические результаты поиска. Результаты поиска включают URL-адрес, заголовок и текстовые фрагменты, описывающие результат. Кроме того, они могут содержать расширенные фрагменты информации, если это применимо.

Если результаты поиска содержат свойство promotions , оно содержит набор рекламных акций .

ОТДЫХ из JavaScript

Вы можете вызвать JSON API пользовательского поиска с помощью REST из JavaScript, используя параметр запроса callback и функцию обратного вызова. Это позволяет вам писать многофункциональные приложения, отображающие данные программируемой поисковой системы, без написания кода на стороне сервера.

В следующем примере этот подход используется для отображения первой страницы результатов поиска по запросу cars :

<html>
  <head>
    <title>Custom Search JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function hndlr(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // Make sure HTML in item.htmlTitle is escaped.
        document.getElementById("content").append(
          document.createElement("br"),
          document.createTextNode(item.htmlTitle)
        );
      }
    }
    </script>
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=cars&callback=hndlr">
    </script>
  </body>
</html>