ASP.NET Core 백엔드에서 solvethree 호출하기

먼저 콘솔에서 워크스페이스의 대상 사이트 프로필을 활성화하세요. 호스트명과 액션을 전송해도 프로필은 생성되지 않습니다. 사이트가 아직 설정되지 않았다면 사이트 프로필 설정을 참고하세요.

서버 구성에 워크스페이스 키를 SOLVETHREE_API_KEY로 저장하세요. 클라이언트 클래스를 추가한 다음, Program.cs 아래에 표시된 등록 코드의 주석을 해제하고 builder.Build() 앞에 배치하세요.

// CaptchaClient.cs; .NET 8+, System.Net.Http.Json and System.Text.Json.Nodes.
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json.Nodes;

public sealed class CaptchaClient(HttpClient http)
{
    public async Task<JsonObject> CreateAsync(string site, string proxy, string requestId,
        CancellationToken cancellationToken)
    {
        using var response = await http.PostAsJsonAsync("tasks?waitMs=0",
            new { site, action = "login", proxy, requestId }, cancellationToken);
        response.EnsureSuccessStatusCode();
        return (await response.Content.ReadFromJsonAsync<JsonObject>(cancellationToken))!;
    }
    public async Task<JsonObject> GetAsync(string id, CancellationToken cancellationToken)
    {
        using var response = await http.GetAsync("tasks/" + Uri.EscapeDataString(id) + "?waitMs=15000",
            cancellationToken);
        response.EnsureSuccessStatusCode();
        return (await response.Content.ReadFromJsonAsync<JsonObject>(cancellationToken))!;
    }
}
// Program.cs, before builder.Build(), in an existing authenticated ASP.NET app:
// builder.Services.AddHttpClient<CaptchaClient>(http => {
//     http.BaseAddress = new Uri("https://api.solvethree.com/v1/");
//     http.Timeout = TimeSpan.FromSeconds(25);
//     http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
//         "Bearer", builder.Configuration["SOLVETHREE_API_KEY"]
//             ?? throw new InvalidOperationException("Missing API key"));
// }).ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler {
//     AllowAutoRedirect = false
// });
// Inject CaptchaClient into your authenticated controller/service. Pass its
// cancellation token, create once, save id and poll GetAsync with a finite deadline.

등록 코드에서는 API 기본 주소, Bearer 인증, 전송 타임아웃 25초를 설정하고 자동 리디렉션을 비활성화합니다. 기본 주소 끝의 슬래시를 유지하세요. 클라이언트의 상대 경로인 tasks는 /v1/ 아래로 해석되어야 합니다.

헬퍼는 HttpClient의 JSON 확장 메서드를 사용하고 JsonObject를 반환합니다. 두 메서드 모두 역직렬화 전에 HTTP 성공 여부를 확인합니다. 인증된 컨트롤러나 서비스에 CaptchaClient를 주입하세요. 헬퍼 자체는 애플리케이션 호출자를 인증하거나 호출자의 권한을 확인하지 않습니다.

1. 1.

   사이트, 액션, 프록시 선택

   전체 URL이 아닌 대상 호스트명을 site로 전달하세요. 이 예제는 action을 login으로 고정합니다. 대상이 기대하는 액션으로 변경하세요. 프록시 하나를 전송하며 기본 enterprise-v3 reCAPTCHA 모드를 사용합니다. type 또는 url 필드를 추가하지 마세요.

2. 2.

   CreateAsync 호출 전에 requestId 저장

   ASCII 영문자, 숫자, 밑줄 또는 하이픈으로 이루어진 1–64자를 사용하세요. 응답이 유실되어도 동일한 논리적 작업을 복구할 수 있도록 정확한 작업 입력값과 함께 저장하세요.

3. 3.

   CreateAsync 호출 및 반환된 작업 ID 저장

   CreateAsync는 waitMs=0으로 POST 요청을 한 번 전송합니다. 호출자의 CancellationToken을 전달하세요. 작업 ID를 받은 뒤에는 새 작업을 생성하지 말고 GetAsync로 해당 작업을 조회하세요.

워크스페이스 크레딧을 사용할 권한은 애플리케이션의 권한 검사로 통제하세요. 이 값들이 수신 요청에서 제공된다면 요청된 사이트, 액션, 프록시가 해당 호출자에게 허용된 항목인지 검증하세요.

GetAsync는 이미 알고 있는 작업 ID를 이스케이프하고 waitMs=15000을 요청합니다. HttpClient의 25초 타임아웃은 각 HTTP 요청을 제한하며, 애플리케이션이 폴링에 사용하는 총시간을 제한하지는 않습니다. 별도의 전체 제한 시간을 설정하고 모든 호출에 취소를 전달하세요.

• pending 또는 solving: 폴링 제한 시간이 남아 있고 호출자가 취소하지 않은 경우에만 계속하세요.
• ready: 폴링을 중단하고 솔루션을 읽으세요. 사용 가능한 솔루션이 있는 유일한 상태입니다.
• failed: 폴링을 중단하고 errorCode와 error를 확인하세요.

브라우저와 통신하는 애플리케이션에서는 작업이 끝날 때까지 하나의 수신 요청 안에서 루프를 돌리지 말고, 생성과 이후 상태 확인을 각각 보호된 별도 작업으로 유지하세요. 로컬 제한 시간이 만료되어도 작업 ID를 보관하여 이후 권한이 확인된 요청에서 조회할 수 있도록 하세요.

토큰을 의도한 대상에 제출할 때는 솔루션에서 반환된 userAgent 및 secChUa 식별 정보와 풀이에 사용한 동일한 프록시를 사용하세요. 준비 완료 상태의 작업은 솔루션이 생성되었다는 뜻이지, 애플리케이션 요청이 성공했다는 뜻이 아닙니다.

ID를 받기 전에 CreateAsync가 타임아웃되거나 취소됩니다.

서버에서 이미 작업이 생성되었을 수 있습니다. 로컬 취소는 원격 작업을 취소하지 않습니다.

다음을 시도해 보세요: 저장한 requestId로 동일한 작업 입력값을 다시 제출하여 복구하세요. ID와 입력값이 같으면 기존 작업이 반환됩니다. 해당 ID를 재사용하면서 입력값을 변경하면 충돌이 발생합니다.

GetAsync가 타임아웃되거나 폴링 제한 시간이 만료됩니다.

이미 작업 ID가 있으므로 응답을 받지 못해도 대체 작업을 만들 필요는 없습니다.

다음을 시도해 보세요: ID를 보관하고 나중에 제한 시간이 있는 새 작업에서 해당 작업을 조회하세요.

HTTP 호출이 성공이 아닌 응답을 반환합니다.

EnsureSuccessStatusCode는 헬퍼가 성공 페이로드를 읽기 전에 예외를 발생시킵니다. 이는 상태가 failed인 작업을 받는 것과 다릅니다.

다음을 시도해 보세요: HTTP 오류를 별도로 처리하세요. 잘못된 입력값을 그대로 재시도하지 말고 수정하세요.

작업이 failed 상태가 됩니다.

site-unreachable과 같은 작업 실패에 대한 errorCode와 error를 읽으세요.

다음을 시도해 보세요: 해당 작업의 폴링을 중단하고 보고된 원인을 해결한 뒤 새 풀이를 시작하세요.

거부된 API 요청과 최종적인 풀이 실패를 구분해야 할 때는 API 오류 가이드를 참고하세요.