PowerShell에서 CAPTCHA API 호출하기

1. 1.

   워크스페이스에서 사이트 사용 설정

   콘솔에서 대상 호스트 이름의 활성 프로필을 구성하세요. 호스트 이름과 액션을 전송해도 프로필이 생성되지는 않습니다. 아직 설정하지 않았다면 사이트 프로필 설정을 참고하세요.

2. 2.

   환경 변수 제공

   평소 사용하는 비밀 정보 관리 방식으로 PowerShell 프로세스의 환경에 SOLVETHREE_API_KEY와 SOLVETHREE_PROXY를 설정하세요. 실행 전에 두 변수에 모두 값이 있는지 확인하세요. API 키는 Bearer 헤더로 전달되며, 작업 JSON에 넣으면 안 됩니다.

3. 3.

   예제 호스트 이름과 액션 바꾸기

   accounts.example.com과 login을 연동에 필요한 호스트 이름과 액션으로 변경하세요. 전체 URL이 아닌 호스트 이름을 사용하세요. 요청은 기본적으로 Enterprise v3를 사용하므로 type이나 url 필드가 필요하지 않습니다.

#requires -Version 7.5
$ErrorActionPreference = 'Stop'
$apiBase = 'https://api.solvethree.com/v1'
$headers = @{ Authorization = "Bearer $env:SOLVETHREE_API_KEY"; Accept = 'application/json' }
$taskInput = @{ site = 'accounts.example.com'; action = 'login'; proxy = $env:SOLVETHREE_PROXY; requestId = [guid]::NewGuid().ToString() }
$requestClock = [Diagnostics.Stopwatch]::StartNew()
function Call-TaskApi($Method, $Path, $Payload = $null) {
    $remaining = 180 - $requestClock.Elapsed.TotalSeconds
    if ($remaining -le 0) { throw 'Local deadline reached' }
    $seconds = [int][Math]::Ceiling([Math]::Min(25, $remaining))
    $options = @{ Method = $Method; Uri = "$apiBase$Path"; Headers = $headers;
        ConnectionTimeoutSeconds = $seconds; OperationTimeoutSeconds = $seconds;
        MaximumRetryCount = 0; MaximumRedirection = 0 }
    if ($null -ne $Payload) { $options.Body = $Payload | ConvertTo-Json -Depth 6; $options.ContentType = 'application/json' }
    Invoke-RestMethod @options
}
$taskId = $null
try {
    $result = Call-TaskApi 'POST' '/tasks?waitMs=0' $taskInput
    $taskId = $result.id
    while ($result.status -in @('pending', 'solving')) {
        $escapedId = [uri]::EscapeDataString($taskId)
        $result = Call-TaskApi 'GET' "/tasks/$escapedId`?waitMs=15000"
        if ($result.status -in @('pending', 'solving')) { Start-Sleep -Seconds 1 }
    }
    if ($result.status -ne 'ready') { throw "Task failed: $($result.errorCode)" }
    Write-Host "Ready task: $taskId"
    # Submit $result.solution.token with userAgent/secChUa and the original proxy.
} catch {
    Write-Host "Recovery requestId=$($taskInput.requestId) taskId=$taskId"
    throw
}

스크립트는 /v1/tasks?waitMs=0으로 POST 요청을 한 번 보냅니다. 이후에는 반환된 ID에 대해 waitMs=15000을 사용하여 GET 요청을 보냅니다. 상태가 pending 또는 solving이면 루프를 계속 실행하고, 다른 상태이면 종료합니다.

ConvertTo-Json은 따옴표를 직접 처리한 JSON이나 셸 명령에 의존하지 않고 작업 해시 테이블을 직렬화합니다. 폴링 전에 작업 ID를 URL 이스케이프 처리합니다. 예제를 수정할 때도 이 부분은 유지하세요.

Stopwatch는 각 API 호출 전에 180초의 로컬 시간 한도를 확인합니다. 각 호출의 연결 및 작업 타임아웃은 최대 25초이며, 남은 시간이 줄어들면 함께 줄어듭니다. 폴링 결과가 종료 상태가 아니면 스크립트는 1초 동안 대기합니다. 이 시간 한도는 무한 폴링을 방지하지만, 실제 경과 시간을 기준으로 정확히 종료하는 것은 아닙니다.

MaximumRetryCount = 0은 자동 HTTP 재시도를 비활성화하고, MaximumRedirection = 0은 리디렉션을 거부합니다. 여기서 사용하는 타임아웃 매개변수는 PowerShell 7.5+가 필요하며, 모든 PowerShell 7 설치에서 지원되는 것은 아닙니다. Microsoft의 Invoke-RestMethod 참조에 이 매개변수가 설명되어 있습니다.

상태가 ready일 때 제출할 reCAPTCHA 값은 $result.solution.token입니다. $taskId는 solvethree 작업을 식별하는 용도로만 사용됩니다. 이 예제는 대상에 애플리케이션 요청을 보내기 전에 종료됩니다.

원래 프록시를 사용하여 반환된 솔루션의 userAgent 및 secChUa와 함께 토큰을 제출하세요. 관련 없는 브라우저 식별 정보로 대체하거나 다른 대상으로 보내지 마세요. ready는 solvethree가 솔루션을 생성했다는 뜻이며, 대상이 애플리케이션 요청을 수락했다는 의미는 아닙니다.

Invoke-RestMethod에서 HTTP 또는 연결 예외가 발생하는 경우

스크립트가 성공 응답을 처리하기 전에 API 요청이 실패했습니다. catch 블록은 복구용 ID를 출력하고 원래 예외를 다시 발생시킵니다.

다음을 시도해 보세요: 확인할 수 있다면 HTTP 상태와 응답 세부 정보를 살펴보세요. 잘못된 입력은 그대로 재시도하지 말고 수정하세요. 작업 생성 결과가 불확실하다면 아래 설명에 따라 복구하세요.

작업이 failed를 반환함

$result.errorCode와 $result.error를 모두 확인하세요. 스크립트의 작업 종료 예외에는 오류 코드만 포함됩니다.

다음을 시도해 보세요: 해당 작업의 폴링을 중단하고 보고된 원인을 해결하세요. 예를 들어 site-unreachable은 작업 오류이며, API 요청 자체가 실패했다는 증거가 아닙니다. CAPTCHA API 오류를 참고하세요.

타임아웃이 발생했다고 해서 생성 요청이 실패한 것은 아닙니다. catch 블록은 requestId를 출력하며, taskId를 수신했다면 함께 출력합니다. 이 값을 보관하세요.

1. 1.

   작업 ID가 있다면 해당 작업 조회

   다른 작업을 생성하지 말고 GET /v1/tasks/:id로 계속 진행하세요. 스크립트의 로컬 시간 한도에 도달했다고 해서 원격 작업이 실패한 것은 아닙니다.

2. 2.

   생성 시 작업 ID가 반환되지 않았다면 원래 요청 재사용하기

   동일한 requestId와 동일한 작업 입력으로 다시 제출하여 기존 작업을 복구하세요. 해당 ID를 재사용하면서 입력을 변경하면 충돌이 발생합니다.

3. 3.

   복구를 위해 이 스크립트를 다시 시작하지 마세요

   새로 실행하면 새 GUID가 생성되므로 논리적으로 새로운 요청이 됩니다. 무인 실행 시에는 POST 전에 원래 requestId와 작업 입력을 안전하게 저장하고, 작업 ID가 도착하면 저장하세요. 이 예제는 실패 시 복구용 ID를 출력하지만, 프로세스가 사라져도 유지되도록 저장하지는 않습니다.

프록시 URL에 자격 증명이 포함되어 있다면 저장된 입력을 일반 로그에 남기지 마세요. 복구에 필요한 것은 원래 입력이며, API 키의 추가 사본이 아닙니다.