C# 中的 Yandex SmartCaptcha:用 YandexSmartAsync 识别

yandex smartcaptcha in c# - Yandex SmartCaptcha in C#: Solve It With YandexSmartAsync

要在 C# 里不借助自己的浏览器识别 Yandex SmartCaptcha,就用一个会保存 cookie 的 HttpClient 获取页面,从小组件的 data-sitekey 属性里读出 sitekey,再把它交给 CapSkip NuGet 包里的 YandexSmartAsync。返回的 token 填进表单字段 smart-token,并且提交时使用识别时给出的同一个 User-Agent(我的模拟服务器强制要求这一点,没有哪个真实站点被证明会这样做)。识别工作发生在你自己的 Windows PC 上,用的是 CapSkip Yandex SmartCaptcha 识别工具,不按 token 收费。

你需要什么

  • 在 Windows PC 上安装 CapSkip,版本要列出 Yandex SmartCaptcha(更新日志显示从 CapSkip 5.0.0 开始支持)。请按照 设置指南。我无法读取正在运行的应用的版本,所以下面的所有结果都来自模拟服务器。
  • 一个 .NET SDK(我用的是 10.0.100,只装了 8 SDK 的机器没有试过),以及 CapSkip NuGet 包 1.8.0,这是第一个带 YandexSmartAsync 的版本。它的 nuspec 只声明了一个目标 netstandard2.0 和一个依赖 System.Text.Json 8.0.5。我的代码在 net8.0(运行时 8.0.27)和 net10.0(运行时 10.0.0)上运行过,两者都是用 SDK 10.0.100 构建的,更旧的版本都没有试过。
  • 一个带有 SmartCaptcha 小组件、并且你被允许自动化操作的注册、登录或联系页面。
  • CapSkip 的地址。Local mode 让识别工具留在 127.0.0.1,只有同一台 PC 才能访问。Server mode 还会监听你的网络地址或公网 IP,供其他机器调用。在 连接设置 里选择使用哪一种。

下面的一切都针对模拟服务器运行。它扮演 in.php、res.php 和一个注册站点,表单规则是我定的。没有联系任何 Yandex 页面,也没有产生真实的 token,所以我无法说明真实的 token 长什么样,也无法说明真实的识别要花多久。

第 1 步:创建项目并读取页面

dotnet new console -o yandex-demo
cd yandex-demo
dotnet add package CapSkip --version 1.8.0

用 SDK 10 创建的新项目,目标是 net10.0。要为 net8.0 构建,请打开 yandex-demo.csproj,把 TargetFramework 那一行改成 net8.0。删除 Program.cs 里的全部内容,然后按顺序粘贴下面三个 C# 代码块。只有第一个带有 using 行。

Yandex 把这个小组件描述为一个空的 div,带有 smart-captcha 类,客户端密钥放在 data-sitekey 里。如果页面用自己的脚本绘制小组件,则会把同一个密钥传给 smartCaptcha.render,正如 CapSkip API 文档 中的 Yandex 部分所说明的。访客通过后,小组件会在容器里插入一个名为 smart-token 的隐藏 input,所以你下载的 HTML 里没有这个字段,需要由代码自己添加(参见 Yandex 的 快速入门).

用正则表达式读取密钥,必须应付属性顺序、引号风格和外观相似的内容,所以第一个代码块只查看 class 属性里列出 smart-captcha 的标签。地址里带有这个名字的样式表或脚本文件,或者同名的 id,都不算。它会逐个尝试这样的标签,先找 data-sitekey,再回退到 smartCaptcha.render 调用。针对我的模拟服务器,它在两个运行时上都在八种页面形态里读出了正确的密钥:data-sitekey 在 class 之后;在 class 之前并使用单引号;不带引号;小组件上方有一个用这个名字的样式表和一个脚本;密钥只出现在 render 调用里;一个 id div 紧挨着 render 调用;一个 id div 包着真正的小组件;以及真正的表单上方有一个搜索表单。把密钥放在变量里的写法,比如 sitekey: k,不被支持,会抛出没有 sitekey 的异常。

接着,这个代码块只在包含小组件的那个表单里工作,所以页面上更靠前的搜索表单不会被当成真正的表单。它把该表单的隐藏 input 复制到一个字典里,CSRF 字段就是这样随表单提交一起送出的,并读取它的 action。SDK 自己会检查密钥:16 到 120 个字母、数字、下划线或连字符,通常以 ysc1_ 开头。

using System.Net;
using System.Text.RegularExpressions;
using CapSkip;
// Implicit usings import System, which has a TimeoutException too (a bare one fails with CS0104).
using SolverTimeout = CapSkip.TimeoutException;

// What the page gives you: the sitekey, the form that holds the widget, and its hidden fields.
record PageForm(string Sitekey, string Action, Dictionary<string, string> Hidden);

static class Page
{
    // A tag whose class attribute lists smart-captcha, in any attribute order. A stylesheet,
    // a script src or an id of the same name does not count.
    static readonly Regex Widget = new(@"<[^>]*\bclass\s*=\s*(?<q>[""'])[^""']*(?<![\w-])smart-captcha(?![\w-])[^""']*\k<q>[^>]*>", RegexOptions.IgnoreCase);
    static readonly Regex DataKey = new(@"data-sitekey\s*=\s*(?<q>[""']?)(?<k>[\w-]+)\k<q>", RegexOptions.IgnoreCase);
    // Pages that draw the widget from script pass a quoted key to smartCaptcha.render.
    static readonly Regex Render = new(@"smartCaptcha\.render\([^;]*?sitekey\s*:\s*(?<q>[""'])(?<k>[^""']+)\k<q>", RegexOptions.Singleline);
    static readonly Regex Input = new(@"<input\b[^>]*>", RegexOptions.IgnoreCase);
    static readonly Regex Attr = new(@"(?<n>[\w-]+)\s*=\s*(?<q>[""'])(?<v>[^""']*)\k<q>");
    static readonly Regex FormAction = new(@"<form\b[^>]*\baction\s*=\s*(?<q>[""'])(?<a>[^""']*)\k<q>", RegexOptions.IgnoreCase);

    public static PageForm Read(string html)
    {
        string? sitekey = null;
        var at = 0;
        foreach (Match tag in Widget.Matches(html))
        {
            var k = DataKey.Match(tag.Value);
            if (k.Success) { sitekey = k.Groups["k"].Value; at = tag.Index; break; }
        }
        if (sitekey is null)
        {
            var r = Render.Match(html);
            if (r.Success) { sitekey = r.Groups["k"].Value; at = r.Index; }
        }
        if (sitekey is null) throw new InvalidDataException("no SmartCaptcha sitekey on the page");

        // Work inside the form that holds the widget, so a search box above it is ignored.
        var start = Math.Max(0, html.LastIndexOf("<form", at, StringComparison.OrdinalIgnoreCase));
        var end = html.IndexOf("</form", at, StringComparison.OrdinalIgnoreCase);
        var form = html.Substring(start, (end < 0 ? html.Length : end) - start);

        var hidden = new Dictionary<string, string>();
        foreach (Match input in Input.Matches(form))
        {
            var a = new Dictionary<string, string>();
            foreach (Match m in Attr.Matches(input.Value))
                a[m.Groups["n"].Value.ToLowerInvariant()] = WebUtility.HtmlDecode(m.Groups["v"].Value);
            if (a.GetValueOrDefault("type") == "hidden" && a.TryGetValue("name", out var name))
                hidden[name] = a.GetValueOrDefault("value", "");
        }
        return new PageForm(sitekey, FormAction.Match(form).Groups["a"].Value, hidden);
    }
}

第 2 步:用 YandexSmartAsync 识别并发送表单

第二个代码块完成一次完整的提交:获取页面、识别、提交表单。有三个细节要紧。

第一,HttpClient 拥有一个 CookieContainer,所以从页面获取中得到的会话 cookie 会随表单提交一起发出,从页面复制来的 CSRF 字段也就和它匹配。第二,页面获取、userAgent 选项和表单提交使用同一个 User-Agent 字符串。这个选项告诉 CapSkip 向 Yandex 出示哪个 User-Agent(SDK 文档)。在我的模拟服务器里,站点会把表单提交的 User-Agent 和任务携带的那个做比较:用 Other/1.0 发送的任务在三次尝试里全部得到 403,而不带该选项发送的任务没有携带任何 User-Agent,顺利通过。这条规则是我定的,所以这个模拟服务器无法证明 Yandex 或任何真实站点在乎这一点。保持一个字符串只需要一个常量。如果你省略这个选项,CapSkip API 文档说会出示当前的 Chrome User-Agent,它不会等于 HttpClient 发送的字符串。

第三,识别要放在获取页面之后、提交之前,并且每次都用新的页面。Yandex 说一个 token 的有效期是五分钟,并且只能被检查一次(见验证文档),所以重复使用或囤积的 token 会失败。我无法判断被拒绝的表单提交是否会用掉 token,所以下一步里的循环会在每次被拒绝后重新获取页面,再识别一次。Referer 这一行之所以在那里,是因为有些框架会拒绝既没有 Referer 也没有 Origin 的表单提交,而 HttpClient 自己两个都不发。把这一行删掉后,我的模拟服务器拒绝了全部三次尝试,因为我就是这样写它的。

static class Flow
{
    // One string, used for the page fetch, the solve and the form post.
    public const string UserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36";

    // Local mode. In Server mode, use your server's address instead. If API Key
    // Validation is on in CapSkip, also pass apiKey: "YOUR_KEY" here.
    public static readonly CapSkipClient Solver = new(host: "127.0.0.1", port: 8080);

    public static HttpClient NewHttp()
    {
        var http = new HttpClient(new HttpClientHandler { CookieContainer = new CookieContainer(), UseCookies = true });
        http.DefaultRequestHeaders.TryAddWithoutValidation("User-Agent", UserAgent);
        return http;
    }

    // One whole submission: fresh page, fresh token, form post. Never reuse a token.
    public static async Task<(int Status, string Text)> Submit(HttpClient http, string pageUrl, string email, CancellationToken ct)
    {
        var form = Page.Read(await http.GetStringAsync(pageUrl, ct));

        // Solve after the page is in hand and right before the post: a token lives 5 minutes.
        var solved = await Solver.YandexSmartAsync(form.Sitekey, pageUrl,
            new Dictionary<string, object?> { ["userAgent"] = UserAgent }, ct);

        var fields = new Dictionary<string, string>(form.Hidden) { ["email"] = email, ["smart-token"] = solved.Token! };
        using var request = new HttpRequestMessage(HttpMethod.Post, new Uri(new Uri(pageUrl), form.Action))
        {
            Content = new FormUrlEncodedContent(fields),
        };
        request.Headers.Referrer = new Uri(pageUrl);   // some frameworks refuse a post without one
        using var response = await http.SendAsync(request, ct);
        var body = await response.Content.ReadAsStringAsync(ct);
        return ((int)response.StatusCode, Regex.Replace(body, "<[^>]+>", " ").Trim());
    }
}

结果里有两份 token,分别是 Token 和 Code,在我的探测中它们是同一个字符串。请使用 Token。保留 Code 是为了让针对其他 2Captcha 客户端写的代码继续可用,那种代码对所有验证码类型都只读一个字段。下面是 YandexSmartAsync 接受的选项,依据 1.8.0 的源码和文档列出。

选项作用在模拟服务器中见到的结果
userAgentCapSkip 向 Yandex 出示的 User-Agent。名称 "useragent" 和 "user_agent" 也可以到达时的名称是 "useragent"。空字符串不会被发送
proxy一个 Proxy 对象、一个普通地址,或者一对 type 和 uri到达时是 proxy 加 proxytype HTTP
"timeout" 和 "polling_interval"继续轮询的秒数,以及两次轮询之间的最长停顿,与其他方法相同默认客户端上 timeout 为 5 时,一个始终未就绪的任务在 7.85 秒(net8.0)和 7.86 秒(net10.0)后结束。polling interval 为 1 时,两者都在 3.87 秒后给出了 token
pageurl代替 url 参数url 为 null 且设置了 pageurl 时,pageurl 被发送了出去

除了 SDK 自己的 timeout 和 polling_interval,其他任何选项都会被拒绝。传入 MTCaptcha 接受的 action,或者 hCaptcha 接受的 invisible,会在发出任何请求之前抛出 ValidationException。如果站点会读取访客地址并把它发给 Yandex,CapSkip Yandex 页面说,识别和表单提交要使用同一个代理。 代理指南 介绍了设置步骤。

第 3 步:端到端运行 Yandex SmartCaptcha C# 示例

最后一个代码块包含 Main。把 PageUrl 指向你自己的注册页面,因为第一次针对 example.com 运行时,会因页面获取失败而打印一条 404 消息,永远到不了小组件。用 dotnet run 运行它。最多三次提交共用一个取消预算,表单的回应低于 400 就结束运行。CapSkip 报错也会结束运行,因为再发一次同样的任务不会改变答案。

预算是十分钟,因为每次识别最多可能等待 recaptchaTimeout(默认 300 秒),所以两次卡住的尝试就会用光全部预算(这是根据默认值算出来的,不是运行结果)。如果你的站点等不了那么久,就调低这个预算。

static class Program
{
    const string PageUrl = "https://example.com/signup";  // the page that shows the SmartCaptcha widget

    static async Task<int> Main()
    {
        // Solves may take a while, so one budget covers every attempt below.
        using var budget = new CancellationTokenSource(TimeSpan.FromMinutes(10));
        using var http = Flow.NewHttp();
        try
        {
            for (var attempt = 1; attempt <= 3; attempt++)
            {
                var (status, text) = await Flow.Submit(http, PageUrl, "[email protected]", budget.Token);
                Console.WriteLine($"attempt {attempt}: {status} {text}");
                if (status < 400) return 0;
            }
            Console.WriteLine("the site refused 3 submissions");
        }
        catch (Exception) when (budget.IsCancellationRequested) { Console.WriteLine("the 10 minute budget ran out"); }
        catch (ValidationException ex) { Console.WriteLine($"CapSkip refused the call: {ex.Message}"); }
        catch (ApiException ex) { Console.WriteLine($"CapSkip answered {ex.Message}"); }
        catch (SolverTimeout ex) { Console.WriteLine($"no token in time: {ex.Message}"); }
        catch (CapSkipError ex) { Console.WriteLine($"{ex.GetType().Name}: {ex.Message}"); }
        // HttpClient's own timeout is a TaskCanceledException wrapping System.TimeoutException.
        catch (TaskCanceledException ex) when (ex.InnerException is System.TimeoutException) { Console.WriteLine("the site answered too slowly"); }
        catch (HttpRequestException ex) { Console.WriteLine($"the site did not answer: {ex.Message}"); }
        catch (InvalidDataException ex) { Console.WriteLine(ex.Message); }
        return 1;
    }
}

超时与取消

Yandex 的识别使用 recaptchaTimeout(默认 300 秒),而不是 defaultTimeout,因为 CapSkip 是在真实的浏览器里通过这个小组件的(SDK 源码)。我用模拟服务器检查了这一点。把 defaultTimeout 设为 3,而任务到第六次轮询才就绪时,调用在 7.86 秒后返回了 token,两个运行时都是如此,所以这个较短的超时被忽略了。把 recaptchaTimeout 设为 5,而任务始终未就绪时,CapSkip 的 TimeoutException 在 7.83 到 7.87 秒后到达,两个运行时共八次运行,都不是在 5 秒时。模拟服务器记录的轮询发生在大约 0、0.26、0.78、1.78 和 3.8 秒。随后 SDK 休眠了 4 秒,发现截止时间已过,就抛出异常,没有进行第六次轮询,因为它只在每次休眠之后才看时钟。

这里会遇到两种 TimeoutException。隐式 using 会导入 System,而它有自己的 TimeoutException,所以在 using CapSkip 旁边写一个不带限定的 catch,会因为错误 CS0104 而无法构建,两个运行时上都是如此。第一个代码块顶部的 using 行把 SDK 的类重命名成了 SolverTimeout。HttpClient 又增加了第三个来源:它自己的超时不是 CapSkipError。对一个休眠三秒的模拟页面设置一秒的 Timeout,表现为一个 TaskCanceledException,它的 InnerException 是 System.TimeoutException,在两个运行时上都是 1.02 秒后出现。

CancellationToken 同时作用于页面获取和 CapSkip 调用。在模拟服务器里,2 秒的预算在两个地方耗尽。当模拟服务器让 in.php 一直挂着时,异常是一个包着 TaskCanceledException 的 NetworkException。当 SDK 正在轮询时,则是一个单独的 TaskCanceledException。两者都在大约 2.0 秒后出现。Main 自己检查预算,所以一个过滤器就能覆盖这两种形态。

下面是模拟服务器的结果。它们不能说明真实站点的情况,在 net8.0 和 net10.0 上完全相同。

模拟设置程序的表现
默认设置,三种页面形态中的任意一种200 账号已创建,一个任务
站点对第一次表单提交返回 403第二次尝试使用新页面和新任务,然后 200
站点拒绝每一次表单提交三次尝试,三个任务,退出码 1
ERROR_RECAPTCHA_INVALID_DOMAIN 或 ERROR_RECAPTCHA_INVALID_SITEKEY打印出回复,退出码 1,一个任务,不重试
没有小组件的页面一条消息,退出码 1,没有发送任务
CapSkip 地址上没有任何监听NetworkException,退出码 1

常见错误

你所看到的原因修复
ValidationExceptionSDK 在发送之前就拒绝了这次调用:sitekey 不在 16 到 120 个允许的字符范围内,页面地址不是绝对的 http 或 https URL,代理类型不受支持,或者用了 Yandex 方法没有的选项。有十一次这样的调用被拒绝,没有一次到达模拟服务器修正参数。重试没有用
ERROR_RECAPTCHA_INVALID_SITEKEY 或 ERROR_RECAPTCHA_INVALID_DOMAINYandex 不认识这个密钥,或者它不允许在该域名上使用(API 文档;我的模拟服务器在第一次轮询时就会抛出这两种错误)重新从页面读取密钥和地址。不要重试
ERROR_CAPTCHA_UNSOLVABLE没有通过挑战(API 文档列出了它;我只能在模拟服务器里触发它)用新的页面开始一次新的提交
ERROR_PROXY_CONNECT_REFUSED任务无法通过它的代理连接到 Yandex(SDK 文档)检查代理地址
CapSkip TimeoutException在 recaptchaTimeout 内没有 token,到下一次轮询时才发现调大 recaptchaTimeout,或者检查 CapSkip
站点拒绝了这个表单按 Yandex 文档,是 token 已过期或已被检查过。在我的模拟服务器里,User-Agent 不同或没有 Referer 也会如此一次完成获取、识别和重新提交

Server 模式:CapSkip 在另一台 PC 上

CapSkip 也可以在你掌控的 Windows 机器上作为服务器运行,所以这个程序可以放在另一台 PC 或主机上,通过 API 调用识别工具。把 CapSkipClient 那一行里的 127.0.0.1 换成那台机器的地址,模式的设置位置见 连接设置.

Server mode 会让 CapSkip 的端口对所有地址可达。请用一条覆盖所有你不预期的机器的 Windows Firewall 阻止规则来收窄范围,并且同时开启 API Key Validation,在 CapSkipClient 那一行里传入 apiKey。

常见问题

在 C# 里识别 Yandex SmartCaptcha 需要浏览器吗?

识别本身不需要:CapSkip 自己驱动小组件。只有当页面用脚本构建表单、导致直接下载的页面里看不到可以提交的表单时,你才需要浏览器。这时请使用浏览器工具,并从加载完成的页面里读取 sitekey。

谁来检查 token?

站点自己的服务器。它把 token 和它的服务端密钥一起发给 Yandex,Yandex 再回复一个状态。你永远不会持有那个密钥。不要在提交表单之前自己去检查 token,因为一个 token 只能被检查一次。

一次识别需要多长时间?

CapSkip Yandex 页面说通常需要 15 到 30 秒。我无法测量,因为没有进行真实的识别。请用 recaptchaTimeout 和 CancellationToken 来做预算。

C# 里的 Yandex SmartCaptcha 归结为一次页面获取、一次 YandexSmartAsync 调用,以及一次复用同一个 User-Agent 的表单提交。使用统一授权、运行在你自己 PC 上的 本地验证码识别工具 时,表单被拒绝只会损失几秒钟,不产生费用。.NET 里其他验证码类型见 C# 验证码识别页面,原始请求格式见 API 文档.