Google Web Search Indexing API 设置教程：为非 WordPress 网站搜索收录提速

什么是Web Search Indexing API？

Google 网页搜索索引 API（通常简称为索引 API）是 Google 提供的一个接口，允许网站所有者和开发者直接通知 Google 其网站上的新增或更新页面。通过此 API，您可以主动为特定 URL 请求编入索引，而不必等待 Googlebot 自然抓取您的网站。这可以大大加快您的内容出现在 Google 搜索结果中的速度。

许多教程通过 WordPress 插件来演示如何使用索引 API，但这对于运行静态网站或自定义部署（例如，使用 Rust、Python 脚本或简单 Shell 自动化生成的网站）的用户来说并无帮助。本指南将引导您在不依赖 WordPress 的情况下注册使用索引 API——非常适合管理静态网站或任何非 WordPress 网站的开发者。

⚠️ Indexing API 使用范围提示

重要提醒（2025年5月28日更新）： Google 官方明确指出，Indexing API 只面向含有 ​JobPosting​​ 或直播类结构化数据（​VideoObject​​ → ​BroadcastEvent​​ ）的页面。普通文章、产品页等内容并不在支持范围内。

Google 也多次警告，强行推送不受支持的 URL 不但无效，甚至可能触发反垃圾机制；常规内容应仍依赖 XML 站点地图和 Googlebot 的正常抓取。

Rank Math 的 Instant Indexing 插件虽然对任何文章类型都开放了提交入口，并声称 Google “可能”会收录，但结果完全由 Google 决定。Rank Math 官方客服同样承认，Google 目前“只允许招聘信息和直播页面”使用该 API，且自从 Google 收紧反垃圾策略后，其他页面的成功率大幅下降。

如果想尝试通过 Rank Math 或自定义脚本把普通文章推送给 Indexing API，请先小规模测试。由于这类请求并不在官方允许范围，极有可能被忽略。请衡量潜在的收录提速与浪费配额的风险，再决定是否全面使用。

设置 Google 索引 API 访问权限

在您发送索引请求之前，需要设置凭据和权限。概括来说，您需要完成以下步骤：

  • 为您的网站创建一个 Google Cloud 项目并启用索引 API。
  • 在该项目中创建一个服务帐号并下载其 JSON 密钥凭据。
  • 在 Google Search Console 中为该服务帐号授予您网站的访问权限（所有者权限）。
  • 使用服务帐号凭据进行身份验证并调用索引 API。

我们将详细介绍这些步骤中的每一步。

1. 创建 Google Cloud 项目

首先，在 Google Cloud 中创建一个新项目，该项目将用于存放您的 API 凭据和设置：

Google Cloud Console “选择项目”菜单，其中“新建项目”选项已突出显示。
Google Cloud Console “选择项目”菜单，其中“新建项目”选项已突出显示。

访问 Google Cloud Console ，然后点击顶部的项目下拉菜单。选择 “新建项目” 。在出现的对话框中，为您的项目命名（例如，“MySite 的索引 API 项目”）并点击创建。这样便会设置一个独立的项目，您可以在其中启用 API 和创建凭据，而不会影响其他项目。

2. 启用网页搜索索引 API

接下来，在您的新项目中启用索引 API：

在 API 库中搜索“indexing”并选择“Web Search Indexing API”。
在 API 库中搜索“indexing”并选择“Web Search Indexing API”。

在 Cloud Console 中，导航至 API 和服务 > 库。在 API 库的搜索栏中输入“Indexing”。在搜索结果中找到 “Web Search Indexing API” （这是索引 API 在 Google Cloud 中的官方名称）并点击它。

Web Search Indexing API 页面上的“启用”按钮。
Web Search Indexing API 页面上的“启用”按钮。

在索引 API 详情页面，确保顶部栏中已选择您的新项目，然后点击启用按钮。启用 API 可能需要一些时间。启用后，您将能够在该项目中管理此 API 的凭据和用量。

索引 API 显示在您项目的已启用 API 列表中。
索引 API 显示在您项目的已启用 API 列表中。

启用后，您可以通过滚动浏览“已启用的 API”列表（在 API 和服务 > 已启用的 API 下）进行确认。您应该会在列表中看到 Web Search Indexing API，表明它已在您的项目中激活。

3. 创建服务帐号并下载凭据

现在您需要创建一个服务帐号。服务帐号是一种特殊的 Google 帐号，它隶属于您的项目（而非人类用户），可用于服务器到服务器的身份验证。

服务帐号页面，其中“+ 创建服务帐号”已突出显示。
服务帐号页面，其中“+ 创建服务帐号”已突出显示。

在 Cloud Console 中，转到您项目的 IAM 和管理 > 服务帐号。点击 “创建服务帐号” 按钮。为服务帐号提供一个名称（例如，“indexing-api-sa”）和可选的描述。

创建服务帐号：“创建并继续”按钮已突出显示。
创建服务帐号：“创建并继续”按钮已突出显示。

命名服务帐号后，点击 “创建并继续” 。接下来的步骤可能会提示您为此服务帐号分配角色或授予用户访问权限——您现在可以跳过添加角色/权限的步骤（仅调用索引 API 不需要额外的角色）。如果出现提示，点击完成以继续并完成创建过程。

列出了新创建的服务帐号；点击其名称可查看详情。
列出了新创建的服务帐号；点击其名称可查看详情。

服务帐号创建后，您应该会在项目的服务帐号列表中看到它。点击服务帐号的电子邮件或名称以打开其详情页面。

现在，为此服务帐号创建一个私钥——您将在代码中使用它进行身份验证：

服务帐号详情页面，其中包含添加密钥的选项和 JSON 密钥下载提示。
服务帐号详情页面，其中包含添加密钥的选项和 JSON 密钥下载提示。

在服务帐号详情页面，转到 “密钥” 标签页。点击 “添加密钥” 并选择 “创建新密钥” 。在弹出的窗口中，选择 JSON 作为密钥类型，然后点击“创建”。Google 将生成一个 JSON 密钥文件，您的浏览器会自动下载它（文件名类似于 project-id-*****.json）。请将此文件保存在安全的位置，因为它包含您的服务帐号凭据（像对待密码一样对待它！）。此 JSON 文件稍后将用于获取访问令牌或设置 API 客户端。

🔒 妥善保管您的 JSON 密钥： 如果任何人获取此文件，他们可能访问您的 Google API。请勿将其提交到版本控制系统或公开共享。

4. 在 Search Console 中将服务帐号添加为所有者

服务帐号现已存在并拥有凭据，但默认情况下，它无权在 Google Search 中管理您的网站。我们需要通过 Google Search Console (GSC) 授予其访问权限。具体来说，我们将在 GSC 中将服务帐号的电子邮件添加为您网站资源的所有者。

Google Search Console 设置显示通过电子邮件添加新所有者（服务帐号的电子邮件）。
Google Search Console 设置显示通过电子邮件添加新所有者（服务帐号的电子邮件）。

访问 Google Search Console (search.google.com/search-console) 并打开您网站的资源（如果您尚未验证您的网站，则需要先在 Search Console 中进行验证）。导航至 设置 > 用户和权限（适用于网域资源）或 设置 > 所有权验证（用于添加所有者）。在这里，查找 “添加所有者” 或 “添加用户” 的选项。输入服务帐号的电子邮件（即您在服务帐号页面或 JSON 密钥中 client_email​ 字段下看到的以 ...iam.gserviceaccount.com​ 结尾的电子邮件地址）。为其分配所有者权限。确认并保存此更改。

完成此操作后，您的服务帐号实际上就拥有与您（网站所有者）相同的权限，可以为该网站提交索引请求。Google 可能会发送一封电子邮件通知，告知该资源已添加新的所有者。

小结： 至此，您已启用索引 API，创建了带凭据的服务帐号，并授权该服务帐号代表您的网站执行操作。现在，您可以实际调用索引 API 来提交 URL 了！

通过索引 API 提交 URL

完成设置后，您可以通过以下几种方式向 Google 发送索引请求：

  • 使用直接 HTTP 请求（例如，通过 ​curl​​ ） ——适用于测试或使用 Shell 命令编写脚本。
  • 使用您编程语言的客户端库——我们将展示 Python 和 Rust 的示例（Google 也为其他语言提供了客户端库）。

所有方法最终都执行相同的操作：向 Google 的索引 API 端点发送一个经过身份验证的 HTTP POST 请求，其中包含您要通知的 URL。

用于发布（通知新增或更新页面）的索引 API URL 是：https://indexing.googleapis.com/v3/urlNotifications:publish​

请求正文是一个 JSON 对象，包含 URL 和通知类型。对于新增或更新的内容，我们使用 "type": "URL_UPDATED"​。（还有一个 "URL_DELETED"​ 类型，用于告知 Google某个 URL 已被移除。）

无论您选择哪种方法，都必须验证使用服务帐号凭据。这通常涉及为 https://www.googleapis.com/auth/indexing​ 范围获取 OAuth 2.0 访问令牌，并将其包含在您的请求头中。API的使用方法请查阅官方文档：如何使用 Indexing API | Google 搜索中心  |  Google for Developers。

使用 Python

为了实现更稳健的集成，您可以使用 Google 的 Python 客户端库。在 Python 中，推荐的方法是使用 Google API Python Client 以及来自 google.oauth2.service_account 的凭据对象。这将为您处理获取令牌和发出请求的过程。

使用 Rust

如果您正在编写 Rust 程序来集成索引通知（例如，作为静态网站部署流程的一部分），您可以使用社区维护的 Rust 版 Google API 客户端。其中一个 crate 是 google-indexing3​，它为索引 API (v3) 提供了 Rust 绑定。

设置： 将该 crate 添加到您的 Cargo.toml​ 文件中：

[dependencies]
google-indexing3 = "*"
serde = "1"
serde_json = "1"

以下是使用 google-indexing3​ crate 提交 URL 的官方示例。此示例使用 yup-oauth2​ crate 来处理服务帐号身份验证和令牌管理：

//官方范例
extern crate hyper;
extern crate hyper_rustls;
extern crate google_indexing3 as indexing3;
use indexing3::{Result, Error};
use indexing3::{Indexing, FieldMask, hyper_rustls, hyper_util, yup_oauth2};

// Get an ApplicationSecret instance by some means. It contains the `client_id` and
// `client_secret`, among other things.
let secret: yup_oauth2::ApplicationSecret = Default::default();
// Instantiate the authenticator. It will choose a suitable authentication flow for you,
// unless you replace  `None` with the desired Flow.
// Provide your own `AuthenticatorDelegate` to adjust the way it operates and get feedback about
// what's going on. You probably want to bring in your own `TokenStorage` to persist tokens and
// retrieve them from storage.
let auth = yup_oauth2::InstalledFlowAuthenticator::builder(
    secret,
    yup_oauth2::InstalledFlowReturnMethod::HTTPRedirect,
).build().await.unwrap();

let client = hyper_util::client::legacy::Client::builder(
    hyper_util::rt::TokioExecutor::new()
)
.build(
    hyper_rustls::HttpsConnectorBuilder::new()
        .with_native_roots()
        .unwrap()
        .https_or_http()
        .enable_http1()
        .build()
);
let mut hub = Indexing::new(client, auth);
// You can configure optional parameters by calling the respective setters at will, and
// execute the final call using `doit()`.
// Values shown here are possibly random and not representative !
let result = hub.url_notifications().get_metadata()
             .url("magna")
             .doit().await;

match result {
    Err(e) => match e {
        // The Error enum provides details about what exactly happened.
        // You can also just use its `Debug`, `Display` or `Error` traits
         Error::HttpError(_)
        |Error::Io(_)
        |Error::MissingAPIKey
        |Error::MissingToken(_)
        |Error::Cancelled
        |Error::UploadSizeLimitExceeded(_, _)
        |Error::Failure(_)
        |Error::BadRequest(_)
        |Error::FieldClash(_)
        |Error::JsonDecodeError(_, _) => println!("{}", e),
    },
    Ok(res) => println!("Success: {:?}", res),
}

有关此 Rust crate 的更多详细信息，请查看 docs.rs 上的 google-indexing3​ 文档及其示例。该 crate 是社区提供的 Google API for Rust 的一部分（包含自动生成的 Google API 接口）。它处理了大量样板代码，但如上所示，您仍需要设置 OAuth2 流程（yup-oauth2​ 通过服务帐号使其相对简单）。

监控配额并确认提交成功

Google 的索引 API 有使用限制，监控您的使用情况是一个好习惯。默认情况下，每个 Google Cloud 项目每天允许发送 200 个索引请求（这是 “publish” 配额）。如果您有多个项目或需要更多配额，可以请求提高配额或将请求分散到多个项目中，但每天 200 个是起始限制。

要在 Google Cloud Console 中查看您的用量和配额：

Google Cloud Console 配额页面显示“索引 API – 每天 200 个请求”的默认配额。
Google Cloud Console 配额页面显示“索引 API – 每天 200 个请求”的默认配额。

在 Cloud Console 中，转到 API 和服务 > 已启用的 API 和服务，然后点击 Web Search Indexing API，并导航到配额或用量部分。在这里您会看到配额（例如，“发布 URL 通知”方法的配额为“每天 200 个请求”）以及您当天已使用的配额量。

用量图表显示成功提交索引请求后用量增加。
用量图表显示成功提交索引请求后用量增加。

在发出调用（无论是通过 cURL、Python、Rust 等）后，刷新配额/用量页面。您应该会看到已用请求计数上升（例如，从 0 到 1）。这是验证 Google 是否成功收到您的请求的快速方法。如果计数没有增加，则您的请求可能未正确验证身份，或者可能在到达 Google 服务器之前就失败了。

此外，成功的 API 调用将返回 200 OK HTTP 状态。如果您收到错误状态（4xx 或 5xx），请注意响应中的错误消息。常见问题包括：未使用正确的范围或凭据（导致 401/403 未授权​ 错误）、JSON 格式错误或超出配额。

配额管理： 每天 200 个 URL 对于大多数静态网站来说已经足够（因为您可能不会每天发布那么多新页面）。如果您确实需要更多，可以向 Google 提交配额增加请求（目前，Google 对索引 API 的更高配额需要审批）。或者，一些用户会创建多个项目（每个项目每天 200 个配额），但请谨慎使用： Google 的政策不鼓励通过多个帐号规避配额，滥用 API 可能导致访问权限被撤销。

为何使用索引 API 而非手动提交？

您可能想知道，为什么不直接使用 Google Search Console 用户界面中的请求编入索引功能，而非要费这么多周折。API 方法具有一些关键优势，特别是对于开发者和静态网站部署而言：

  • 自动化和效率： 通过 API，您可以将索引请求自动化，作为部署或内容发布工作流程的一部分。无需手动登录 GSC 并逐个提交 URL。这样可以节省时间，并确保每个新增或更新的页面都能及时提交。
  • 索引速度： 索引 API 通常能促使 Google 更快地抓取页面，而不是等待下一次常规抓取。虽然手动的“请求编入索引”也能触发抓取，但通过 API 操作可以与 CI/CD 流水线集成，因此在您部署新内容时会立即执行。
  • 可靠性和一致性： 依赖手动过程容易出错（您可能会忘记为某个页面请求编入索引，或者 GSC 界面可能暂时不可用）。API 方法是可编写脚本且一致的——一旦设置完成，每次都会以相同的方式运行。事实上，曾有过手动“请求编入索引”工具被禁用或限制的情况，而 API 对于已验证的网站仍然可用。
  • 批量操作： API（通过一些额外工作）允许在单个请求中批量处理多达 100 个 URL 通知。这在用户界面中是无法实现的。如果您一次生成大量内容或更新，可以通过 API 高效地提交它们。
  • 程序化反馈： 调用 API 时，您会收到一个响应，指示每个请求的成功或失败。此反馈可以被记录或用于您的应用程序逻辑中（例如，重试失败的提交或在索引请求未通过时提醒您）。相比之下，GSC 用户界面除了通用的“已请求”状态外，不会提供如此详细的反馈。
  • 移除和元数据： 索引 API 不仅仅用于提交新 URL；您还可以通知 Google URL 的移除（如果您已删除某些页面），或查询某个 URL 的最新索引通知状态（urlNotifications.getMetadata​ 方法）。这些程序化功能以一种便捷的方式超越了手动用户界面所能提供的功能。

您已经为您的静态网站设置了索引 API，并学会了通过多种方法使用它。您可以将这些调用集成到您的部署脚本或内容管理工作流程中，以便每当您发布新内容时，都会立即通知 Google。这可以加快您更新内容的搜索可见性，而在初始设置之后无需任何手动操作。

你可能也感兴趣