jsonscraper
שווקים
חזרה ליומן

איך להפוך חיפוש ב-TikTok ליומן שינויים שבועי

סקריפט Python שומר סרטונים חדשים שנמצאו, משווה ביניהם לפי מזהה ומפיק CSV לבדיקה שוטפת של נושאים

מדיניות עריכה דיווח על שגיאה

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

המטרה: לזהות רשומות חדשות, במקום לבדוק מחדש את כל התוצאות

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

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

מה להכין

  • Python בגרסה 3.8 ואילך.
  • גישה ל-TikTok Scraper API ומפתח רישיון.
  • שאילתת חיפוש שאפשר לחזור עליה בלי לשנות את משמעותה, למשל שם מוצר או ביטוי מסוים.

שמרו את המפתח במשתנה הסביבה JSONSCRAPER_TIKTOK_LICENSE_KEY, ולא בקובץ הסקריפט. בדוגמה שלהלן המפתח מועבר כפרמטר הבקשה license_key, בהתאם לסכמת ה-API. אל תדפיסו אותו ליומן ההרצה.

export JSONSCRAPER_TIKTOK_LICENSE_KEY="המפתח_שלכם"
python -m pip install requests

ב-Windows PowerShell אפשר להגדיר את המשתנה למושב הנוכחי כך: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="המפתח_שלכם". אל תוסיפו סודות אמיתיים ל-Git או לקובץ CSV משותף.

אינטגרציה: שליחת חיפוש ונרמול JSON

לחיפוש סרטונים, התיעוד מתאר את נתיב GET בשם /searchVideo, עם הפרמטר הנדרש keyword. בבקשה אפשר גם להגדיר count, אזור, מיון, מסנן זמן וסמן להמשך מעבר על התוצאות. בדוגמה המינימלית הזאת משתמשים רק במילת המפתח, במספר הפריטים המבוקש ובאזור ארה״ב. מדריך הנתיבים של TikTok API מפרט את שמות הפרמטרים המדויקים.

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

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

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "שם המוצר"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")

license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
    raise RuntimeError("הגדירו את JSONSCRAPER_TIKTOK_LICENSE_KEY")

response = requests.get(
    BASE_URL,
    params={
        "license_key": license_key,
        "keyword": KEYWORD,
        "count": COUNT,
        "region": REGION,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

# דוגמת התשובה כוללת status חיצוני ואובייקט tiktok מקונן.
if "status" in data and data["status"] != "ok":
    raise RuntimeError("ה-API החזיר סטטוס שאינו ok")

tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
    info = entry.get("aweme_info")
    if isinstance(info, dict):
        items.append(info)

# פריטים ייחודיים בתשובה הנוכחית, תוך שמירה על הסדר.
current = {}
for item in items:
    video_id = item.get("aweme_id")
    if video_id:
        current[str(video_id)] = item

if STATE_FILE.exists():
    seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
    seen = set()

new_items = [(video_id, item) for video_id, item in current.items()
             if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()

fields = ["collected_at_utc", "query", "aweme_id", "created_at",
          "author", "description", "share_url", "play_count",
          "digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=fields)
    if write_header:
        writer.writeheader()
    for video_id, item in new_items:
        author = item.get("author") or {}
        stats = item.get("statistics") or {}
        writer.writerow({
            "collected_at_utc": run_time,
            "query": KEYWORD,
            "aweme_id": video_id,
            "created_at": item.get("create_time"),
            "author": author.get("unique_id") or author.get("nickname"),
            "description": item.get("desc"),
            "share_url": item.get("share_url"),
            "play_count": stats.get("play_count"),
            "digg_count": stats.get("digg_count"),
            "comment_count": stats.get("comment_count"),
            "share_count": stats.get("share_count"),
        })

seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"בתשובה: {len(current)} סרטונים ייחודיים; חדשים: {len(new_items)}")

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

איך פועלת בדיקת השינויים

  1. הבקשה מחזירה עמוד של תוצאות חיפוש עבור מילת המפתח הנתונה.
  2. המנרמל אוסף רשומות מתוך aweme_list ומ-search_item_list[].aweme_info.
  3. הסקריפט מסיר כפילויות בתוך התשובה לפי מזהה הסרטון.
  4. המזהים מושווים ליומן JSON מקומי.
  5. מזהים חדשים מתווספים ל-CSV, ואז כל קבוצת המזהים שנצפתה נשמרת להרצה הבאה.
מאמר: איך להפוך חיפוש ב-TikTok ליומן שינויים שבועי
תקציר: הגדירו איסוף חוזר של סרטוני TikTok לפי מילת מפתח: עבדו עם שתי צורות התשובה של ה-API, הסירו כפילויות ושמרו רק רשומות חדשות לדוח השבועי.
תפקיד התמונה: איור תומך 2 — היבט מסוים נוסף
מקטע: איך פועלת בדיקת השינויים
נושא חזותי: אינפוגרפיקה ברורה ברוסית המציגה חמישה שלבים מאומתים בתהליך עם תוויות: בקשה / שני מערכי תשובה / הסרת כפילויות לפי awe
התרשים מציג את המעבר מתשובת החיפוש ל-CSV של רשומות חדשות וליומן JSON להרצה הבאה.© jsonscraper · איור שנוצר באמצעות בינה מלאכותית
מאמר: איך להפוך חיפוש ב-TikTok ליומן שינויים שבועי
תקציר: הגדירו איסוף חוזר של סרטוני TikTok לפי מילת מפתח: עבדו עם שתי צורות התשובה של ה-API, הסירו כפילויות ושמרו רק רשומות חדשות לדוח השבועי.
תפקיד התמונה: תמונת שער — הרעיון המרכזי
מקטע: איך פועלת בדיקת השינויים
נושא חזותי: טבע דומם מערכתי של סקירת נתונים שבועית: כרטיסים שקופים מוערמים המייצגים תוצאות חיפוש של סרטונים ציבוריים קצרים, וכרטיס חדש אחד לצד קומפקטי
מזהים חדשים ביומן המקומי מופרדים מסרטונים שנמצאו שוב.© jsonscraper · נוצר באמצעות בינה מלאכותית

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

הרצה חוזרת ועימוד

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

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

התרחיש הנוכחי אינו כולל בכוונה סיווג טקסט אוטומטי או מסקנה על «טרנד». ה-CSV עוזר לזהות במהירות רשומות חדשות שנמצאו; לאחר מכן אנליסט יכול לתייג אותן לפי נושא, כוונה או סוג שאלה ולבדוק דוגמאות ידנית. אם מחברים מודל שפה, העבירו לו רק את שדות הטקסט הנחוצים ובקשו שיחזיר קטגוריות לצד המזהה המקורי, כדי שאפשר יהיה לאמת את התוצאה ולקשר אותה לרשומה.

בדיקות ושגיאות נפוצות

  • שגיאת HTTP. raise_for_status() עוצר את ההרצה כאשר קוד ה-HTTP אינו בטווח ההצלחה. בדקו את זמינות ה-API, הפרמטרים והחשבון לפני עדכון קובץ המצב.
  • הסטטוס של ה-API שונה מ-ok. הסקריפט נעצר לפני כתיבת התוצאות אם בתשובה מופיע שדה status ברמה העליונה ובו ערך אחר. כך היומן הקודם נשמר, ונמנע מצב שבו תשובה שגויה נתפסת כחיפוש ללא תוצאות.
  • רשימה ריקה ב-aweme_list. בדקו גם את search_item_list; הקוד מתחשב בשני המבנים.
  • סרטונים חוזרים בין הרצות. הדבר צפוי כאשר עמודי תוצאות החיפוש חופפים: סרטונים לא יופיעו שוב בדוח אם המזהה שלהם כבר נשמר.
  • מדד חסר. התא נשאר ריק. בחישובים יש להבחין בין ערכים חסרים לאפסים בפועל.
  • המצב אבד. הסקריפט יתייחס לכל המזהים שהוחזרו כאל חדשים. גבו את seen_video_ids.json יחד עם ה-CSV או השתמשו במסד נתונים קבוע.

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

התוצאה

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

אֲנָשִׁים

עדיין לא רשומים אנשים עבור מאמר זה.

המשיכו לקרואכיצד לזהות שאלות חוזרות על מוצר ב-TikTok
קרא את המאמר הבא

הפכו את מה שקראתם לאינטגרציה עובדת

גלו את ממשקי ה-API לנתונים חברתיים של jsonscraper, בדקו בקשות ובנו את תהליך העבודה הבא.

גלה API