Cloudflare Workers에서 CAPTCHA API 호출하기

먼저 콘솔에서 워크스페이스의 대상 사이트 프로필을 활성화하세요. 호스트 이름과 액션을 전송하는 것만으로는 프로필이 생성되지 않습니다. 이 사전 요건을 완료하지 않았다면 사이트 프로필 설정을 참고하세요.

• SOLVETHREE_API_KEY: Worker 시크릿으로 저장하는 워크스페이스 API 키입니다.
• INTEGRATION_KEY: 애플리케이션 호출자가 x-integration-key로 전송해야 하는 별도의 시크릿입니다.
• SOLVETHREE_PROXY: 해결에 사용하는 프록시 URL입니다. 자격 증명이 포함되어 있다면 시크릿으로 저장하세요.
• CAPTCHA_SITE: 전체 URL이 아닌 대상 호스트 이름입니다.

이 예제는 액션을 login으로 고정하고 프록시 하나를 제공합니다. 배포된 입력을 통합 환경에 맞게 변경하세요. 호출자가 임의의 대상 입력을 제공하도록 허용하지 마세요. recaptchaType을 생략하면 API는 기본적으로 reCAPTCHA Enterprise v3를 사용합니다.

통합 키는 신뢰할 수 있는 애플리케이션 호출자와 Worker 사이에서 사용하고, 공개 배포되는 브라우저 코드에는 넣지 마세요. 이는 공유 자격 증명이며, 사용자별 작업 권한 부여 수단이 아닙니다.

export default {
  async fetch(request, env) {
    if (!env.INTEGRATION_KEY || request.headers.get('x-integration-key') !== env.INTEGRATION_KEY) {
      return new Response('Unauthorized', { status: 401 });
    }
    const url = new URL(request.url);
    const headers = { Authorization: `Bearer ${env.SOLVETHREE_API_KEY}`, 'Content-Type': 'application/json' };
    let response;
    if (request.method === 'POST') {
      const requestId = request.headers.get('x-request-id');
      if (!requestId || !/^[A-Za-z0-9_-]{1,64}$/.test(requestId)) return new Response('Provide X-Request-ID', { status: 400 });
      response = await fetch('https://api.solvethree.com/v1/tasks?waitMs=0', {
        method: 'POST', headers, redirect: 'error', signal: AbortSignal.timeout(20000),
        body: JSON.stringify({ site: env.CAPTCHA_SITE, action: 'login', proxy: env.SOLVETHREE_PROXY, requestId }),
      });
    } else if (request.method === 'GET') {
      const id = url.searchParams.get('id');
      if (!id || !/^[A-Za-z0-9_-]{1,128}$/.test(id)) return new Response('Provide a valid id', { status: 400 });
      response = await fetch(`https://api.solvethree.com/v1/tasks/${encodeURIComponent(id)}?waitMs=15000`, {
        headers, redirect: 'error', signal: AbortSignal.timeout(25000),
      });
    } else return new Response('Use POST or GET', { status: 405 });
    if (!response.ok) return Response.json({ error: 'Solver API request failed', status: response.status }, { status: response.status });
    return Response.json(await response.json(), { headers: { 'Cache-Control': 'no-store' } });
  },
};
// Store keys in Worker secret bindings. The task proxy field does not add a
// generic HTTP proxy option to Workers fetch; another client must submit through it.

1. 1.

   작업 생성

   x-integration-key와 x-request-id를 포함하여 Worker에 POST 요청을 보내세요. 요청 ID는 ASCII 영문자, 숫자, 밑줄 또는 하이픈으로 구성된 1–64자여야 합니다. Worker는 구성된 대상과 프록시로 작업 본문을 생성하며, 호출자가 제공한 본문은 사용하지 않습니다.

2. 2.

   작업 ID 보관

   Worker는 솔버의 JSON 응답을 반환합니다. 반환된 작업 ID를 저장하고, 생성에 사용한 요청 ID도 보관하세요.

3. 3.

   결과 조회

   id 쿼리 매개변수에 작업 ID를 넣고 동일한 통합 키 헤더를 포함하여 Worker에 GET 요청을 보내세요. 핸들러는 ID 구문을 검증하고 solvethree에서 해당 작업을 조회합니다.

두 업스트림 요청 모두 워크스페이스 키로 인증합니다. 핸들러는 성공이 아닌 HTTP 상태 코드를 일반 오류 본문과 함께 전달하고, 성공한 JSON 응답에는 Cache-Control: no-store를 설정합니다. 공유 통합 키 외에는 작업 소유권을 확인하지 않으므로, 개별 사용자에게 조회 기능을 제공하기 전에 해당 권한 검사를 추가하세요.

생성에는 waitMs=0과 20초의 fetch 시간 제한을 사용합니다. 조회에는 waitMs=15000과 25초의 fetch 시간 제한을 사용합니다. 이 제한은 개별 HTTP 호출에 적용되며, 작업의 전체 수명을 제한하지는 않습니다.

작업 ID를 받기 전에 생성 요청이 시간 초과되면 동일한 요청 ID로 동일한 작업 요청을 반복하세요. 작업이 생성되었다면 기존 작업을 복구합니다. 연결이 실패했다는 이유만으로 새 ID를 생성하지 마세요. 첫 번째 요청이 이미 solvethree에 도달했을 수 있습니다. 입력을 변경한 채 ID를 재사용하면 충돌이 발생합니다.

이 예제는 시간 초과를 포함한 fetch 예외를 처리하지 않습니다. 호출자에게 구조화된 오류 응답이 필요하다면 예외 처리를 추가하되, 복구에 사용할 수 있도록 요청 ID를 보관하세요.

• pending 또는 solving: 호출자에 설정한 전체 기한 내에서 동일한 작업을 다시 조회하세요.
• ready: 솔루션을 사용할 수 있습니다. 폴링을 중단하고 제출 클라이언트에 전달하세요.
• failed: 폴링을 중단하고 errorCode와 error를 확인하세요. 보고된 문제를 해결한 후에 다른 작업을 생성하세요.

HTTP 오류와 상태가 failed인 작업은 서로 다른 실패입니다. 핸들러는 HTTP 상태를 먼저 확인하며, 호출자는 성공 응답에서도 작업 상태를 확인해야 합니다. 진단 방법은 CAPTCHA API 오류를 참고하세요.

이 Worker 예제는 solvethree만 호출합니다. 작업의 proxy 필드는 솔버가 사용할 프록시를 지정하며, Worker의 네트워크 라우팅을 변경하지는 않습니다. Workers fetch에는 범용 프록시 URL 옵션이 없습니다.

동일한 프록시를 통해 의도한 대상에 제출할 수 있는 클라이언트로 준비된 솔루션을 보내세요. 무관한 브라우저 헤더 대신 솔루션에서 반환된 userAgent와 secChUa를 사용하세요. 작업이 준비되었다는 것은 solvethree가 솔루션을 생성했다는 뜻이며, 수락 여부는 대상에 보내는 후속 요청에 달려 있습니다.