切换主题
语言
German English Spanish French Japanese Korean Russian Chinese (Simplified)

API 文档

平台 API 集成规则

简明的集成参考：正确传递 API 密钥、选择响应结构、发出第一个请求、处理错误并校验模拟数据。

API 参考 V2 平台 API 参考 V1
从哪里开始

本页面确定的内容

本页面汇总了与具体 API 方法无关的规则：身份验证、响应版本、错误处理、重试、模拟 API 的使用以及上线检查。

API 方法的参数、数据结构和特定示例请查阅 API 参考。比较覆盖范围和方法分组请使用平台页面。

请将本页面作为团队开展新集成的基准。它是对 API 参考的补充，而非重复。
每个请求都要带密钥

身份验证

在每个平台 API 请求中通过 `X-API-Key` 请求头发送您的 API 密钥。

该密钥不会从控制台会话中继承。后端服务、worker 和后台任务都必须显式附加此请求头。

  • 将密钥保存在密钥存储中，并在访问权限变更或怀疑泄露时轮换密钥。
  • 不要将密钥放在浏览器代码、公开仓库、客户端打包文件或日志中。
  • 尽可能按环境和服务限制对密钥的访问。
响应版本

选择响应结构

V1 和 V2 提供相同的 API 方法目录，但返回不同的数据结构。请在构建客户端之前选定版本，并将其固定在集成配置中。

不要在同一处理流程中混用 V1 和 V2。这会使字段映射、缓存、测试和维护变得更加困难。

V1
V1 原始响应

保留源平台的响应结构，ScrapeStorm 仅做最少的改动。

适用场景

迁移、向后兼容，以及已依赖平台原生字段的客户端。

V2
V2 规范化响应

为产品代码、分析和内部服务提供更稳定的数据契约。

适用场景

新集成、新服务，以及任何不需要源平台数据结构的代码。

默认使用 V2。仅在需要兼容或迁移现有客户端时保留 V1。
传输检查

发出第一个真实 API 请求

选定版本后，请使用一个真实 API 方法验证集成：基础 URL、请求头、查询参数、超时和错误处理。

HTTP 方法 GET
端点 /api/v2/youtube.com/profile/about-by-user-identifier
查询参数示例 user_identifier=mkbhd
请求头 X-API-Key

此示例使用 YouTube 的 `profile/about-by-user-identifier` API 方法。请将 `user_identifier` 替换为您自己场景中的测试标识符。

一次成功的响应只能证明传输和顶层响应结构正常。请验证您计划上线的每个 API 方法，以及限制、价格和故障处理。
响应外层结构

校验响应结构

V1 和 V2 中的公开平台 API 方法使用相同的外层结构：`success`、`status` 和 `data`。集合类方法还可能包含顶层的 `pagination`。

版本选择改变的是 `data` 内部的结构，而不是传输外壳。所选 API 方法的具体数据字段请查阅 API 参考。

响应情况 顶层字段 优先查看的内容
成功响应 success, status, data `data` 包含方法的数据。
分页的成功响应 success, status, pagination, data `pagination` 位于顶层；方法数据仍在 `data` 中。
错误响应 success, status, error, meta 根据 HTTP 状态码和 `error.code` 进行分支处理。
不要根据外层结构推断是 V1 还是 V2。请在 URL 和客户端配置中固定版本，然后按该版本的 API 参考解析 API 方法的数据结构。
错误与重试

按错误码而不是按文本处理错误

错误使用统一的外层结构。请根据 HTTP 状态码和 `error.code` 进行分支处理。`message` 字段适合用于展示或日志，但不应用于应用程序的控制流程。

  • 在原因改变之前，不应重试 `401`、`402` 和 `422`。
  • `429 RATE_LIMIT_EXCEEDED` 只能在 `Retry-After` 或 `error.retry_after_seconds` 指定的时间之后重试。
  • `500` 和 `503` 应使用有上限的退避策略并设置严格的尝试次数上限进行重试。
HTTP 状态码 错误代码 客户端操作
401 未授权 UNAUTHORIZED 检查 API 密钥和环境。不要用同一个密钥循环发送同一请求。
422 校验失败 VALIDATION_FAILED 修正请求参数。相同的输入会返回相同的错误。
402 积分不足 INSUFFICIENT_CREDITS 暂停流程，直到余额或账户限制更新。
429 超出并发连接数 CONCURRENT_CONNECTIONS_EXCEEDED 减少每个 API 密钥的并行任务，或将请求排队。
429 超出速率限制 RATE_LIMIT_EXCEEDED 等待公布的重试间隔，并在各 worker 之间协调重试。
503 端点不可用 ENDPOINT_UNAVAILABLE 如果其他方法运行正常，请只对该 API 方法应用退避策略，而不是暂停整个集成。
500 服务器内部错误 INTERNAL_SERVER_ERROR 使用有上限的退避策略重试。达到尝试次数上限后，记录日志并通过监控上报。
对于 `RATE_LIMIT_EXCEEDED`，下一次重试时间的唯一可信来源是 `Retry-After` 或 `error.retry_after_seconds`。
模拟 API

在模拟数据上校验结构

模拟 API 方法返回静态 JSON 示例，不会调用源平台。可将其用于客户端开发、UI 工作和解析器测试。

模拟 API 无法证明方法可用性、数据新鲜度、限制、价格或上线后的表现。上线前请在正式 API 上重复相同的场景。
  • 不要使用模拟数据验证数据新鲜度。
  • 不要将模拟数据中的值复制到正式环境的集成逻辑中。
  • 只比较外层结构、字段名称和基本响应结构。
模拟 API https://www.scrapestorm.net/api-mock
示例 https://www.scrapestorm.net/api-mock/v2/youtube.com/profile/about-by-user-identifier?user_identifier=mkbhd
API 参考
模拟 API 参考 V2 模拟 API 参考 V1
上线前

生产环境检查清单

在接入正式流量和提高 worker 并发之前，请检查以下各项。

  1. 01

    响应版本已固定

    新客户端使用 V2。V1 仅允许用于兼容或迁移现有集成。

  2. 02

    API 密钥作为机密存储

    密钥保存在密钥存储中，不出现在前端代码、公开仓库、客户端打包文件和日志中。

  3. 03

    错误处理基于机器可读的错误码

    客户端分支依赖 HTTP 状态码和 `error.code`。业务逻辑中不使用 `message`。

  4. 04

    重试次数有上限

    `RATE_LIMIT_EXCEEDED` 会等待 `Retry-After` 或 `error.retry_after_seconds`。`402` 和 `422` 不会以未更改的输入重试。`500` 和 `503` 具有退避策略和尝试次数上限。

  5. 05

    按 API 密钥控制并发

    队列或限流器会限制来自 worker、定时任务和后台进程的同时请求数。

  6. 06

    分别验证模拟环境与正式环境

    模拟数据用于验证数据结构。正式 API 用于验证真实参数、限制、可用性和积分消耗。

  7. 07

    已确认 API 方法价格

    在流量增长之前，查看您计划使用的 API 方法的费用。