使用 REST 调用 API

本文档介绍了如何使用 Custom Search JSON API。

发出请求

Custom Search JSON API 中的 REST(即表征状态传输)与传统 REST 略有不同。该 API 不提供对资源的访问权限,而是对服务的访问权限。因此,该 API 提供了充当服务端点的单个 URI。

您可以通过向相应 URI 发送 HTTP GET 请求来检索特定搜索的结果。您将搜索请求的详细信息作为查询参数传入。Custom Search JSON API URI 的格式为:

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

每个搜索请求都需要三个查询 [parameters]

  • API 密钥 - 使用 key 查询参数来标识您的应用
  • 可编程搜索引擎 ID - 使用 cx 可指定用于执行此搜索的可编程搜索引擎。必须使用控制面板创建搜索引擎。注意:搜索引擎 ID (cx) 可以采用不同的格式(例如 8ac1ab64606d234f1)

  • 搜索查询 - 使用 q 查询参数指定您的搜索表达式。

所有其他查询参数都是可选的。

以下示例展示了如何在测试可编程搜索引擎中搜索 lectures

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

查询参数

您可以在请求中传递两种类型的参数:

  • API 特有的参数 - 定义搜索的属性,例如搜索表达式、结果数量、语言等。
  • 标准查询参数 - 定义请求的技术方面,例如 API 密钥。

所有参数值都需要经过网址编码。

API 专属查询参数

如需了解专门适用于 Custom Search JSON API 并用于定义搜索请求的请求参数,请参阅参考文档

标准查询参数

系统参数中介绍了适用于所有 Custom Search JSON API 操作的查询参数。

响应数据

如果请求成功,服务器将返回 200 OK HTTP 状态代码以及 JSON 格式的响应数据。您可以在引用中查找响应数据结构。

响应数据是一个 JSON 对象,其中包含以下三种属性:

  • 描述请求的搜索(也可能是相关的搜索请求)的元数据
  • 描述可编程搜索引擎的元数据
  • 搜索结果

如需详细了解每个属性,请参阅参考文档

搜索请求元数据

搜索元数据包括:

  • url 属性,该属性包含有关用于此请求中返回结果的 OpenSearch 模板的信息。
  • queries 属性:这是一个描述可能搜索特征的对象数组。数组中每个对象的名称要么是 OpenSearch 查询角色的名称,要么是此 API 定义的两个自定义角色之一:previousPagenextPage。可能的查询角色对象包括:
    • request:描述当前结果集的查询的元数据。
      • 此角色会一直存在于响应中。
      • 该组一直只有一个元素。
      • nextPage:描述用于下一页结果的查询的元数据。
        • 如果当前结果是最后一页,则此角色不存在。 注意 :此 API 最多仅返回前 100 个结果。
        • 如果此角色出现,则会保持自身的组只包含一个元素。
    • previousPage:描述用于上一页结果的查询的元数据。
      • 如果当前结果在第一页中,则此角色不会出现。
      • 如果存在,则始终是一个只包含一个元素的数组。

搜索引擎元数据

context 属性包含描述执行搜索查询的搜索引擎的元数据。它包含搜索引擎的名称,以及它提供的任何用于优化搜索的构面对象

搜索结果

items 数组包含实际搜索结果。搜索结果包括描述结果的网址、标题和文本摘要。此外,它们可以包含结构化摘要信息(如果适用)。

如果搜索结果包含 promotions 属性,则它包含一组促销活动

JavaScript 中的 REST

您可以通过 callback 查询参数和回调函数,使用 JavaScript 中的 REST 调用 Custom Search JSON API。这样,您无需编写任何服务器端代码,即可编写显示可编程搜索引擎数据的丰富应用。

以下示例使用此方法显示查询 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>