在 AWS Lambda 中使用 Node.js SDK

作者:solvethree阅读需 1 分钟

使用 Node.js 22 或更高版本,并将官方 SDK 与处理程序一同打包。将 SDK 截止时间设在 Lambda 剩余执行时间结束之前,确保函数有时间返回任务 ID 和错误 ID。

本页内容

打包 SDK 并配置目标

  1. 1.

    安装依赖项

    在干净的构建目录中初始化 npm 包。使用 npm 安装位于 https://solvethree.com/downloads/solvethree-sdk-0.1.0.tgz 的官方 tarball。它提供 @solvethree/sdk 导入;不要假定 npm 注册表中已有发布版本。

  2. 2.

    配置工作区和目标

    设置名为 SOLVETHREE_API_KEY、CAPTCHA_SITE 和 SOLVETHREE_PROXY 的私有 Lambda 环境变量。分别使用工作区 API 密钥、目标主机名而非完整 URL,以及此任务的代理。工作区必须已具备该站点的有效配置;请参阅站点配置设置。

  3. 3.

    保存并打包处理程序

    将下方示例保存为 index.mjs。创建 ZIP,将 index.mjs、包元数据和已安装的 node_modules 目录放在压缩包根目录,而非外层项目目录中。不要将凭据放入 ZIP。

  4. 4.

    通过现有 Lambda 流程部署

    使用 Node.js 22 运行时,并将处理程序设为 index.handler。通过已获授权的后端或 IAM 流程调用,为逻辑作业提供稳定的 requestId。不要公开返回的解题结果数据。

此示例使用操作 login;部署前,请将其改为目标预期的操作。它发送一个 proxy,并使用默认请求类型 enterprise-v3。不要添加 reCAPTCHA type 或 url 字段。

根据调用时间预算限制 SDK 等待

Lambda index.mjs · 根据调用时间预算限制 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. 1.

    有任务 ID 时按任务 ID 恢复

    使用 getTask 获取现有任务。pending 和 solving 表示任务仍在运行;只有 ready 包含可用的解题结果。任何后续等待都应限制在新一次调用的剩余时间预算内。

  2. 2.

    否则按逻辑请求 ID 恢复

    使用调用方原始的 requestId 重试同一任务请求。输入相同会返回现有任务;输入不同则会发生冲突。恢复期间请保持站点、操作和代理不变,即使配置发生变化也应如此。

连接超时并不意味着任务创建失败。在分配新的逻辑请求 ID 之前,请先恢复现有任务。有关底层约定,请参阅任务轮询和 API 错误处理。

使用相同的代理和返回的浏览器身份提交

SDK 返回解决方案数据,但不会将其应用到目标。应用提交这些数据时,请使用配置的代理以及返回的 userAgent 和 secChUa。不要替换为无关的浏览器身份或目标 URL。任务就绪表示已生成解决方案,并不表示目标已接受后续请求。

运行您的第一个任务。

使用 $5 工作区额度开始体验。

创建工作区
在 AWS Lambda 中使用 Node.js SDK · solvethree