TikTok: איך לוודא שניטור החיפוש באמת פועל

HTTP 200 אינו מבטיח שניטור TikTok היומי אסף סרטונים. תוצאות החיפוש עשויות להימצא ב-aweme_list או ב-search_item_list[].aweme_info; סקריפט שקורא רק את המערך הראשון עלול להסתיים בלי שגיאה ולכתוב דוח ריק. בדיקה אמינה מאמתת בנפרד את סטטוס התעבורה ואת הסטטוס היישומי, שולפת את שתי וריאציות המבנה הנתמכות ומתעדת כמה סרטונים ייחודיים חולצו בהרצה זו.

מה בדיוק כדאי לאבחן

נניח שהצוות אוסף מדי בוקר סרטונים ציבוריים לפי כמה שאילתות, כדי לזהות פרסומים חדשים על מוצר. תוצאה חשובה של התהליך היא רשימה שניתן לשחזר של הרשומות שנמצאו, עם תיאור, מחבר, תאריך פרסום ומדדים זמינים. אם הדוח מתרוקן פתאום, הסיבה עשויה להיות עיבוד JSON, שינוי במערך התוצאות, הצגה חוזרת של סרטונים שכבר מוכרים או כשל אמיתי בבקשה. מספר יחיד — למשל אורך aweme_list — אינו מאפשר להבחין בין האפשרויות האלה.

ב-TikTok Scraper API של jsonscraper, נתיב החיפוש /searchVideo מקבל את הפרמטר keyword כחובה, וכן את הפרמטרים הנוספים count, cursor, date_posted, sort_by ו-region. תיעוד הנתיב מתאר עימוד באמצעות cursor; יש להעביר אותו כערך אטום מהתגובה הקודמת. הפרמטר count קובע את מספר התוצאות הרצוי, אך אינו מבטיח כיסוי מלא של הפרסומים.

חלקו את הבדיקה לארבעה אותות

אבחון מועיל מורכב מארבע בדיקות נפרדות. הראשונה — בקשת HTTP הסתיימה בהצלחה. השנייה — ה-status החיצוני של התשובה הוא ok, ו-tiktok.status_code הפנימי מציין תשובה מוצלחת. השלישית — אובייקט tiktok קיים, וניתן לחלץ רשומות משני המקומות המתועדים בתשובה. הרביעית — לאחר הסרת כפילויות נותרו רשומות עם מזהים המתאימים לאחסון. שמרו ביומן את מספר הפריטים שחולצו לפני ואחרי הסרת הכפילויות: ההפרש מראה אם נוצרו חזרות בשלב הנרמול.

שדה חסר צריך להישאר ריק, ולא לקבל ערך מומצא. לדוגמה, מונה הצפיות עשוי להיות חסר ברשומה מסוימת. שמירת JSON המקורי לצד השורה המנורמלת מסייעת לבדוק בהמשך אם המידע אבד בעת הניתוח או שלא היה בתשובה המקורית.

בקשה מינימלית ונרמול ב-Python

מפרט jsonscraper מגדיר את כתובת הבסיס https://tiktok.evelode.com ואת העברת המפתח בפרמטר הבקשה license_key. הדוגמה שלהלן משתמשת בפרמטרים המתועדים; המפתח נקרא ממשתנה סביבה ואינו נכתב ליומן. התקינו את התלות באמצעות הפקודה python -m pip install requests, ואז הגדירו את JSONSCRAPER_TIKTOK_LICENSE_KEY בסביבה.

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):
    """איסוף סרטונים משני המבנים המוכרים של תשובת חיפוש."""
    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": "דוגמה לשאילתה על מוצר",
        "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 החזיר סטטוס חיצוני שאינו ok")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("אובייקט tiktok חסר בתשובה")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("ה-status_code הפנימי אינו שווה לערך ההצלחה 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()

הסקריפט בודק את שכבת התעבורה באמצעות raise_for_status(), ולאחר מכן בודק את הסטטוס החיצוני, את קיומו של האובייקט tiktok ואת ה-status_code הפנימי. לאחר מכן הוא שולף רשומות משני מבני החיפוש, מסיר כפילויות לפי aweme_id ושומר תמונת מצב עם מועד האיסוף. גם אם לא נמצאו רשומות מתאימות, הקובץ עדיין מכיל פרטים על ההרצה, וכך אפשר להבחין בין תוצאה ריקה שנשמרה לבין דוח חסר.

איך להפוך תמונות מצב לאות לצוות

הריצו את הסקריפט לפי לוח זמנים באמצעות cron, CI או מתזמן תהליכי עבודה. שמרו תמונות מצב נפרדות לכל שאילתה, או הוסיפו את מילת המפתח לשם הקובץ. בטבלת המצב די לתעד את מועד ההרצה, הסטטוס, מספר הרשומות שחולצו ומספר הרשומות הייחודיות, וכן את הדגל has_more. כדאי לשלוח התראה במקרה של חריגת בקשה, היעדר חלקים חיוניים בתשובה או שינוי חד במספר הרשומות שחולצו ביחס להיסטוריה של אותו תהליך.

השוואה כזו מזהה חריגה בצינור הנתונים, אך אינה מסבירה כשלעצמה את סיבתה. מספר תוצאות קטן יותר עשוי לשקף את הרכב התוצאות הנוכחי, ולא תקלה ב-API או במנתח. לכן כדאי לשמור את JSON המקורי, להשוות פרמטרים זהים ולבדוק את המזהים שנמצאו. בחרו את סף ההתראה על סמך תצפיות בשאילתה שלכם, ולא לפי מספר אוניברסלי.

לצורך עימוד, השתמשו ב-cursor מהתשובה והפסיקו לסרוק כשה-API מציין שאין תוצאות נוספות. שמרו את הסמנים שבהם השתמשתם ואת פרמטרי הבקשה, כדי שיהיה אפשר לשחזר את ההרצה. הפרמטרים date_posted ו-sort_by מאפשרים להגדיר מסנן זמן ומיון; אם המשימה דורשת השוואות עקביות, קבעו אותם באופן זהה בכל ההרצות.

איך לקרוא את התוצאה

לאחר ההטמעה, לצוות יש תשובה שניתן לבדוק לשלוש שאלות מעשיות: האם הבקשה הצליחה, היכן נמצאות התוצאות ב-JSON וכמה סרטונים ייחודיים נכללו בתמונת המצב שנשמרה. כך מתקצר המסלול מטבלה ריקה לאבחון: תחילה בודקים סטטוסים ומבנה, ואז את הפרמטרים, הכפילויות והתוכן של התשובה המקורית.

סכמת התשובה והשדות הזמינים עשויים להשתנות בין רשומות. בבדיקת live של jsonscraper ב-25 באוקטובר 2026, החיפוש החזיר שדות של מזהה, תיאור, מחבר וסטטיסטיקה; יש להתייחס לערכים ברשומה מסוימת כאל ערכים שאינם מובטחים. דוח תקין שומר את הנתונים שהתקבלו בפועל ואינו מחליף ערכים חסרים באפסים.

אפשר להתחיל בעמוד TikTok Scraper API, ולהצליב את הנתיבים והפרמטרים המדויקים עם תיעוד ה-API הרשמי. בדיקה כזו מועילה לפני הפעלת הניטור: הדוח הופך לתוצאה ניתנת לצפייה, שאפשר לאבחן את איכותה.