Django 뷰에서 solvethree 사용하기

1. 1.

   Django 환경에 설치

   공식 SDK에는 Python 3.10+가 필요합니다. Django를 실행하는 환경에서 python -m pip install https://solvethree.com/downloads/solvethree_sdk-0.1.0-py3-none-any.whl을 사용하세요.

2. 2.

   서버 환경 변수 설정

   SOLVETHREE_API_KEY에는 워크스페이스 API 키를, CAPTCHA_SITE에는 전체 URL이 아닌 대상 호스트 이름을, SOLVETHREE_PROXY에는 해결 및 이후 대상 제출에 사용할 프록시를 설정하세요. API 키와 프록시 인증 정보는 서버에 보관하세요.

3. 3.

   사이트 프로필 활성화

   콘솔에서 해당 호스트 이름에 대해 워크스페이스에서 사용할 수 있는 활성 프로필을 설정하세요. 호스트 이름과 액션을 전송해도 프로필이 생성되지는 않습니다. 사이트 프로필 설정을 참조하세요.

예제는 액션을 login으로 고정하며 호출자로부터 대상 설정을 받지 않습니다. 설정한 대상에 다른 액션이 필요하면 변경하세요. 요청은 기본 enterprise-v3 모드를 사용하며, type이나 url이 아니라 site, action, 그리고 proxy 또는 proxyCandidates 중 정확히 하나가 필요합니다.

# views.py in an existing Django project with authentication/CSRF configured.
import os
from django.contrib.auth.decorators import login_required
from django.http import JsonResponse
from django.views.decorators.http import require_GET, require_POST
from solvethree import Solvethree, SolvethreeError

def client():
    return Solvethree(os.environ["SOLVETHREE_API_KEY"])

@login_required
@require_POST
def create_captcha(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"]
    try:
        return JsonResponse(client().create_task(task, wait_ms=0, timeout=20))
    except ValueError:
        return JsonResponse({"error": "Invalid task input"}, status=400)
    except SolvethreeError as error:
        return JsonResponse({"requestId": error.request_id, "taskId": error.task_id}, status=502)

@login_required
@require_GET
def get_captcha(request, task_id):
    try:
        return JsonResponse(client().get_task(task_id, wait_ms=15000, timeout=25))
    except ValueError:
        return JsonResponse({"error": "Invalid task ID"}, status=400)
    except SolvethreeError as error:
        return JsonResponse({"requestId": error.request_id, "taskId": error.task_id}, status=502)

# urls.py: import these views and add to urlpatterns:
# path("captcha/tasks", create_captcha),
# path("captcha/tasks/<str:task_id>", get_captcha),

create_task는 wait_ms=0을 사용하므로 전체 해결 과정이 끝날 때까지 기다리지 않고 작업을 반환합니다. HTTP 호출의 제한 시간은 20초입니다. 조회 뷰는 작업 업데이트를 최대 15초 동안 기다릴 수 있으며, HTTP 제한 시간은 25초입니다. 이 SDK 호출은 동기식이므로 조회 요청은 대기하는 동안에도 Django 워커를 점유합니다.

login_required는 로그인한 사용자로 접근을 제한하고, 메서드 데코레이터는 생성에 POST, 조회에 GET을 허용합니다. Django의 일반 CSRF 보호를 유지하고 POST 요청 시 CSRF 토큰을 포함하세요. csrf_exempt를 추가하지 마세요.

1. 1.

   기존 URLconf 업데이트

   django.urls에서 path를 가져오고 앱의 뷰 모듈에서 create_captcha와 get_captcha를 가져오세요. 예제 하단에 표시된 두 라우트 항목을 기존 urlpatterns에 추가하세요. 앱 URLconf를 사용한다면 프로젝트 URLconf에 포함되어 있는지 확인하세요.

2. 2.

   개발 서버 시작

   프로세스에서 환경 변수를 사용할 수 있는 상태에서, manage.py가 있는 디렉터리에서 python manage.py runserver를 실행하세요. 엔드포인트를 호출하기 전에 프로젝트의 기존 로그인 절차를 따르세요.

3. 3.

   등록된 경로 사용

   상위 URL 접두사가 없다면 생성은 POST /captcha/tasks, 조회는 GET /captcha/tasks/<task_id>입니다. 제공된 라우트에는 끝 슬래시가 없습니다. 프로젝트 URLconf에서 추가한 접두사가 있다면 포함하세요.

1. 1.

   POST를 보내기 전에 ID 저장

   논리적 작업마다 새 X-Request-ID를 선택하고 생성 결과가 확정될 때까지 보관하세요. ASCII 영문자, 숫자, 밑줄 또는 하이픈으로 구성된 1–64자를 사용하세요. 뷰는 이 헤더를 작업의 requestId로 전달합니다.

2. 2.

   작업 상태보다 HTTP 성공 여부를 먼저 확인

   예제는 입력 검증 오류를 포착하면 HTTP 400, SDK 오류를 포착하면 502를 반환합니다. 성공 응답에는 작업 페이로드가 포함됩니다. 그 안의 id와 status를 확인하세요. HTTP 성공은 요청이 성공했다는 뜻이지, 토큰이 준비되었다는 뜻은 아닙니다.

3. 3.

   작업이 끝날 때까지 조회

   반환된 작업 ID로 GET 엔드포인트를 호출하세요. pending 또는 solving이면 계속 조회하세요. ready이면 솔루션을 사용하세요. failed이면 폴링을 중단하고 errorCode와 error를 확인하세요. 해결에 실패하면 환불됩니다. 잘못된 입력값을 그대로 재시도하지 말고 수정하세요.

4. 4.

   생성 여부가 불확실한 작업 복구

   POST 시간이 초과되거나 SDK 오류가 반환되면 새 ID로 즉시 다른 작업을 생성하지 마세요. 기존 작업의 ID를 알고 있다면 조회하세요. 모른다면 원래 X-Request-ID와 변경하지 않은 작업 입력값으로 POST를 다시 보내 복구하세요. 설정된 호스트 이름, 액션 또는 프록시 변경을 포함해 다른 입력값으로 같은 ID를 재사용하면 충돌이 발생합니다.

SDK 오류 응답에는 진단을 위해 예외의 requestId와 taskId가 포함됩니다. 해당 응답 수신 여부에 의존하지 않고 복구할 수 있도록 호출자의 원래 X-Request-ID를 별도로 보관하세요. 실패 처리 방법은 CAPTCHA API 오류를 참조하세요.

ready 작업에만 사용 가능한 솔루션이 포함됩니다. 의도한 대상에 보낼 값은 작업 ID가 아니라 solution.token입니다. 반환된 solution.userAgent와 solution.secChUa 브라우저 식별 정보를 SOLVETHREE_PROXY에 설정된 원래 프록시와 함께 사용하세요.

이 뷰는 대상에 아무것도 제출하지 않습니다. 제출 코드에서 해당 프록시를 유지하고 반환된 식별 정보를 적용해야 합니다. 관련 없는 브라우저 세션에 토큰을 반환한다고 해서 이 과정이 자동으로 수행되지는 않습니다. 프록시 인증 정보는 서버에 보관하고, 솔루션을 다른 대상 URL이나 브라우저 식별 정보와 혼용하지 마세요.