FastAPI 백엔드에서 solvethree 호출하기

Python 3.10 이상을 사용하세요. python -m pip install "fastapi[standard]"로 FastAPI를 설치한 다음, python -m pip install https://solvethree.com/downloads/solvethree_sdk-0.1.0-py3-none-any.whl로 공식 SDK를 설치하세요.

앱을 시작하기 전에 서버 프로세스에 다음 환경 변수를 설정하세요.

• SOLVETHREE_API_KEY: 워크스페이스 API 키입니다. 서버에 보관하세요. SDK는 이 키로 solvethree에 인증합니다.
• INTEGRATION_KEY: 호출자가 FastAPI 경로에 인증하기 위해 X-Integration-Key 헤더로 보내는 별도의 비밀 값입니다.
• CAPTCHA_SITE: 전체 URL이 아닌 대상 호스트 이름입니다.
• SOLVETHREE_PROXY: 이 작업에 사용하는 HTTP 또는 HTTPS 프록시 URL로, 경로, 쿼리, 프래그먼트가 없어야 합니다.

경로를 호출하기 전에 워크스페이스에 대상의 활성 프로필을 생성하세요. 이 예제는 액션을 login으로 고정하므로 프로필과 의도한 대상 요청이 해당 용도에 맞아야 합니다. 호스트 이름을 제공해도 프로필이 생성되지는 않습니다. 사이트 프로필 설정을 참고하세요.

이 예제를 main.py로 저장하세요. 두 경로 모두 X-Integration-Key가 필요합니다. 생성 경로는 전적으로 서버 설정을 바탕으로 작업을 구성하며, 호출자는 요청 본문에 사이트, 액션 또는 프록시를 제공하지 않습니다.

# pip install "fastapi[standard]" and the official solvethree SDK wheel.
import hmac
import os
from fastapi import FastAPI, HTTPException, Request
from fastapi.concurrency import run_in_threadpool
from solvethree import Solvethree, SolvethreeError

app = FastAPI()

def authorize(request):
    if not hmac.compare_digest(request.headers.get("x-integration-key", ""), os.environ["INTEGRATION_KEY"]):
        raise HTTPException(status_code=401, detail="Unauthorized")

@app.post("/captcha/tasks")
async def create(request: Request):
    authorize(request)
    task = {"site": os.environ["CAPTCHA_SITE"], "action": "login", "proxy": os.environ["SOLVETHREE_PROXY"]}
    if request.headers.get("x-request-id"):
        task["requestId"] = request.headers["x-request-id"]
    def submit():
        return Solvethree(os.environ["SOLVETHREE_API_KEY"]).create_task(task, wait_ms=0, timeout=20)
    try:
        return await run_in_threadpool(submit)
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid task input")
    except SolvethreeError as error:
        raise HTTPException(status_code=502, detail={"requestId": error.request_id, "taskId": error.task_id})

@app.get("/captcha/tasks/{task_id}")
async def retrieve(task_id: str, request: Request):
    authorize(request)
    def fetch():
        return Solvethree(os.environ["SOLVETHREE_API_KEY"]).get_task(task_id, wait_ms=15000, timeout=25)
    try:
        return await run_in_threadpool(fetch)
    except ValueError:
        raise HTTPException(status_code=400, detail="Invalid task ID")
    except SolvethreeError as error:
        raise HTTPException(status_code=502, detail={"requestId": error.request_id, "taskId": error.task_id})

작업은 기본적으로 reCAPTCHA Enterprise v3를 사용합니다. type이나 url 필드 없이 site, action, 하나의 proxy를 전송합니다.

Python SDK는 동기식입니다. async def 안에서 직접 호출하면 이벤트 루프가 차단되므로 두 핸들러 모두 run_in_threadpool을 사용합니다. 생성은 wait_ms=0과 20초 SDK 요청 타임아웃을 사용하고, 조회는 최대 15초 대기와 25초 SDK 요청 타임아웃을 사용합니다. 어느 핸들러도 client.solve로 전체 솔루션 생성이 끝날 때까지 기다리지 않습니다.

로컬 개발 시 파일이 있는 디렉터리에서 fastapi dev main.py를 실행하세요. 경로는 POST http://127.0.0.1:8000/captcha/tasks와 GET http://127.0.0.1:8000/captcha/tasks/{task_id}입니다. FastAPI가 app 객체를 자동으로 찾으므로 별도의 URLconf를 등록할 필요가 없습니다.

1. 1.

   고정된 요청 ID로 한 번만 생성하세요

   X-Integration-Key와 이 논리적 작업에 대해 계속 유지할 X-Request-ID를 포함해 POST /captcha/tasks를 전송하세요. 요청 ID는 ASCII 영문자, 숫자, 밑줄 또는 하이픈 1–64자로 구성되어야 합니다. 경로는 이를 requestId로 solvethree에 전달합니다. 반환된 작업 id를 저장하세요.

2. 2.

   작업 상태를 읽기 전에 HTTP 상태를 확인하세요

   래퍼는 인증 실패 시 401, ValueError 입력 오류 시 400, 포착한 SolvethreeError 예외에 대해 502를 반환합니다. 502 응답의 detail에는 SDK 오류의 requestId와 taskId가 포함됩니다. 응답을 작업으로 취급하기 전에 해당 HTTP 오류를 처리하세요.

3. 3.

   기존 작업 조회

   X-Integration-Key를 포함해 GET /captcha/tasks/{task_id}를 호출하세요. HTTP 응답이 성공할 때마다 status를 확인하세요. 조회 대기가 끝나도 작업이 최종 상태가 아닐 수 있습니다. 새 작업을 생성하지 말고 같은 작업을 다시 조회하세요.

4. 4.

   생성 여부가 불확실한 요청 복구

   생성 요청이 타임아웃되었고 작업 ID가 있다면 해당 작업을 조회하세요. 그렇지 않으면 원래 X-Request-ID와 변경하지 않은 서버 측 작업 입력값으로 POST를 반복하세요. 동일한 작업에 같은 ID를 재사용하면 기존 작업이 반환되고, 입력값을 변경하면 충돌이 발생합니다. 원래 ID를 오류 응답의 requestId로 대체하지 말고 별도로 보관하세요.

이 경로들은 작업 데이터를 반환하며, 대상 웹사이트에 아무것도 제출하지 않습니다. status가 ready가 되면 대상 요청을 보내는 구성 요소는 작업 ID가 아닌 solution.token을 사용해야 합니다.

반환된 solution.userAgent와 solution.secChUa 브라우저 식별 정보를 사용해 해당 작업을 생성할 때 사용한 것과 동일한 프록시로 제출하세요. 현재 환경에 여전히 같은 프록시가 있다고 가정하지 말고 원래 작업 설정을 보관하세요. SDK의 successful_proxy(original_task, ready_result) 헬퍼는 해당 원래 작업에서 프록시를 선택합니다.

제출이 의도한 대상 및 액션과 연결되도록 유지하세요. ready 작업은 solvethree가 솔루션을 생성했다는 뜻입니다. 애플리케이션 요청이 수락되었는지는 대상의 응답으로만 알 수 있습니다.