Turnstile Solver API 检查清单：输入、令牌和验证

快速摘要

• 根据您允许的工作流所需的确切小部件和结果契约评估Turnstile求解器API。
• 保持求解器服务密钥、公共Turnstile网站密钥和网站所有者的验证密钥分开；它们服务于不同的系统。
• 在评估延迟或价格之前，检查已记录的任务输入和令牌字段。
• 一个准备好的求解任务和一个被接受的应用程序操作是不同的结果，需要分开的证据。
• 使用确定性测试密钥检查应用程序行为，然后在拥有权限的环境中使用适当的凭证单独评估真实求解。
• 明确记录不支持或未经验证的要求，而不是将通用的“Cloudflare支持”声明视为充分条件。

Turnstile求解器API可能会返回成功响应，而您的应用程序仍会拒绝该操作。集成可能选择了错误的小部件，遗漏了应用程序元数据，读取了错误的解决方案字段，或在尝试不再有效后提交。一个有用的评估会在团队承诺维护集成之前识别这些不匹配。

CapSolver 记录了一个Turnstile任务契约，可以作为此审查的具体示例。以下清单重点在于输入、结果、验证和可复现的证据，适用于自有QA工作流程。它不排名供应商或报告测量的成功率。其目的是帮助您决定特定求解器接口是否符合您实际运营的应用程序。

Turnstile求解器评估应确立什么？

Turnstile求解器评估应确立与所需任务的兼容性、可用的结果契约，以及证明预期应用程序可以接受结果的证据。

从自有应用程序和测试操作开始。记录预期的页面、小部件配置和完成条件。一个联系表单测试可能需要服务器接受测试提交并返回其接收标识符。收到令牌将是早期里程碑，而不是最终结果。

将此技术评估范围限制在一般采购练习之外。CAPTCHA API选择指南涵盖了更广泛的集成和操作考虑因素。此处的核心问题是Turnstile任务的输入和输出契约是否与特定应用程序匹配。

API测试术语表提供了更广泛的测试背景。对于求解器而言，HTTP响应只是该背景的一部分：测试还需要保留哪个应用程序尝试请求了结果以及什么会使该尝试完成。

检查1：确认正确的机制和密钥角色

确认操作使用了嵌入的Turnstile组件，并区分每个密钥所属的服务。

Cloudflare的 Turnstile设置指南 描述了公共网站密钥和私有服务器端密钥。网站密钥标识小部件的集成。网站所有者的密钥属于服务器端验证步骤。求解器服务凭证用于认证对独立求解服务的请求。

不要仅仅因为任务要求密钥就将网站所有者的验证密钥放入求解任务中。在记录的CapSolver Turnstile任务中，websiteKey 指的是公共网站密钥，而 clientKey 用于认证CapSolver请求。在处理真实凭证之前，请先查看每个字段的去向。

同时确认页面是Turnstile集成，而不是其他Cloudflare挑战体验。通用的覆盖声明不足以证明与同一供应商名称的每个机制兼容。如果页面的机制不确定，请在创建付费测试任务之前解决该不确定性。

您的评估记录应明确命名确切支持的任务，并列出用于选择它的应用程序证据。当后续页面更改使相同集成行为不同时，该记录将变得有用。

检查2：匹配已记录的输入契约

将每个所需任务输入与自有应用程序当前状态中的可靠来源匹配。

CapSolver Turnstile任务参考 记录了 AntiTurnstileTaskProxyLess、websiteURL 和 websiteKey。可选元数据包括 action 和 cdata，其中集成提供这些内容。这些字段应来自相关应用程序上下文，而不是从无关示例中复制的值。

将可选数据作为兼容性要求进行审查

服务模式中的可选字段仍可能对特定应用程序重要。如果您的应用程序使用操作元数据，请在评估中包含该要求，并确认所选接口的映射。不要因为两种机制都使用“action”一词而替换为reCAPTCHA特定字段。

SDK和底层JSON API可能暴露不同的名称或嵌套。如果评估包括SDK，请作为单独步骤检查其记录的字段映射。任意 extra 字典的存在并不能证明特定值会到达正确的任务字段。

避免虚构的代理和浏览器要求

CapSolver当前的Turnstile任务参考指定了无代理任务，并说明调用者提供的自定义User-Agent在此任务中被忽略。不要因为另一个CAPTCHA任务有这些参数而添加代理或声称控制求解浏览器。

如果某要求对您的环境很重要但任务文档未描述，请标记为未解决，并在依赖之前获得具体答案。这比假设熟悉字段名称意味着跨任务家族等效行为更有用。

检查3：理解任务和结果生命周期

了解服务如何识别进行中的任务以及完成的Turnstile令牌返回位置。

createTask API 定义了服务请求包。对于异步任务，请将返回的任务标识符与创建它的应用程序尝试一起保留。getTaskResult API 定义了结果检索，并将处理与就绪和错误分开。

对于记录的Turnstile任务，解决方案包括 token 字段。不要假设每个CAPTCHA任务都使用reCAPTCHA风格的字段名称，或假设非空响应体已经是可用解决方案。您的映射应足够具体，使意外结果形状产生显式失败。

评估调用者失去连接、收到服务错误或停止等待时会发生什么。本地超时不应自动解释为证明提供者从未创建任务。如果第一个请求的结果未知，请避免盲目创建替代工作。

本文提供了一个契约检查表，而不是新的轮询实现。使用官方任务示例作为实现起点，然后在您自己的环境中测试所选客户端及其失败策略。此处不声称任何实时提供者调用或时间结果。

领取您的CapSolver优惠代码

立即提升您的自动化预算！
在充值CapSolver账户时使用优惠代码 CAP26，每次充值可获得额外 5% 的奖励 —— 无限制。
现在在您的 CapSolver仪表板 中领取

检查4：将令牌验证与求解分开

令牌验证属于应用程序服务器，必须与求解器的任务就绪响应分开。

Cloudflare的 Siteverify文档 要求服务器端验证。它描述了Turnstile令牌为一次性且有效五分钟。应用程序还需要根据其集成检查相关返回上下文，例如预期的主机名和操作。

这些属性会影响评估设计。已兑换的令牌不能作为可重复使用的成功固定点。长时间的应用程序队列也可能使即使早些时候完成求解的响应变得不可用。分别测量步骤，以免延迟的应用程序工作与提供者处理混淆。

使用应用程序的真实接受条件

对于自有联系表单测试，将服务器接受预期测试操作作为最终检查。客户端成功回调是客户端事件的证据。成功的Siteverify响应是验证的证据。表单之后仍可能因其他应用程序规则而失败。

保持证据精确。如果验证通过但缺少所需表单数据，请报告应用程序拒绝而不是求解器失败。如果任务从未返回结果，请报告该阶段。一个“失败”标志会使选择正确修复或比较两个集成版本变得困难。

不要将原始求解器凭证、验证密钥或完整令牌发送到通用日志中。记录足够的标识符和原因类别以诊断尝试，同时限制对团队所需额外证据的访问。

检查5：将确定性测试与真实求解分开

使用确定性应用程序测试进行可预测行为，并为真实服务证据使用单独的授权求解测试。

Cloudflare的 测试指南 提供了具有可控结果的虚拟网站密钥和秘密密钥。这些对于检查应用程序处理成功验证和失败路径非常有用，而无需依赖可变挑战。

它们不衡量求解器生成可接受生产结果的能力。虚拟令牌及其匹配的测试密钥属于测试契约。不要将始终通过的固定点作为商业求解器达到特定成功率的证据。

对于真实求解，使用您拥有或明确授权测试的环境，具有相关生产类似配置和该测试所需的服务凭证。限制流量，避免从合成提交生成面向客户的消息，并提前决定测试何时停止。

如果该环境或凭证缺失，请完成文档和本地映射审查，并将真实服务阶段标记为未验证。明确缺失的先决条件是有效的评估结果。伪造成功响应会消除评估本应收集的证据。

有用的评估工作表应包含哪些情况？

有用的表格在测试运行前记录每个相关阶段的预期结果。

情况	预期处理	保留的证据
必需输入缺失	拒绝请求或捕获记录的错误	字段名称和脱敏错误类别
可选应用程序元数据重要	确认正确值映射到任务	映射审查和自有测试上下文
任务仍在处理	在其预算内保持尝试待定	任务引用和状态转换
返回令牌	将其与原始活动尝试关联	结果形状和相关记录
验证拒绝令牌	保留服务器的原因并停止该提交	脱敏验证结果
表单在完成前更改	在使用结果前重新评估预期操作	表单版本或尝试身份
普通应用程序规则失败	单独报告应用程序失败	应用程序断言和响应类别

此表格是一个建议的测试计划，而不是完成的测试结果。添加特定于应用程序的要求，而不是用不影响决策的情况来扩大列表。

例如，具有多个小部件的页面需要明确的表单到小部件关联。能够重启的工作者需要定义处理其已知进行中任务的方式。这些要求属于应用程序和客户端共同；不应从提供者主页的措辞中推断。

在确认兼容性后如何比较成本和延迟？

在理解所需输入和验证路径后，仅在相同允许的工作负载上比较成本和延迟。

记录任务创建时间、解决方案可用性、验证完成和最终应用程序结果作为单独事件。在报告中包括未成功的尝试。仅包含成功样本的延迟图表可能隐藏长时间失败，而排除重试的成本计算可能低估接受操作的费用。

使用评估服务的实际计费行为和发票或使用证据。不要假设失败任务总是被收费、总是退款或包含在特定计划中。这些是需要当前验证的服务特定条款。

报告尝试的操作数量、应用程序接受的数量和未解决的尝试，以及任何百分比。将挑战配置、应用程序版本和评估窗口附加到报告中，以便后续审查者理解发生了什么变化。

此技术检查表不提供测量的供应商排名。它提供在对您的工作负载有意义的排名或采购决策之前所需的确证要求。

从完成的契约审查中做出集成决策

当记录的任务契约和您观察到的接受结果符合应用程序要求时，选择Turnstile求解器接口。

记录已验证的内容、失败的内容和未测试的内容。如果输入映射清晰但服务器验证从未执行，该区别应在决策中保持可见。对于支持的允许工作流，CapSolver 可以提供求解步骤，而您的应用程序保留对预期操作及其最终结果的责任。

常见问题

Q: 求解器需要我的Turnstile密钥吗？
文档中的CapSolver Turnstile任务使用公共的websiteKey和CapSolver的clientKey。站点所有者的Turnstile密钥属于服务器端验证，不是该求解器任务中的字段。

问：就绪任务是否等同于成功提交表单？

答：就绪任务表示求解结果已可用。应用程序仍需进行令牌验证和自身的接受检查，才能将操作视为完成。

问：模拟密钥能否衡量求解器准确性？

答：模拟密钥测试受控的应用程序行为。它们不能建立商业求解准确率或生产接受率。

问：我应该为每个Turnstile任务添加代理吗？

答：请遵循特定任务的文档。CapSolver目前为Turnstile记录了AntiTurnstileTaskProxyLess；其他验证码任务的要求不应自动复制到其中。

问：如果所需功能未被记录，我该怎么办？

答：将该功能标记为未解决，并在依赖它之前获取可验证的信息。不要将广泛覆盖声明或类似名称的SDK字段视为证明。