本文档介绍了如何使用 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)
- 可编程搜索引擎 ID - 使用
搜索查询 - 使用
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
您可以使用 callback 查询参数和回调函数,通过 JavaScript 使用 REST 调用 Custom Search JSON API。这样,您无需编写任何服务器端代码,即可编写显示可编程搜索引擎数据的丰富应用。
以下示例使用此方法显示查询 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>