Google Custom Search JSON API

本篇文档旨在介绍如何利用 Google Custom Search JSON API 搜索特定网站。文档内容包括如何创建和配置可编程搜索引擎（Custom Search Engine，简称 CSE）、如何获取 API Key、如何通过 RESTful 接口发送请求，以及如何在前端页面中调用 API 并渲染搜索结果。

[[toc]]

简介

Google Custom Search JSON API 允许开发者使用 HTTP GET 请求，获取指定搜索范围内的搜索结果。利用该 API，你可以将搜索目标限定在特定网站（如 sjsu.edu），并通过编程方式处理返回的 JSON 格式数据。需要注意的是，使用该 API 前必须具备以下两个必要条件：

  • 一个可编程搜索引擎（CSE）及其对应的 ID（即 cx 值）
  • 一个已启用 Custom Search JSON API 权限的 API Key

创建并配置可编程搜索引擎

注意： 此步骤是必须的，没有有效的 CSE（及对应的 cx），API 无法知道在哪个搜索范围内执行搜索。

手动创建 CSE

  1. 访问 Programmable Search Engine 控制台。
  2. 点击 “新增搜索引擎” 或编辑已有的搜索引擎。
  3. 在“网站待搜索”或“包含的网站”处填写目标域名（例如：sjsu.edu 或 https://www.sjsu.edu/）。
  4. 创建完成后，系统会为你生成一个搜索引擎 ID，即 cx 值，例如：
    017576662512468239146:omuauf_lfve
  5. 确保在 Google Cloud API Console 中已启用 Custom Search JSON API。

为什么必须手动配置？

  • API 必需参数：Custom Search JSON API 要求请求中携带 cx 参数，此值来源于你预先创建的 CSE。
  • 搜索范围控制：通过在 CSE 中配置包含的网站或在查询关键词中使用 site:sjsu.edu，你可以限定搜索范围。
  • 无通用 cx：Google 不提供通用的搜索引擎 ID，必须使用自定义创建的 CSE。

获取并确认 API Key

确保你已经获得了一个 API Key，并在 Google Cloud API Console 中启用了对 Custom Search JSON API 的访问权限。你可以在控制台中查看该 API Key 的配额与权限配置。

通过 RESTful 接口发送请求

构造请求 URL 时需包含以下参数：

  • key：你的 API Key。
  • cx：你创建的可编程搜索引擎 ID。
  • q：搜索关键词。

示例

如果你的 CSE 已经限定了搜索域为 sjsu.edu，只需在 q 中填写关键词即可。例如，搜索 “registration”：

GET https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_SJSU_CX&q=registration

如果 CSE 没有限定域名，则可以在查询中加入 site:sjsu.edu 限定范围：

GET https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_CX&q=registration+site:sjsu.edu

返回结果为 JSON 格式，其中包括搜索结果、分页信息和搜索引擎相关数据。例如：

{
  "kind": "customsearch#search",
  "url": { ... },
  "queries": {
    "request": [
      {
        "title": "Google Custom Search - registration",
        "totalResults": "5150",
        "searchTerms": "registration",
        "count": 10,
        "startIndex": 1,
        "inputEncoding": "utf8",
        "outputEncoding": "utf8",
        "safe": "off",
        "cx": "YOUR_SJSU_CX"
      }
    ],
    "nextPage": [ ... ]
  },
  "context": { "title": "sjsu" },
  "searchInformation": { ... },
  "items": [
    {
      "kind": "customsearch#result",
      "title": "Fall 2024 | Office of the Registrar",
      "link": "https://www.sjsu.edu/registrar/calendar/fall-2024.php",
      "snippet": "2024 · First Day of Instruction, Late Registration begins on MySJSU at 7am...",
      ...
    },
    ...
  ]
}

前端 JavaScript 调用示例

如果希望在 HTML 页面中直接调用 API 并渲染结果，可以使用 JSONP 的方式。示例如下：

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Search sjsu.edu</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        // 遍历搜索结果并插入到页面中
        if (response.items) {
          response.items.forEach(function (item) {
            const div = document.createElement("div");
            div.innerHTML = item.htmlTitle; // 注意 XSS 安全性
            document.getElementById("content").appendChild(div);
          });
        }
      }
    </script>
    <!-- 使用 JSONP 的方式调用 -->
    <script src="https://www.googleapis.com/customsearch/v1?key=YOUR_API_KEY&cx=YOUR_SJSU_CX&q=registration&callback=handleResponse"></script>
  </body>
</html>

这样，搜索结果会以 JSONP 格式返回，并由 handleResponse 回调函数进行处理与展示。

常见注意事项

  1. 查询长度限制
    请求 URL 总长度不应超过 2048 个字符。

  2. 返回结果数量
    API 最多返回 100 条结果（即 10 页，每页 10 条）。

  3. 配额限制
    不同的 API Key 与 Google Cloud 账户有各自的免费/付费调用配额，使用时请留意调用次数限制。

  4. 参数编码
    确保所有参数值均已进行 URL 编码，以避免请求错误。

常见问答

1. 创建并配置可编程搜索引擎这一步是必须的吗？

回答：是的。Custom Search JSON API 需要 cx 参数，该值来源于预先创建并配置的 CSE。如果没有创建 CSE，你将无法获得合法的 cx，进而无法正常调用 API。

2. 是否可以通过发送 HTTP 请求来动态创建或配置可编程搜索引擎？

回答：不可以。目前 Google 官方并未提供任何 REST API 来远程创建或配置 CSE。所有的 CSE 创建和配置操作都必须通过 Programmable Search Engine 控制台 手动完成。

Java 代码调用 Google Custom Search JSON API

笔者开发了java-openai 项目里面封装对 Google Custom Search JSON API 的调用,下面是一段代码.展示了如何在 Java 项目中调用 Google Custom Search JSON API。

示例代码

package com.litongjava.perplexica.services;

import com.litongjava.google.search.GoogleCustomSearchClient;
import com.litongjava.google.search.GoogleCustomSearchResponse;
import com.litongjava.tio.utils.environment.EnvUtils;

public class GoogleCustomSearchService {

  /**
   * 调用 Google Custom Search JSON API 搜索指定内容
   *
   * @param ctx   搜索引擎的 ID (CSE_ID)
   * @param text  搜索关键字
   * @return      搜索结果封装对象
   */
  public GoogleCustomSearchResponse search(String ctx, String text) {
    // 从环境变量中获取 API Key
    String key = EnvUtils.getStr("GOOGLE_API_KEY");
    // 调用封装的搜索客户端执行搜索请求，并返回响应结果
    return GoogleCustomSearchClient.search(key, ctx, text);
  }
}

示例说明

在示例代码中，我们定义了一个 GoogleCustomSearchService 类，其中的 search 方法接收两个参数：

  • ctx：表示搜索引擎的 ID（CSE_ID）。
  • text：表示搜索关键字。

方法内部首先通过 EnvUtils.getStr 获取存放在环境变量中的 API Key（键名为 "GOOGLE_API_KEY"），然后调用 GoogleCustomSearchClient.search 方法发起搜索请求，并返回 GoogleCustomSearchResponse 对象作为搜索结果。

总结

  • 创建与配置：在调用 API 前，必须先在控制台中创建一个可编程搜索引擎（CSE），并将其配置为只搜索目标网站（如 sjsu.edu）。
  • API Key：确保你拥有一个已启用 Custom Search JSON API 权限的 API Key。
  • 请求构造：使用 GET 请求，包含 key、cx 与 q 参数。若 CSE 未限定域名，可在查询中使用 site:sjsu.edu 限定搜索范围。
  • 前端调用：可以利用 JSONP 的方式在 HTML 与 JavaScript 中直接调用 API 并渲染结果。
  • 注意事项：关注 URL 长度、返回结果数、调用配额以及参数编码问题。

通过以上步骤，你就能利用现有的 API Key 和已配置的 CSE，针对特定网站（如 sjsu.edu）实现搜索功能，并获取 JSON 格式的搜索结果。

这份文档详细说明了使用 Google Custom Search JSON API 的全过程，确保你在开发过程中可以顺利集成并调用该 API。