TikTok: הפכו תוצאות חיפוש לרשימת נושאים שבועית לתמיכה

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

מה הסקריפט יפיק

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

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

מה לחפש וכיצד בנויה התגובה

לצורך חיפוש סרטונים, jsonscraper מתעדת את נתיב GET /searchVideo במארח https://tiktok.evelode.com. הפרמטר הנדרש הוא keyword; אפשר להעביר גם count, אזור, מיון, תקופת פרסום וסמן לעמוד הבא. למשל, אפשר לחזור על החיפוש באמצעות כמה ביטויים שנקבעו מראש: שם התכונה, ניסוח נפוץ של הודעת שגיאה ושאלה קצרה על הגדרה. הפרמטרים והערכים המותרים שלהם מפורטים במדריך TikTok API.

לחיפוש יש מאפיין חשוב עבור המנתח: המערך aweme_list עשוי להיות ריק, בעוד שהאובייקטים שנמצאו מופיעים ב-search_item_list, ובתוך כל פריט נמצא aweme_info. לכן המטפל שלהלן בודק את שתי הצורות. דוגמת התגובה והשדות שנצפו בבדיקה ב-25 באוקטובר 2026 מופיעים במפרט הראשי של jsonscraper; ייתכן ששדות הסטטיסטיקה לא יופיעו, ולכן הקוד אינו ממציא ערכים.

הכינו מפתח ורשימת שאילתות

שמרו את המפתח במשתנה הסביבה JSONSCRAPER_TIKTOK_LICENSE_KEY, ולא בקובץ המקור. במעטפת פקודות של Linux או macOS אפשר לעשות זאת כך:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="ваш_ключ"

התקינו את ספריית הבקשות והכינו קובץ queries.txt עם ביטוי חיפוש אחד בכל שורה, למשל название продукта настройка ו-название функции не работает. בחרו ניסוחים בהתאם לשפת קהל היעד ושמרו אותם ברשימה נפרדת, כדי שהייצואים השבועיים ישוו את אותן שאילתות.

python -m pip install requests

אספו ונרמלו את הסרטונים שנמצאו

הדוגמה תואמת ל-Python 3.8 ומעלה. היא שולחת בקשה אחת לכל ביטוי עם מגבלת תוצאות, בודקת שגיאות HTTP ואת סטטוס התגובה העליון, ואז שומרת רק שדות שקיימים בפועל. התאמות כפולות מאוחדות לפי aweme_id, וכל השאילתות שבהן נמצא הסרטון נרשמות בשדה keywords. השדה הנפרד collected_at_utc מתעד את מועד קבלת הנתונים כדי לאפשר השוואה להפעלות הבאות.

import csv
import os
import sys
from datetime import datetime, timezone

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("Установите JSONSCRAPER_TIKTOK_LICENSE_KEY")


def get_items(tiktok):
    """Извлекает видео из обеих документированных форм ответа поиска."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("Неуспешный статус API для запроса:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": author.get("unique_id") or author.get("nickname"),
                "play_count": stats.get("play_count"),
                "digg_count": stats.get("digg_count"),
                "comment_count": stats.get("comment_count"),
                "share_count": stats.get("share_count"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Сохранено найденных уникальных роликов:", len(videos))

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

כיצד לקרוא את קובץ ה-CSV בלי להסיק מסקנות שגויות

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

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

תזמנו את האיסוף

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

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

מגבלות מעשיות

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

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