CapMonster Cloud API
适用于浏览器的扩展程序
在本文中，我们尽量回答了所有关键问题。要开始解决问题，第一步是确定当前使用的是哪种防护系统。为此，您可以查看常见验证码与反机器人防护系统列表，其中提供了可视化示例和关键特征，帮助您快速判断自己正在使用哪一种方案。
如果您发现自己的网站使用的是 reCAPTCHA v2 Enterprise，下一步就是更深入地了解它的特性和具体工作方式。在本文中，您还可以查看 reCAPTCHA v2 Enterprise 的接入说明，以便彻底弄清它在您的网站上是如何运行的。这样一来，您不仅能更好地理解当前的防护机制，还可以更合理地规划后续的维护和支持。
测试包含 reCAPTCHA v2 Enterprise 的表单时，常常需要确认 captcha 是否集成正确并工作正常。
你可以手动验证站点上的 captcha。
若想自动解题，可以使用 CapMonster Cloud 等服务，它会接收验证码参数、在服务器中解析并返回可直接使用的 token。把 token 注入表单即可无需人工操作通过验证。
通过 CapMonster Cloud API 工作的一般流程：
创建任务
发送 API 请求解决请求需包含：
type - RecaptchaV2EnterpriseTask;
websiteURL - 验证码所在页面地址;
websiteKey - 页面上提供的 sitekey;
enterprisePayload - 若验证码控件在调用 grecaptcha.enterprise.render 时与 sitekey 一起传递了额外的 s 字段，请传入该值;
pageAction - 控件发送给 Google 的 action 值（默认 verify）.
https://api.capmonster.cloud/createTask{
"clientKey": "API_KEY",
"task": {
"type": "RecaptchaV2EnterpriseTask",
"websiteURL": "https://mydomain.com/page-with-recaptcha-enterprise",
"websiteKey": "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd",
"pageAction": "verify",
"enterprisePayload": {
"s": "SOME_ADDITIONAL_TOKEN"
}
}
}
{
"errorId":0,
"taskId":407533072
}
获取结果https://api.capmonster.cloud/getTaskResult{
"clientKey":"API_KEY",
"taskId": 407533072
}
{
"errorId": 0,
"status": "ready",
"solution": {
"gRecaptchaResponse": "03AFcWeA66ZARdA5te7acD9vSwWE2hEQ2-B2aqFxm455iMA-g-Jis..."
}
}
将 token 应用到页面import { chromium } from 'playwright';
import { CapMonsterCloudClientFactory, ClientOptions, RecaptchaV2EnterpriseRequest } from '@zennolab_com/capmonstercloud-client';
(async () => {
const browser = await chromium.launch({ headless: false });
const context = await browser.newContext();
const page = await context.newPage();
// 2. 打开包含验证码的页面
await page.goto('https://example.com');
// 3. 创建 CapMonster Cloud 客户端
const cmcClient = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: '<your_capmonster_cloud_api_key>' })
);
// 4. 配置解决请求
const recaptchaRequest = new RecaptchaV2EnterpriseRequest({
websiteURL: page.url(),
websiteKey: '6Lf76sUnAAAAAIKLuWNyegRsFUfmI-3Lex3xT5N'
// enterprisePayload: { s: 'SOME_ADDITIONAL_TOKEN' } // 可选的 Enterprise 参数
});
// 5. 通过 CapMonster 解验证码
const solution = await cmcClient.Solve(recaptchaRequest);
const token = solution.solution.gRecaptchaResponse;
console.log('验证码令牌：', token);
// 6. 将 token 写入隐藏字段
await page.evaluate((t) => {
const el = document.getElementById('g-recaptcha-response');
if (el) el.value = t;
}, token);
// 7.（可选）提交表单 — 根据需要调整选择器
await page.click('button[data-action="submit"]');
await page.waitForTimeout(5000);
await browser.close();
})();由于 reCAPTCHA Enterprise 运行在 Google Cloud 上，你首先需要在控制台中创建一个项目：
1. 打开 Google Cloud Console。
2. 在顶部菜单中选择一个已有项目，或点击 New project 创建新项目。
3. 输入项目名称，填写组织信息并确认创建。
4. 打开 API 页面：reCAPTCHA Enterprise API，然后点击 Enable。
5. 在控制台中进入 Create key 页面，并点击 Create Key。
6. 配置基础设置：
接着打开 Additional Settings，开启 Will you use challenges?，并启用 Checkbox Challenge。
7. 点击 Create。系统会生成一个密钥，你需要把它加入到网站中以启用保护。
8. 将脚本添加到页面。
可嵌入到你网站中的 HTML 示例片段<html>
<head>
<title>reCAPTCHA demo: Simple page</title>
<script src="https://www.google.com/recaptcha/enterprise.js" async defer></script>
</head>
<body>
<form action="" method="POST">
<div class="g-recaptcha" data-sitekey="YOUR_SITEKEY" data-action="LOGIN"></div>
<br/>
<input type="submit" value="Submit">
</form>
</body>
</html>9. 在服务器端验证响应。
PHP 示例令牌 (g-recaptcha-response) 会发送到后端。
它的有效期为 2 分钟，因此请在收到后尽快进行验证！为了与 API 安全通信，我们推荐使用官方的 Google Cloud 库：
<?php
require 'vendor/autoload.php';
// 通过 Composer 安装 Google Cloud 库
use Google/Cloud/RecaptchaEnterprise/V1/RecaptchaEnterpriseServiceClient;
use Google/Cloud/RecaptchaEnterprise/V1/Event;
use Google/Cloud/RecaptchaEnterprise/V1/Assessment;
use Google/Cloud/RecaptchaEnterprise/V1/CreateAssessmentRequest;
use Google/Cloud/RecaptchaEnterprise/V1/TokenProperties/InvalidReason;
/**
* 验证 reCAPTCHA Enterprise 令牌并获取风险评分。
*
* @param string $recaptchaKey 你的网站/应用的 reCAPTCHA 密钥
* @param string $token 从客户端接收到的令牌
* @param string $projectId Google Cloud 项目 ID
* @param string $action 与令牌关联的操作名称（action name）
*/
function create_assessment(string $recaptchaKey, string $token, string $projectId, string $action): void {
$client = new RecaptchaEnterpriseServiceClient();
$projectName = $client->projectName($projectId);
// 创建评估事件（assessment event）
$event = (new Event())->setSiteKey($recaptchaKey)->setToken($token);
$assessment = (new Assessment())->setEvent($event);
$request = (new CreateAssessmentRequest())->setParent($projectName)->setAssessment($assessment);
try {
$response = $client->createAssessment($request);
if (!$response->getTokenProperties()->getValid()) {
echo '令牌无效： ' . InvalidReason::name($response->getTokenProperties()->getInvalidReason());
return;
}
if ($response->getTokenProperties()->getAction() === $action) {
echo '风险评分： ' . $response->getRiskAnalysis()->getScore();
} else {
echo 'reCAPTCHA 标签中的 action 与期望的值不匹配';
}
} catch (Exception $e) {
echo '检查 reCAPTCHA 时出错： ' . $e->getMessage();
}
}
// 使用这些变量调用该函数
create_assessment(
'YOUR_SITE_KEY',
'YOUR_USER_RESPONSE_TOKEN',
'YOUR_PROJECT_ID',
'YOUR_RECAPTCHA_ACTION'
);
?>
如果你接手了一个已经集成了验证码或其他防护系统的网站，但又无法访问其代码，也不用担心！要判断实际使用了哪种技术其实并不难。为了核实其是否正常工作，你可以在隔离的测试环境中使用CapMonster Cloud识别服务，确保令牌处理机制和校验逻辑都运行正常。
对于reCAPTCHA v2 Enterprise，只需识别出所用的系统，观察其行为，并确认防护是否正常工作即可。本文演示了如何识别 reCAPTCHA v2 Enterprise，以及到哪里查找其接入或重新配置的说明文档，从而帮助你自信地维护防护方案并掌控其运行情况。
