TikTok: jak ověřit, že monitorování vyhledávání skutečně funguje

HTTP 200 nezaručuje, že každodenní monitorování TikToku shromáždilo videa. Výsledky vyhledávání mohou být v aweme_list nebo v search_item_list[].aweme_info; skript, který čte pouze první pole, může skončit bez chyby a zapsat prázdný report. Spolehlivá kontrola samostatně ověřuje stav přenosu i aplikace, získává data z obou podporovaných struktur a zaznamenává, kolik jedinečných videí se podařilo při tomto spuštění získat.

Co přesně diagnostikovat

Představte si tento úkol: tým každé ráno shromažďuje veřejná videa pro několik dotazů, aby zaznamenal nové příspěvky o produktu. Důležitým výsledkem tohoto procesu je reprodukovatelný seznam nalezených záznamů s popisem, autorem, datem zveřejnění a dostupnými metrikami. Pokud je report náhle prázdný, může být příčinou zpracování JSON, změněná sada výsledků, opětovné vrácení již známých videí nebo skutečné selhání požadavku. Jediné číslo — například délka aweme_list — tyto případy nerozliší.

Trasa /searchVideo v TikTok Scraper API od jsonscraper přijímá povinný parametr keyword a další parametry count, cursor, date_posted, sort_by a region. Dokumentace trasy popisuje stránkování pomocí cursor; ten je třeba předat jako neprůhlednou hodnotu z předchozí odpovědi. Parametr count určuje požadovaný počet výsledků, nikoli záruku úplného pokrytí příspěvků.

Rozdělte kontrolu na čtyři signály

Užitečná diagnostika se skládá ze čtyř nezávislých kontrol. První: požadavek HTTP skončil úspěšně. Druhá: vnější hodnota status odpovědi je ok a vnitřní tiktok.status_code odpovídá úspěšné odpovědi. Třetí: objekt tiktok je přítomen a záznamy lze získat z obou dokumentovaných míst v odpovědi. Čtvrtá: po odstranění duplicit zůstaly záznamy s identifikátory vhodnými k uložení. Do protokolu ukládejte počet získaných položek před odstraněním duplicit i po něm: rozdíl ukáže, zda se duplicity objevily během normalizace.

Chybějící pole ponechte prázdné, nenahrazujte je vymyšlenou hodnotou. Například počet zhlédnutí může v konkrétním záznamu chybět. Uložení původního JSON vedle normalizovaného řádku pomůže později ověřit, zda se informace ztratila při parsování, nebo zda v původní odpovědi vůbec nebyla.

Minimální požadavek a normalizace v Pythonu

Specifikace jsonscraper uvádí základní adresu https://tiktok.evelode.com a předávání klíče v parametru požadavku license_key. Níže uvedený příklad používá dokumentované parametry; klíč se načítá z proměnné prostředí a nevypisuje se do protokolu. Nainstalujte závislost příkazem python -m pip install requests a poté nastavte proměnnou JSONSCRAPER_TIKTOK_LICENSE_KEY v prostředí.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def extract_videos(payload):
    """Shromáždí videa z obou známých struktur odpovědi search."""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

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

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "ukázkový dotaz o produktu",
        "count": 20,
        "region": "US",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API vrátilo vnější stav odlišný od ok")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("V odpovědi chybí objekt tiktok")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("Vnitřní status_code se nerovná úspěšné hodnotě 0")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

Skript ověřuje transportní vrstvu pomocí raise_for_status(), poté kontroluje vnější stav, přítomnost objektu tiktok a vnitřní status_code. Následně získá záznamy ze dvou struktur výsledků vyhledávání, odstraní duplicity podle aweme_id a uloží snímek s časem sběru. Pokud nejsou k dispozici žádné vhodné záznamy, soubor přesto obsahuje informace o spuštění, což umožňuje rozlišit uložený prázdný výsledek od chybějícího reportu.

Jak ze snímků vytvořit signál pro tým

Spouštějte skript podle plánu pomocí nástrojů cron, CI nebo plánovače pracovního postupu. Snímky pro jednotlivé dotazy ukládejte odděleně, případně přidejte klíčové slovo do názvu souboru. Do stavové tabulky stačí zapisovat čas spuštění, stav, počet získaných a jedinečných záznamů a také příznak has_more. Upozornění je vhodné odeslat při výjimce požadavku, chybějících povinných částech odpovědi nebo prudké změně počtu získaných záznamů oproti vlastní historii.

Takové srovnání odhalí anomálii pipeline, samo o sobě však nevysvětlí její příčinu. Menší počet výsledků může odrážet aktuální skladbu výsledků, nikoli poruchu API nebo parseru. Proto je užitečné ukládat původní JSON, porovnávat stejné parametry a kontrolovat nalezené identifikátory. Prahovou hodnotu pro upozornění zvolte na základě pozorování právě pro váš dotaz, nikoli podle univerzálního čísla.

Při stránkování použijte cursor z odpovědi a procházení ukončete, když API oznámí, že další výsledky nejsou k dispozici. Ukládejte použité kurzory a parametry požadavku, aby bylo možné spuštění reprodukovat. Parametry date_posted a sort_by umožňují nastavit časový filtr a řazení; pokud úloha vyžaduje opakovatelné porovnávání, zachovávejte je mezi jednotlivými spuštěními.

Jak číst výsledek

Po zavedení tohoto postupu získá tým ověřitelnou odpověď na tři praktické otázky: zda se požadavek uskutečnil, kde se výsledky v JSON nacházejí a kolik jedinečných videí bylo zahrnuto do uloženého snímku. Tím se zkrátí cesta od prázdné tabulky k diagnostice: nejprve se kontrolují stavy a struktura, potom parametry, duplicity a obsah původní odpovědi.

Schéma odpovědi a dostupná pole se mohou u jednotlivých záznamů lišit. Při živé kontrole jsonscraper dne 25. října 2026 vyhledávání vracelo pole s identifikátorem, popisem, autorem a statistikami; hodnoty v konkrétním záznamu je třeba považovat za nepovinné. Provozní report uchovává skutečně získaná data a nenahrazuje chybějící hodnoty nulami.

Začít můžete na stránce TikTok Scraper API a přesné trasy a parametry ověřit v oficiální dokumentaci API. Tato kontrola se hodí před spuštěním monitorování: report se stává pozorovatelným výsledkem, jehož kvalitu lze diagnostikovat.