使用 REST 调用 API

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

发出请求

Custom Search JSON API 中的 REST（即代表状态传输）与常规 RESTful API 略有不同。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 查询参数指定搜索表达式。

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

以下是搜索测试可编程搜索引擎中的讲座的请求示例：

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 定义的两个自定义角色之一：previousPage 和 nextPage。可能的查询角色对象包括：
    • request：描述当前结果集的查询的元数据。
    • 此角色始终存在于响应中。
      • 该组一直只有一个元素。
      • nextPage：用于描述要用于下一页结果的查询的元数据。
        • 如果当前结果是最后一页，则不存在此角色。注意 ：此 API 最多只会返回前 100 条结果。
        • 如果此角色出现，则会保持自身的组只包含一个元素。
    • previousPage：描述要用于前一页结果的查询的元数据。
      • 如果当前结果在第一页中，则此角色不会出现。
      • 如果存在，则始终是一个只有一个元素的数组。

搜索引擎元数据

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

搜索结果

items 数组包含实际的搜索结果。搜索结果包括网址、标题和用于描述结果的文字摘要。此外，它们还可以包含富媒体摘要信息（如果适用）。

如果搜索结果包含 promotions 媒体资源，则其中包含一组促销活动。

JavaScript 中的 REST

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

以下示例使用此方法显示查询 lecture 的第一页搜索结果：

<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>