验证用户的响应
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
本页介绍了如何从应用的后端验证用户对 reCAPTCHA 质询的响应。
对于 Web 用户,您可以通过以下三种方式之一获取用户的响应令牌:
对于 Android 库用户,您可以调用
SafetyNetApi.RecaptchaTokenResult.getTokenResult()
方法在状态返回成功时获取响应令牌。
令牌限制
每个 reCAPTCHA 用户响应令牌的有效期为两分钟,只能验证一次,
从而防止重放攻击如果您需要新令牌,可以重新运行 reCAPTCHA 验证。
获得响应令牌后,您需要在两分钟内通过 reCAPTCHA 使用
以下 API 来确保令牌有效。
API 请求
URL:https://www.google.com/recaptcha/api/siteverify
方法:POST
POST 参数 |
说明 |
secret |
必需。您的网站与 reCAPTCHA 之间的共享密钥。 |
response |
必需。您网站上的 reCAPTCHA 客户端集成提供的用户响应令牌。 |
remoteip |
可选。用户的 IP 地址。 |
API 响应
响应是一个 JSON 对象:
{
"success": true|false,
"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
}
对于 reCAPTCHA Android:
{
"success": true|false,
"challenge_ts": timestamp, // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
"apk_package_name": string, // the package name of the app where the reCAPTCHA was solved
"error-codes": [...] // optional
}
错误代码参考
错误代码 |
说明 |
missing-input-secret |
缺少 Secret 参数。 |
invalid-input-secret |
Secret 参数无效或格式错误。 |
missing-input-response |
缺少响应参数。 |
invalid-input-response |
响应参数无效或格式错误。 |
bad-request |
请求无效或格式错误。 |
timeout-or-duplicate |
响应不再有效:过旧或以前使用过。 |
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2025-07-25。
[null,null,["最后更新时间 (UTC):2025-07-25。"],[[["\u003cp\u003eThis page details how to verify if a user successfully completed a reCAPTCHA challenge on your website or Android app.\u003c/p\u003e\n"],["\u003cp\u003eYou'll receive a response token from the reCAPTCHA integration that needs to be verified within two minutes using the reCAPTCHA API.\u003c/p\u003e\n"],["\u003cp\u003eVerification involves sending a POST request to the reCAPTCHA API with the secret key, response token, and optionally, the user's IP address.\u003c/p\u003e\n"],["\u003cp\u003eThe API response is a JSON object indicating success or failure, along with details like timestamp and potential error codes.\u003c/p\u003e\n"],["\u003cp\u003eEach response token is valid for a single use and expires after two minutes to prevent replay attacks.\u003c/p\u003e\n"]]],["To verify a user's reCAPTCHA response, obtain the response token via the `g-recaptcha-response` parameter, `grecaptcha.getResponse()`, or a callback function for web users or the `SafetyNetApi.RecaptchaTokenResult.getTokenResult()` method for Android. Then, within two minutes, send a POST request to `https://www.google.com/recaptcha/api/siteverify` with `secret` (your site's key) and `response` (the user token). The optional `remoteip` can be included. The JSON response indicates success, timestamp, and hostname or `apk_package_name` if Android, and error codes if any.\n"],null,["# Verifying the user's response\n\nThis page explains how to verify a user's response to a reCAPTCHA challenge from your application's\nbackend.\n\nFor web users, you can get the user's response token in one of three ways:\n\n- `g-recaptcha-response` POST parameter when the user submits the form on your site\n- [`grecaptcha.getResponse(opt_widget_id)`](/recaptcha/docs/display#js_api) after the user completes the reCAPTCHA challenge\n- As a string argument to your [callback function](/recaptcha/docs/display#render_param) if `data-callback` is specified in either the `g-recaptcha` tag attribute or the callback parameter in the `grecaptcha.render` method\n\nFor Android library users, you can call the\n[SafetyNetApi.RecaptchaTokenResult.getTokenResult()](https://developers.google.com/android/reference/com/google/android/gms/safetynet/SafetyNetApi.RecaptchaTokenResult.html#getTokenResult())\nmethod to get response token if the status returns successful.\n\nToken Restrictions\n------------------\n\nEach reCAPTCHA user response token is valid for two minutes, and can only be verified *once* to\nprevent replay attacks. If you need a new token, you can re-run the reCAPTCHA verification.\n\nAfter you get the response token, you need to verify it within two minutes with reCAPTCHA using the\nfollowing API to ensure the token is valid.\n\nAPI Request\n-----------\n\nURL: `https://www.google.com/recaptcha/api/siteverify`\n\nMETHOD: `POST`\n\n| POST Parameter | Description |\n|----------------|---------------------------------------------------------------------------------------------------|\n| `secret` | Required. The shared key between your site and reCAPTCHA. |\n| `response` | Required. The user response token provided by the reCAPTCHA client-side integration on your site. |\n| `remoteip` | Optional. The user's IP address. |\n\nAPI Response\n------------\n\nThe response is a JSON object: \n\n {\n \"success\": true|false,\n \"challenge_ts\": timestamp, // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)\n \"hostname\": string, // the hostname of the site where the reCAPTCHA was solved\n \"error-codes\": [...] // optional\n }\n\nFor reCAPTCHA Android: \n\n {\n \"success\": true|false,\n \"challenge_ts\": timestamp, // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)\n \"apk_package_name\": string, // the package name of the app where the reCAPTCHA was solved\n \"error-codes\": [...] // optional\n }\n\n### Error code reference\n\n| Error code | Description |\n|--------------------------|---------------------------------------------------------------------------------|\n| `missing-input-secret` | The secret parameter is missing. |\n| `invalid-input-secret` | The secret parameter is invalid or malformed. |\n| `missing-input-response` | The response parameter is missing. |\n| `invalid-input-response` | The response parameter is invalid or malformed. |\n| `bad-request` | The request is invalid or malformed. |\n| `timeout-or-duplicate` | The response is no longer valid: either is too old or has been used previously. |"]]