在 AWS Lambda 中使用 Node.js SDK
使用 Node.js 22 或更高版本,并将官方 SDK 与处理程序一同打包。将 SDK 截止时间设在 Lambda 剩余执行时间结束之前,确保函数有时间返回任务 ID 和错误 ID。
本页内容
打包 SDK 并配置目标
- 1.
安装依赖项
在干净的构建目录中初始化 npm 包。使用 npm 安装位于
https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz的官方 tarball。它提供@solvethree/sdk导入;不要假定 npm 注册表中已有发布版本。 - 2.
配置工作区和目标
设置名为
SOLVETHREE_API_KEY、CAPTCHA_SITE和SOLVETHREE_PROXY的私有 Lambda 环境变量。分别使用工作区 API 密钥、目标主机名而非完整 URL,以及此任务的代理。工作区必须已具备该站点的有效配置;请参阅站点配置设置。 - 3.
保存并打包处理程序
将下方示例保存为
index.mjs。创建 ZIP,将index.mjs、包元数据和已安装的node_modules目录放在压缩包根目录,而非外层项目目录中。不要将凭据放入 ZIP。 - 4.
通过现有 Lambda 流程部署
使用 Node.js 22 运行时,并将处理程序设为
index.handler。通过已获授权的后端或 IAM 流程调用,为逻辑作业提供稳定的requestId。不要公开返回的解题结果数据。
此示例使用操作 login;部署前,请将其改为目标预期的操作。它发送一个 proxy,并使用默认请求类型 enterprise-v3。不要添加 reCAPTCHA type 或 url 字段。
根据调用时间预算限制 SDK 等待
import { Solvethree, SolvethreeError, TaskFailedError, ApiError } from '@solvethree/sdk';
const client = new Solvethree({ apiKey: process.env.SOLVETHREE_API_KEY });
export const handler = async (event, context) => {
const timeoutMs = Math.min(180000, context.getRemainingTimeInMillis() - 1500);
if (timeoutMs < 1000) throw new Error('Not enough execution time to start a task');
// The caller supplies one stable ID for this logical job; Lambda retries must
// reuse it. awsRequestId changes with invocations and is not that logical ID.
if (!event.requestId) throw new Error('Provide a stable requestId');
try {
return await client.solve({
site: process.env.CAPTCHA_SITE, action: 'login', proxy: process.env.SOLVETHREE_PROXY,
requestId: event.requestId,
}, { timeoutMs, signal: AbortSignal.timeout(timeoutMs) });
} catch (error) {
if (error instanceof TaskFailedError) return { status: 'failed', id: error.taskId, errorCode: error.errorCode };
if (error instanceof ApiError) return { apiError: error.status, requestId: error.requestId };
if (error instanceof SolvethreeError) return { interrupted: true, requestId: error.requestId, taskId: error.taskId };
throw error;
}
};
// Invoke through your authorized backend/IAM flow. The return value is private
// solution data; do not attach this handler to an unauthenticated public URL.处理程序读取 Lambda 的剩余执行时间,预留 1,500 毫秒,并将 SDK 等待时间上限设为 180,000 毫秒。该上限仅适用于此示例,并非通用的 Lambda 执行限制。扣除预留时间后,若剩余时间不足一秒,处理程序会拒绝启动。
SDK 超时和中止信号都使用计算出的截止时间。solve 只创建一次任务,并持续轮询,直到任务就绪或发生错误。预留时间让错误处理有机会返回恢复信息,但 Lambda 被强制终止时,仍可能无法返回任何响应。
调用方必须在调用重试之间保留 event.requestId。使用 1–64 个 ASCII 字母、数字、下划线或连字符。不要使用 awsRequestId:它标识的是一次调用,而非逻辑解题请求。
处理失败,避免盲目开始另一次解题
| 结果 | 处理方法 |
|---|---|
状态为 ready 的任务 | 使用其解题结果。仅创建任务或收到成功的 HTTP 响应还不够。 |
status: failed | 记录 id 和 errorCode。如果需要错误消息,可以获取该任务,但应停止轮询这个失败的任务。 |
apiError | 记录 HTTP 状态和返回的请求 ID。这是 API 请求错误,而非任务终态失败;使用未修改的输入重试前,应先检查原因。 |
interrupted: true | 保留返回的所有 taskId 和 requestId,以及调用方原始的逻辑请求 ID,以便恢复。 |
验证错误和意外错误会被重新抛出。处理程序不会将所有异常都转换为中断响应。
- 1.
有任务 ID 时按任务 ID 恢复
使用
getTask获取现有任务。pending和solving表示任务仍在运行;只有ready包含可用的解题结果。任何后续等待都应限制在新一次调用的剩余时间预算内。 - 2.
否则按逻辑请求 ID 恢复
使用调用方原始的
requestId重试同一任务请求。输入相同会返回现有任务;输入不同则会发生冲突。恢复期间请保持站点、操作和代理不变,即使配置发生变化也应如此。
连接超时并不意味着任务创建失败。在分配新的逻辑请求 ID 之前,请先恢复现有任务。有关底层约定,请参阅任务轮询和 API 错误处理。
使用相同的代理和返回的浏览器身份提交
SDK 返回解决方案数据,但不会将其应用到目标。应用提交这些数据时,请使用配置的代理以及返回的 userAgent 和 secChUa。不要替换为无关的浏览器身份或目标 URL。任务就绪表示已生成解决方案,并不表示目标已接受后续请求。
来源与 API 参考
运行您的第一个任务。
使用 $5 工作区额度开始体验。