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

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

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

Оформление запроса

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

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

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

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

Если запрос успешен, сервер отвечает кодом состояния 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>