Skip to content

远程调用示例

Jump to bottom
Naibo Wang edited this page Jul 14, 2025 · 1 revision

后端接口的所有逻辑都位于此文件中：

https://github.com/NaiboWang/EasySpider/blob/master/ElectronJS/server.js

接口通用格式

在没有修改过 config.json 配置的情况下，所有接口的端口号都是 8074，即地址为 http://localhost:8074

接口请求失败的返回值是通用的，响应状态码可能不同。失败的请求格式如下：

{
    "error": "错误描述文本",
    "status": false
}

虽然 status 属性可以用于确认任务是否成功，但出于兼容性考虑，部分旧接口请求成功时的返回值不包含 status 属性。因此，推荐通过响应的状态码判断请求是否成功完成。

成功响应码：200

失败响应码：

  • 400：表示输入参数存在问题，比如缺少必需的输入参数。
  • 404：表示无法通过输入参数找到所需内容，比如无法通过输入的任务 id 查找到任务
  • 500：服务器在处理请求时出现内部错误。

GET 请求的所有参数都作为 url 的一部分传递。

POST 请求都需要采用 x-www-form-urlencoded 方式作为请求体，将参数以键值对的形式放入表单中传递。文档的最后有通过 Postman 或 Node.js 进行 POST 请求的示例。

调试模式

如果您通过 npm run start_direct 在本地通过源代码运行此程序，那么程序会自动进入调试模式。在接口请求出现 500 内部错误时，返回值中会包含错误的具体堆栈信息。运行打包的程序时，返回值不会包含堆栈信息。

调试模式实际通过 NODE_ENV 环境变量控制，如果 NODE_ENV 环境变量的值等于 development，程序会进入调试模式。因此，在运行打包的程序时，通过在终端设置环境变量，也可以进入调试模式。

非调试模式下，出现服务器内部错误时，会返回一条响应码为 500，类型为 text/plain，内容为 Internal Server Error 的响应。

调试模式下，出现服务器内部错误时，会返回一条响应码为 500，类型为 text/plain，内容为 Internal Server Error 开头，第二行及以后为内部错误的具体堆栈信息。

1. 任务管理接口

1.1 查询所有任务

  • 作用: 获取保存在 tasks 目录下的所有任务列表，按修改时间降序排列。

  • 请求方法: GET

  • 地址: /queryTasks

  • 参数: 无

  • 成功返回值:

    • 内容: 一个包含任务对象的数组。
    • 示例: 
      [
    {
        "id": 1,
        "name": "示例任务-采集网站标题",
        "url": "http://example.com",
        "mtime": "2025-07-10T10:00:00.000Z",
        "links": "http://example.com\nhttp://example.org",
        "desc": "这是一个采集网站标题的示例任务"
    }
]

1.2 查询单个任务

  • 作用: 根据任务 ID 获取单个任务的详细配置。
  • 请求方法: GET
  • 地址: /queryTask
  • 参数:
    • id (Query Param, number, 必需): 任务的唯一标识符。
  • 成功返回值:
    • 格式: application/json
    • 内容: 完整的任务文件内容，即 tasks/${id}.json 中的内容。
    • 示例: 
      // 返回 tasks/1.json 的完整内容
// 不同版本的 EasySpider 采用的任务格式可能不同，具体请查看您自己的任务文件
{
    "id": 1,
    "name": "示例任务-采集网站标题",
    "links": "http://example.com\nhttp://example.org",
    "desc": "这是一个采集网站标题的示例任务",
    "graph": [...],
    "outputParameters": [...]
}
  • 失败返回值:
    • 状态码: 404
    • 内容: {"error": "Cannot find task based on specified task ID.", "status": false}

1.3 创建/更新任务

  • 作用: 创建一个新任务或更新一个已有任务的配置。

  • 请求方法: POST

  • 地址: /manageTask

  • 参数:

    • params（必需）: 需要添加/修改的任务的全部内容作为 JSON 字符串。如果 JSON 中的 id 为 -1，则为创建新任务；否则为更新指定 ID 的任务。

    • 通过将 id 属性设置为一个尚不存在的任务 id，可以创建指定 id 的任务。

    • 示例：

      {
    "id": 10, // 这就是上方提到的 id 属性
    "name": "地震台网",
    "url": "http://www.ceic.ac.cn/history",
    "links": "http://www.ceic.ac.cn/history\r\nhttp://www.ceic.ac.cn/history2",
    "create_time": "7/7/2023, 2:15:59 AM",
    "version": "0.3.5",
    "saveThreshold": 10,
    "quitWaitTime": 10,
    "cloudflare": 0,
    "environment": 0,
    "maxViewLength": 15,
    "outputFormat": "xlsx",
    "saveName": "地震信息",
    "containJudge": false,
    "desc": "http://www.ceic.ac.cn/history",
    "inputParameters": [
        ...省略
    ],
    "outputParameters": [
        {
            "id": 0,
            "name": "参数1_文本",
            "desc": "",
            "type": "string",
            "exampleValue": "3.12023-05-09 14:12:2241.0778.8410新疆阿克苏地区乌什县"
        }
    ],
    "graph": [
        ...省略
    ]
}

  • 成功返回值:

    • 格式: text/plain
    • 内容: 创建或更新的任务的 ID。
    • 示例: 1

此接口比较旧，为了兼容性起见，没有添加 status: true 属性到返回值中来说明请求已经成功。

1.4 删除任务

  • 作用: 根据任务 ID 逻辑删除一个任务（将其 id 属性设置为 -2）。
  • 请求方法: GET
  • 地址: /deleteTask
  • 参数:
    • id (Query Param, number, 必需): 要删除的任务的 ID。
  • 成功返回值:
    • 格式: application/json
    • 内容: {"success": "Task has been deleted successfully.", "status": true}
  • 失败返回值:
    • 状态码: 404
    • 内容: {"error": "Cannot find task based on specified task ID.", "status": false}

多次删除一个任务时，每次请求都会成功。

2. 任务执行与控制

2.1 生成任务

  • 作用：实例化一个任务，可以（可选的）修改任务的输入参数。

  • 请求方法：POST

  • 地址：/invokeTask

  • 参数:

    • id(Form Data, number, 必需): 需要实例化的任务的 id，与“任务管理接口”中涉及的 id 一致。

    • params（Form Data, json，可选）：需要修改的此任务中的参数。任务的参数可以在查看/管理/执行任务->任务信息中查看。

      此参数需要传入一个字典（包含两侧的大括号），比如：

      {
    "urlList_0": "https://www.baidu.com"
}

      传入字典中的参数值会覆盖原先任务文件中定义的参数值。如果不传入某个参数，它将会保持原先任务文件中定义的参数值。

  • 成功返回值：

    • 类型：text/plain
    • 返回单个数字，表示实例化后的任务的 id。这个 id 只能用于下方的执行任务、停止任务接口，无法用于上方提到的任务管理系列接口。

  • 失败返回值：

    • 状态码：400
    • 内容示例：{"error": "Fail to parse parameters from json string.","status": false}

2.1 执行任务

  • 作用: 启动一个执行进程，来执行指定的任务。

  • 请求方法: POST

  • 地址: /executeTask

  • 参数:

    • id (Form Data, number 或 Array<number>, 必需): 要执行的任务 ID。可以是单个数字或者一个数组。输入数组时，形式例如 [10,11]，需要包含中括号。

      此处的任务 id 为 execution_instance 的 id，而不是 task 的 id。如果你的任务已经通过 manageTask 接口上传到了任务文件夹，需要先使用 invokeTask 生成任务接口生成一个执行任务，再通过这个接口返回的 id 调用本接口实现启动。

    • use_user_data (Form Data, boolean, 可选): 是否使用带用户信息模式。1：使用；0：不使用。

    • timeout（Form Data，number，可选）：等待进程启动的时间，默认为 10 秒。

    此接口在执行进程启动完成，准备开始执行任务时才会返回，因此请求耗时较长，一般需要 5-10 秒完成请求。根据服务器所运行的机器性能不同，启动执行进程的时间可能有差异。如果频繁出现超时未启动错误，可以尝试增加超时时间。

    设置超时时间后，如果执行进程超过规定时间仍然没有启动完成，将会杀掉执行进程，启动失败，返回失败返回值。

  • 成功返回值:

    • 格式: application/json

    • 示例:

      {
    "success": "Task execution started successfully for ID(s): 1",
    "status": true
}

  • 失败返回值:

    • 状态码: 500
    • 内容: {"error": "Failed to start the child process and get its PID.", "status": false}

2.2 停止任务

  • 作用: 停止一个正在运行的任务进程。
  • 请求方法: POST
  • 地址: /stopTask
  • 参数:
    • id (Form Data, number, 必需): 正在执行的任务的 ID。
  • 成功返回值:
    • 格式: application/json
    • 内容: {"success": "Shutdown command sent successfully to task ID 1.", "status": true}
  • 失败返回值:
    • 状态码: 404 (任务未运行) 或 500 (发送命令失败)。
    • 内容: {"error": "No running process found for execution instance ID: 1...", "status": false}

2.3 查询任务日志

  • 作用: 获取指定任务在执行过程中的实时日志。
  • 请求方法: GET
  • 地址: /getTaskLog
  • 参数:
    • id (Query Param, number, 必需): 正在执行的任务的 ID。
  • 成功返回值:
    • 格式: application/json
    • 内容: 日志字符串。
    • 示例: 
      {
    "logs": "任务ID 1 的保存文件名为: output_2025_07_10...\n正在打开网页:http://example.com...\n",
    "status": "true"
}

3. 系统与配置接口

3.1 查询操作系统信息

  • 作用: 获取服务器所在的操作系统平台和架构。
  • 请求方法: GET
  • 地址: /queryOSVersion
  • 参数: 无
  • 成功返回值:
    • 格式: application/json
    • 示例: {"version": "win32", "bit": "x64"}

3.2 获取配置

  • 作用: 获取 config.json 文件的内容。
  • 请求方法: GET
  • 地址: /getConfig
  • 参数: 无
  • 成功返回值:
    • 格式: application/json
    • 内容: config.json 的完整内容。

3.3 设置用户数据目录

  • 作用: 更新 config.json 文件中的 absolute_user_data_folder 字段。在执行任务接口中，如果 use_user_data 设置为真，那么就会采用 config.json 中指定的用户数据目录，这个目录可以通过此接口修改。
  • 请求方法: POST
  • 地址: /setUserDataFolder
  • 参数:
    • path (Form Data, string, 必需): 用户数据目录的绝对路径。
  • 成功返回值:
    • 格式: application/json
    • 内容: {"success": "User data folder has been set successfully.", "status": true}

接口调用示例

下面介绍如何通过 POSTMAN 或 Node.js 语言调用后端接口。

POSTMAN示例

假设有3个输入参数可以被修改，其调用名称分别为：urlList_0，loopTimes_循环_1，inputText_2，分别表示打开网页操作的网址列表，循环点击下一页操作的点击次数以及输入文字操作的输入值，我们分别要输入示例值如下：

则在POSTMAN中，可以设置以下配置来获得新的任务ID：

  • 调用方法：POST
  • 调用地址：http://localhost:8074/invokeTask
  • Body字段类型：x-www-form-urlencoded
  • 键值对：

    • id: 任务的id号，在API调用网址后面写了id=ID: image

    • EID：已存在的任务执行ID，如果传递了此值，则为覆盖模式，新的配置将会覆盖原执行ID对应的配置文件（0.6.0以上支持）。

    • params: 一个键值对对象，包含了所有输入参数的键:值形式(0.5.0及之前版本请使用paras)，如：

      {"urlList_0":"https://www.baidu.com/s?wd=1\r\nhttps://www.baidu.com/s?wd=1\r\nhttps://www.baidu.com/s?wd=3","loopTimes_循环_1":"15","inputText_2":"TEST"}

示例截图如下：

image

全部配置完成后点击发送请求按钮，如果成功，会得到一个任务ID号：

image

即可通过此ID，配合命令行执行的命令来执行任务，如执行任务ID号为37的命令为：

cd 你的EasySpider文件夹，如cd D:\Document\Projects\EasySpider
./EasySpider/resources/app/chrome_win64/easyspider_executestage.exe --ids [37] --user_data 0 --server_address http://localhost:8074 --config_folder "D:/Document/Projects/EasySpider/ElectronJS/" --headless 0 --read_type remote --config_file_name config.json --saved_file_name

JavaScript代码示例

如果想要通过API调用的方式获得任务执行ID，可以参考以下文件：

https://github.com/NaiboWang/EasySpider/blob/v0.3.1/ElectronJS/src/taskGrid/invokeTask.html

参考此文件的第237行开始的localExecuteInstant方法的POST调用案例：

let param = {};
let t = $('#form').serializeArray();
t.forEach(function (item, index) {
    param[item.name] = item.value;
});
let message = {
       id: TASKID, //这里写任务ID号，如1
       EID: "1", //已存在的任务执行ID，可不设置表示新增一个配置，如果设置则表示覆盖此EID对应的配置
       params: JSON.stringify(param)
}
//这里本质上就是在生成一个对象，示例的message内容为：
//{
//  "id": 157,
//  "EID": 1,
//  "params": '{"urlList_0":"https://www.jd.com","loopTimes_循环_1":"0","inputText_2":""}'
//}
$.post("http://localhost:8074/invokeTask", message, function (EID) {
   console.log("任务ID为：", EID);
});

以上POST请求将返回任务执行IDexecution_ID，接下来使用命令行传入此ID即可执行任务。

后台处理逻辑

后台处理逻辑在以下文件的第223行：

https://github.com/NaiboWang/EasySpider/blob/v0.3.1/ElectronJS/server.js

后台处理参数的本质就是将tasks文件夹内的任务的.json文件中的默认的参数替换为给定的输入参数值，其余内容保持不变并在execution_instances文件夹内生成新的任务.json文件，然后供程序调用。

Click Pages above to see more pages

Getting Started

EXEC/EVAL

Introduction

Quick Start

Video Tutorials

Other Platforms

System Architecture

High Level Design

Operation Guide

Open Page

Element Selection

Collect Data

Click Element

Input Text

If Condition

Clone this wiki locally