使用旧版 SiteVerify 验证用户响应令牌

本页面介绍了如何使用旧版 SiteVerify API 端点 (https://www.google.com/recaptcha/api/siteverify) 从应用后端验证用户对 reCAPTCHA 验证任务的响应。只有在维护无法使用 CreateAssessment 的旧版集成或第三方插件时，才应使用此端点。

准备工作

如需调用 SiteVerify 端点，您需要密钥的旧版密钥。如需在 Google Cloud 控制台中查找密钥，请参阅在 Google Cloud 控制台中检索密钥。 请在后端服务器上妥善保管您的密钥，切勿在客户端代码中公开该密钥。

检索用户的回答令牌

旧版 Web 集成会加载非企业版 JavaScript API (https://www.google.com/recaptcha/api.js)，该 API 会在 grecaptcha 对象上提供方法，而不是在 grecaptcha.enterprise 对象上提供方法。您可以通过以下方式之一在前端检索用户的回答令牌：

  • 当用户在您的网站上提交表单时，从 g-recaptcha-response POST 参数中获取。
  • 在用户完成 reCAPTCHA v2 验证任务后调用 grecaptcha.getResponse(opt_widget_id)。此方法会以字符串形式返回响应令牌，如果验证未完成，则返回空字符串。可选的 opt_widget_id 参数用于指定 grecaptcha.render() 返回的 widget ID；如果省略，则默认为创建的第一个 widget。
  • 当用户完成挑战时，作为传递给回调函数的字符串实参；如果您在 g-recaptcha HTML 元素的 data-callback 属性或 grecaptcha.render(container, parameters) 方法的 callback 参数中指定了回调函数名称，则会传递该实参。
  • 从 grecaptcha.execute(site_key, {action: action_name}) 返回的 Promise 的已解析值中获取，适用于基于得分 (v3) 的密钥。

旧版 grecaptcha 方法（render、getResponse、execute、ready 和 reset）和 g-recaptcha 标记属性使用的参数与 grecaptcha.enterprise 等效项相同。如需了解参数详情，请参阅 reCAPTCHA 的 JavaScript API 参考文档。

如需迁移到更新后的 reCAPTCHA JavaScript API，请参阅迁移 reCAPTCHA JavaScript API。

token 限制

每个 reCAPTCHA 用户响应令牌的有效期都是 2 分钟，并且您只能验证每个令牌 1 次，以防止重放攻击。在收到响应令牌后的两分钟内，使用 reCAPTCHA 验证该令牌。 如果需要新令牌，请再次运行 reCAPTCHA 验证。

API 请求

使用以下端点和方法发送请求：

  • 网址：https://www.google.com/recaptcha/api/siteverify（如果无法访问 www.google.com，则为 https://www.recaptcha.net/recaptcha/api/siteverify；请参阅在全球范围内使用 reCAPTCHA）
  • 方法：POST

在请求中添加以下 POST 参数：

POST 参数 说明
secret 必需。您的网站与 reCAPTCHA 之间的共享 Secret 密钥。
response 必需。由您网站上的 reCAPTCHA 客户端集成机制提供的用户响应令牌。
remoteip 可选。用户的 IP 地址。

API 响应

SiteVerify 端点会返回一个 JSON 对象。

对于 Web 集成（基于得分的 v3、复选框 v2 或隐形 v2 密钥），响应的格式如下：

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number,            // the score for this request (0.0 - 1.0) for score-based (v3) keys
  "action": string,           // the action name for this request (important to verify)
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

错误代码参考

下表介绍了 error-codes 数组中可能显示的错误代码：

错误代码 说明
missing-input-secret 缺少 secret 参数。
invalid-input-secret secret 参数无效或格式不正确。
missing-input-response 缺少 response 参数。
invalid-input-response response 参数无效或格式不正确。
bad-request 请求无效或格式不正确。
timeout-or-duplicate 该响应不再有效，因为其已过期或已被使用。

后续步骤