on_page/resources：获取页面资源列表

POST /v3/on_page/resources

POST /v3/on_page/resources 用于获取网站爬取页面中的资源列表图片、脚本、样式表及失效资源，并返回每个资源的详细信息。如需查询指定资源的页面，请使用 Pages By Resource 接口。

请求信息

请求方法：POST
请求路径：/v3/on_page/resources
请求地址：https://api.seermartech.cn/v3/on_page/resources
请求格式：application/json
字符编码：UTF-8
请求体：JSON 数组，格式为 [{ ... }]

计费说明

本接口不收取费用，任务结果可在提交后的 30 天获取。

参考价约 ¥0.0000 / 次
实扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

请求体中的每个数组代表一个任务。

参数	类型	填	说明
`id`	string	是	任务 ID。通过 `/v3/on_page/task_post` 提交任务后，可从响应中获取。示例：`07131248-1535-0216-1000-17384017ad04`
`url`	string	否	指定页面 URL获取该页面中的资源。若要获取某个 URL 下资源的 `meta` 信息，在此字段中传该 URL。未指定时，响应中的 `meta` 基于爬虫首次发现该资源的页面数据。
`limit`	integer	否	返回资源的最大数量。默认值：`100`；最大值：`1000`。
`offset`	integer	否	结果偏移量。默认值：`0`；最大值：`2000000`。例如设置为 `10`，将跳过前 10 条结果。
`filters`	array	否	资源筛选条件，最多同时设置 8 个过滤条件。
`relevant_pages_filters`	array	否	根据页面属性筛选资源。支持与页面接口相同的过滤条件，最多同时设置 8 个过滤条件。
`order_by`	array	否	结果排序规则。最多设置 3 条排序规则。
`search_after_token`	string	否	获取后续结果的令牌。当单次请求需要获取 `20,000` 条结果时，可使用该参数时。该值由上一次响应返回。使用时，请求参数与上一次请求保持一致。
`tag`	string	否	自定义任务标识，最长 255 个字符。该值会原样出现在响应的 `data` 对象中，便于匹任务与结果。

`filters` 与 `relevant_pages_filters`

支持以下逻辑运算符：

regex
not_regex
<
<=
>
>=
=
<>
in
not_in
like
not_like

多个条件之间使用逻辑运算符 and 或 or。在 like 和 not_like 中可以使用 % 匹零个或多个字符。

示例：

json

[
  ["resource_type", "=", "image"],
  "and",
  ["size", ">", 100000]
]

`order_by`

排序格式为：

json

["size,desc"]

：

asc：升序
desc：降序

多条排序规则示例：

json

["resource_type,asc", "size,desc"]

请求示例

cURL

bash

curl --location --request POST \
  "https://api.seermartech.cn/v3/on_page/resources" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "filters": [
        ["resource_type", "=", "image"],
        "and",
        ["size", ">", 100000]
      ],
      "order_by": ["size,desc"],
      "limit": 10
    }
  ]'

Python

python

import requests

url = "https://api.seermartech.cn/v3/on_page/resources"

headers = {
    "Authorization": "Bearer smt_live_YOUR_KEY",
    "Content-Type": "application/json",
}

post_data = [
    {
        "id": "07281559-0695-0216-0000-c269be8b7592",
        "filters": [
            ["resource_type", "=", "image"],
            "and",
            ["size", ">", 100000],
        ],
        "order_by": ["size,desc"],
        "limit": 10,
    }
]

response = requests.post(url, headers=headers, json=post_data)
result = response.json()

if result.get("status_code") == 20000:
    print(result)
else:
    print(
        "错误。代码：%s，消息：%s"
        % (result.get("status_code"), result.get("status_message"))
    )

TypeScript

typescript

import axios from "axios";

const postData = [
  {
    id: "07281559-0695-0216-0000-c269be8b7592",
    filters: [
      ["resource_type", "=", "image"],
      "and",
      ["size", ">", 100000],
    ],
    order_by: ["size,desc"],
    limit: 10,
  },
];

axios
  .post(
    "https://api.seermartech.cn/v3/on_page/resources",
    postData,
    {
      headers: {
        Authorization: "Bearer smt_live_YOUR_KEY",
        "Content-Type": "application/json",
      },
    }
  )
  .then((response) => {
    // 处理响应结果
    console.log(response.data);
  })
  .catch((error) => {
    console.error(error);
  });

C#

csharp

using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;

public static class OnPageResourcesDemo
{
    public static async Task GetResourcesAsync()
    {
        using var httpClient = new HttpClient();

        httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", "smt_live_YOUR_KEY");

        var postData = new List<object>
        {
            new
            {
                id = "07281559-0695-0216-0000-c269be8b7592",
                filters = new object[]
                {
                    new object[] { "resource_type", "=", "image" },
                    "and",
                    new object[] { "size", ">", 100000 }
                },
                order_by = new[] { "size,desc" },
                limit = 10
            }
        };

        var content = new StringContent(
            JsonConvert.SerializeObject(postData),
            Encoding.UTF8,
            "application/json"
        );

        var response = await httpClient.PostAsync(
            "https://api.seermartech.cn/v3/on_page/resources",
            content
        );

        var result = JsonConvert.DeserializeObject<dynamic>(
            await response.Content.ReadAsStringAsync()
        );

        if (result.status_code == 20000)
        {
            Console.WriteLine(result);
        }
        else
        {
            Console.WriteLine(
                $"错误。代码：{result.status_code}，消息：{result.status_message}"
            );
        }
    }
}

响应结构

接口返回 JSON 数据，顶层 tasks 数组。

json

{
  "version": "0.1.20200805",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "4.8323 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "07281559-0695-0216-0000-c269be8b7592",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "4.8323 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "on_page",
        "resources"
      ],
      "data": {
        "api": "on_page",
        "function": "resources",
        "limit": 100
      },
      "result": [
        {
          "crawl_progress": "finished",
          "crawl_status": {
            "max_crawl_pages": 100,
            "pages_in_queue": 0,
            "pages_crawled": 100,
            "total_items_count": 10,
            "items_count": 10
          },
          "items": []
        }
      ]
    }
  ]
}

响应字段

顶层字段

字段	类型	说明
`version`	string	当前 API 版本。
`status_code`	integer	通用响应状态码。成功时通常为 `20000`。
`status_message`	string	通用响应说明。
`time`	string	接口执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`tasks_count`	integer	`tasks` 数组中的任务总数。
`tasks_error`	integer	`tasks` 数组中返回错误的任务数量。
`tasks`	array	任务结果数组。

`tasks` 字段

字段	类型	说明
`id`	string	任务唯一标识，采用 UUID 格式。
`status_code`	integer	任务状态码，通常位于 `10000` 至 `60000` 范围。
`status_message`	string	任务状态说明。
`time`	string	任务执行耗时，单位为秒。
`cost`	float	平台原始 USD 成本兼容字段；人民币实扣以 `X-SeerMarTech-Charge-CNY` 为准。
`result_count`	integer	`result` 数组中的数量。
`path`	array	请求路径。
`data`	object	提交任务时使用的参数。
`result`	array	任务结果数组。

`result` 与爬取状态字段

字段	类型	说明
`crawl_progress`	string	爬取状态。可选值：`in_progress`、`finished`。
`crawl_status`	object	爬取会话。
`max_crawl_pages`	integer	创建任务时设置的最大爬取页面数。
`pages_in_queue`	integer	当前仍在爬取队列中的页面数量。
`pages_crawled`	integer	已爬取页面数量。
`total_items_count`	integer	爬取到的资源总数。
`items_count`	integer	当前结果中的资源数量。
`items`	array	资源数组。

资源字段

基础资源信息

字段	类型	说明
`resource_type`	string	资源类型。可选值：`script`、`image`、`stylesheet`、`broken`。
`meta`	object	资源属性，取决于 `resource_type`。未指定请求参数 `url` 时，基于爬虫首次发现该资源的页面返回。
`url`	string	资源 URL。
`status_code`	integer	资源所在页面的状态码。
`location`	string	`Location` 响应头，表示页面重定向目标 URL。
`content_encoding`	string	编码类型。
`media_type`	string	用于呈现资源的媒体类型。
`accept_type`	string	期望的资源类型。可选值：`any`、`none`、`image`、`sitemap`、`robots`、`script`、`stylesheet`、`redirect`、`html`、`text`、`other`、`font`。对于 `resource_type=broken` 的资源，该字段表示失效资源的类型。
`server`	string	服务器版本。
`from_sitemap`	boolean	资源是否在网站站点地图中被发现。

图片与标题信息

以下字段主要适用于 image 类型资源：

字段	类型	说明
`alternative_text`	string	图片 `alt` 属性。
`alternative_text_variations`	array	同一图片资源出现过的不同 `alt` 属性值。
`title`	string	标题。
`alternative_title_variations`	array	同一图片出现过的不同 `title` 属性值。
`original_width`	integer	图片原始宽度，单位为像素。
`original_height`	integer	图片原始高度，单位为像素。
`width`	integer	图片显示宽度，单位为像素。
`height`	integer	图片显示高度，单位为像素。

资源大小与加载信息

字段	类型	说明
`size`	integer	资源大小，单位为字节。
`encoded_size`	integer	编码后的资源大小，单位为字节。
`total_transfer_size`	integer	压缩后的资源传输大小，单位为字节。
`fetch_time`	string	获取资源的日期和时间，使用 UTC 格式：`yyyy-mm-dd hh-mm-ss +00:00`。
`fetch_timing`	object	资源获取时间范围。
`duration_time`	integer	获取资源耗时，单位为毫秒。
`fetch_start`	integer	开始下载资源所需的时间。
`fetch_end`	integer	完成资源下载所需的时间。

`cache_control`

缓存控制信息。

字段	类型	说明
`cachable`	boolean	资源是否可缓存。
`ttl`	integer	缓存有效期，单位为毫秒。

`checks`

资源检查结果。字段会根据资源类型变化。

字段	类型	说明
`no_content_encoding`	boolean	资源是否未使用压缩编码。适用于 `script`、`image`、`stylesheet`、`broken`。
`high_loading_time`	boolean	资源加载时间是否 3 秒。
`is_redirect`	boolean	资源所在页面是否发生 `3XX` 重定向。
`is_4xx_code`	boolean	资源所在页面是否返回 `4XX` 状态码。
`is_5xx_code`	boolean	资源所在页面是否返回 `5XX` 状态码。
`is_broken`	boolean	资源是否失效。资源所在页面返回 `4XX`、`5XX`，或资源损坏时为 `true`。
`is_www`	boolean	资源所在页面是否位于 `www` 子域名。
`is_https`	boolean	资源所在页面是否使用 HTTPS 协议。
`is_http`	boolean	资源所在页面是否使用 HTTP 协议。
`original_size_displayed`	boolean	图片是否以原始尺寸显示。适用于 `image`。
`is_minified`	boolean	样式表或脚本是否已压缩。适用于 `stylesheet`、`script`。
`has_redirect`	boolean	资源是否重定向。适用于 `script`、`image`。对于图片，表示页面或资源是否重定向到该图片；对于脚本，表示脚本是否重定向。
`has_subrequests`	boolean	样式表或脚本是否额外请求。适用于 `stylesheet`、`script`。

`resource_errors`

资源错误和警告信息。

`errors`

字段	类型	说明
`line`	integer	发现错误的行号。
`column`	integer	发现错误的列号。
`message`	string	错误文本信息。
`status_code`	integer	错误状态码。

错误状态码：

状态码	含义
`0`	未识别错误
`501`	HTML 解析错误
`1501`	JavaScript 解析错误
`2501`	CSS 解析错误
`3501`	图片解析错误
`3502`	图片缩放值为 0
`3503`	图片尺寸为 0
`3504`	图片格式无效

`warnings`

字段	类型	说明
`line`	integer	警告对应的行号。为 `0` 时表示警告涉及整个页面。
`column`	integer	警告对应的列号。为 `0` 时表示警告涉及整个页面。
`message`	string	警告文本。
`status_code`	integer	警告状态码。

常见警告信息：

Has node with more than 60 childs.：HTML 页面中至少存在一处同级标签嵌套 60 层。
Has more that 1500 nodes.：DOM 树 1,500 个。
HTML depth more than 32 tags.：HTML DOM 深度 32 层。

警告状态码：

状态码	含义
`0`	未识别警告
`1`	节点 60 个子节点
`2`	节点数量 1,500 个
`3`	HTML 深度 32 层

`last_modified`

资源变更信息。如果没有对应数据，字段值为 null。

字段	类型	说明
`header`	string/null	HTTP 头部记录的最后修改时间，使用 UTC 格式。
`sitemap`	string/null	站点地图记录的最后修改时间，使用 UTC 格式。
`meta_tag`	string/null	Meta 标签记录的最后修改时间，使用 UTC 格式。

时间格式示例：

text

2019-11-15 12:57:46 +00:00

状态码与错误处理

请根据顶层 status_code 和任务级 tasks[].status_code 判断请求及任务是否成功。建议在客户端实现错误处理机制，覆盖 HTTP 异常、任务状态异常及结果为空等。

完整状态码请参考错误码文档。

实用场景

识别失效图片、脚本和样式表，减少 4XX/5XX 资源错误对抓取与页面体验的影响。
筛选指定大小的图片资源，定位影响页面加载速度的文件并指导压缩优化。
检查脚本和样式表是否完成压缩，降低静态资源体积并改善核心网页指标。
分析资源加载耗时与传输大小，定位高加载时间资源并优化前端性能。
核查图片 alt、标题及显示尺寸，批量发现无障碍和图片 SEO 优化问题。

on_page/resources：获取页面资源列表 ​

请求信息 ​

计费说明 ​

请求参数 ​

filters 与 relevant_pages_filters ​

order_by ​

请求示例 ​

cURL ​

Python ​

TypeScript ​

C# ​

响应结构 ​

响应字段 ​

顶层字段 ​

tasks 字段 ​

result 与爬取状态字段 ​

资源字段 ​

基础资源信息 ​

图片与标题信息 ​

资源大小与加载信息 ​

cache_control ​

checks ​

resource_errors ​

errors ​

warnings ​

last_modified ​

状态码与错误处理 ​

实用场景 ​

on_page/resources：获取页面资源列表

请求信息

计费说明

请求参数

`filters` 与 `relevant_pages_filters`

`order_by`

请求示例

cURL

Python

TypeScript

C#

响应结构

响应字段

顶层字段

`tasks` 字段

`result` 与爬取状态字段

资源字段

基础资源信息

图片与标题信息

资源大小与加载信息

`cache_control`

`checks`

`resource_errors`

`errors`

`warnings`

`last_modified`

状态码与错误处理

实用场景