此页面由 Cloud Translation API 翻译。

使用 REST 调用 API

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

发出请求

REST（即具象状态传输）与传统 REST 有所不同。此 API 不提供对资源的访问权限，而是提供对服务的访问权限。因此，该 API 提供了充当服务端点的单个 URI。

您可以通过发送 HTTP GET 来检索特定搜索的结果请求其 URI。您可以将搜索请求的详细信息作为查询参数。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 的参数并定义您的搜索请求的汇总 reference。

标准查询参数

适用于所有 Custom Search JSON API 操作的查询参数记录在系统参数。

响应数据

如果请求成功，服务器会返回 200 OK HTTP 状态代码以及 JSON 格式的响应数据。您可以查询结构（在 reference 中）。

响应数据是一个 JSON 对象，包含三种类型的属性：

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

有关每个属性的详细说明，请参阅 reference。

搜索请求元数据

搜索元数据包括：

url 属性，该属性具有 OpenSearch 模板的相关信息，用于此请求中返回的结果。
queries 属性，它是以下对象的数组：对象，用于描述可能的搜索的特征。每个可以是 OpenSearch query 角色也可以是此 API 定义的两个自定义角色中的一个： previousPage和nextPage。可能的查询角色对象包括： <ph type="x-smartling-placeholder">
- request：描述当前查询集的查询的元数据结果。
  - 此角色会一直存在于响应中。
  - 该组一直只有一个元素。
  - nextPage：描述要用于下一个查询的元数据结果页。
    - 如果当前结果是最后一页，则此角色不存在。注意：此 API 最多只返回前 100 个结果。
    - 如果此角色出现，则会保持自身的组只包含一个元素。
- previousPage：描述要用于结果的上一页。
  - 如果当前结果在第一页中，则此角色不会出现。
  - 如果存在，则始终为仅包含一个元素的数组。

搜索引擎元数据

context 属性包含描述搜索引擎的元数据执行该搜索查询的网址。包括搜索引擎的名称以及它为以下对象提供的任何构面对象优化搜索

搜索结果

items 数组包含实际搜索结果。搜索结果包括描述结果的网址、标题和文本摘要。在还可以包含丰富网页摘要信息（如果有）。

如果搜索结果包含 promotions 属性，则其中包含一组促销活动。

JavaScript 中的 REST

您可以使用 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>