解析 JSON 时如何避免遗漏 TikTok 搜索结果

通过 API 搜索 TikTok 视频时，视频可能不在处理程序首先预期的数组中。在 jsonscraper 对 `` 请求进行的一次验证中，`aweme_list` 字段为空，而包含视频数据的条目位于 `search_item_list[].aweme_info` 中。如果代码只读取 `aweme_list`，就会保存零条视频，尽管响应中确实包含搜索结果。对开发者而言，这是一项具体的可靠性工作：从两种数据结构中提取内容，并在写入数据库或发送到报告前将其规范化为一个统一列表。

可在 jsonscraper API 规范和 TikTok 接口文档中查看实际示例和接口说明。规范中的模式快照日期为 2026 年 10 月 25 日；它展示的是某个具体响应的结构，并不保证每次后续请求都包含所有字段。

为什么解析器可能返回空列表

`GET https://tiktok.evelode.com/searchVideo` 接口通过必填参数 `keyword` 搜索视频。文档还列出了 `cursor`、`count`、`cache_timeout`、`date_posted`、`sort_by` 和 `region`。在观测到的响应模式中，顶层对象包含 `status` 和嵌套的 `tiktok` 对象；后者包含 `cursor`、`has_more`、`status_code`、`aweme_list` 和 `search_item_list`。

在一次使用关键词并设置 `count=3` 的观测中，`aweme_list` 数组为空。与此同时，`search_item_list` 包含若干条目，其中的视频信息位于 `aweme_info` 中。这些对象可能包含视频 ID、说明文字、发布 URL、作者信息和统计数据，例如播放、点赞或评论次数。上述字段反映的是观测到的模式；处理程序仍应能够应对字段缺失的情况。

实际要点是，HTTP 请求成功与某个预期字段中的数组非空，是两项不同的检查。先检查外层状态以及是否存在 `tiktok`，然后从所有有文档说明的位置收集视频。用于分析时，请保存 ID 和原始响应，以便追踪具体记录是如何提取和规范化的。

写入存储前先规范化响应

API 与自有系统之间可以通过一个清晰的边界来衔接：编写一个接收嵌套 `tiktok` 对象并返回统一条目的函数。函数应处理两个数组，跳过非字典或空条目，并按 `aweme_id` 去除重复视频。如果服务提供方未返回计数，就让计数保持为空：零表示测得的数值，而 `None` 表示字段缺失。

下面是一个适用于 Python 3.8 及以上版本的最小示例。它发送一次请求，检查传输状态和顶层状态，规范化两种结果形式，并打印选定字段。密钥从环境变量读取，不会输出到日志中。

import os
import requests

BASE_URL = "https://tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

    search_items = tiktok.get("search_item_list") or []
    if isinstance(search_items, list):
        for item in search_items:
            if isinstance(item, dict):
                candidates.append(item.get("aweme_info"))

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

运行 python -m pip install requests 安装依赖，在运行环境中设置 `JSONSCRAPER_TIKTOK_LICENSE_KEY`，并将文件保存为例如 `search_videos.py`。请求参数与文档列出的名称一致：`keyword`、`count` 和 `region`；`license_key` 作为查询参数传递。代码假设响应包含 `status: "ok"`，与记录在案的示例一致。如果 API 返回其他状态，处理流程会立即停止，避免将可疑结构传递到后续环节。

如何将示例改造成可重复的数据采集流程

一次性导出时，将规范化后的条目写入 JSON Lines 或表格即可。在持续运行的流程中，还应保存原始响应，并记录获取时间和搜索词。规范化后的视频表可以用 `aweme_id` 作为键：再次获取到同一结果时更新记录，而同一 ID 同时出现在两个数组中也不会产生重复项。

如需请求下一页，文档指出应使用 `cursor` 参数，并传入上一次响应中获取的值。请将其视为不透明令牌，原样存储和传回。若 `has_more` 表示没有后续内容，或者 API 未提供可用游标，分页循环就应结束；同时限制每次运行的页数，避免错误逻辑造成无限循环。记录在案的资料确认了该参数名称，以及观测到的模式中存在 `cursor` 和 `has_more` 字段，但并未保证结果完整。

如果要监控多个搜索词，请将搜索词与视频 ID、采集时间一并保存。这样便能按查询词生成切片、比较不同运行批次的结果，并将新 ID 发送到后续分类队列。这样的系统描述的是实际获取到的搜索结果；其数据集取决于查询词、地区、时间以及 API 实际返回的条目。

检查数据质量，而不仅是请求是否成功

规范化后，可以为数据流程记录一些简单的技术指标：来自每个数组的记录数、唯一 ID 数量、缺少 ID 的条目比例，以及缺少统计数据的条目比例。这些指标描述的是对具体响应的处理情况，并非视频受欢迎程度的评估。例如，缺少 `play_count` 的条目增多，说明分析系统应保留未知值并标记字段完整性，而不是填入零。

不要让后续计算依赖于每个视频都必然包含相同的一组统计数据。保存原始数据时，应保留完整 JSON；分析表则只选择需要的字段，并允许 `NULL`。如果响应结构发生变化，原始归档能让你重新运行规范化程序，而无需再次发起请求。

通过 CI 密钥管理系统或编排器的环境变量传递 API 密钥。不要将密钥放入可能被保存到日志中的 URL，不要打印请求参数对象，也不要将密钥与原始响应一同保存。如果任务按计划运行，请设置请求超时，处理 HTTP 错误，并在重试时加入间隔；仅在对应的搜索词范围内保存游标，避免混淆不同结果集的分页。

结果：从遗漏视频到统一表格

规范化后，无论视频来自 `aweme_list` 还是 `search_item_list[].aweme_info`，下游代码都会收到同一个视频列表。ID 可用于去重，而可选字段则会明确保持为空。这样可以降低只读取一个数组而导致报告为空的风险，也让下一阶段——导出、筛选或分类——更可预测。

你可以从 TikTok Scraper API 页面开始验证，该页面列出了 API 基础地址，并提供前往演示的入口。集成时请使用官方文档，并先用少量条目测试处理逻辑；需要时再增大 `count`，并使用文档说明的游标继续获取结果。最终得到的是适用于你自身任务的整洁数据层，而不是对 TikTok 全部内容都已覆盖的假设。