Используйте REST для вызова API

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

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

REST, или передача репрезентативного состояния , в API JSON пользовательского поиска несколько отличается от обычных API RESTful. Вместо предоставления доступа к ресурсам 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 и функцию обратного вызова. Это позволяет вам писать многофункциональные приложения, отображающие данные программируемой поисковой системы, без написания кода на стороне сервера.

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

<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
    <div id="content"></div>
    <p id="demo"></p>
    <script>
    function hndlr(response) {
      if (response.items == null) {
        document.getElementById("demo").innerHTML +=`<h3> No Results Found </h3>`;
      } else {
        for (var i = 1; 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=lecture&callback=hndlr">
    </script>
  </body>
</html>