TikTok: حوّل نتائج البحث إلى قائمة أسبوعية بموضوعات الدعم

يحتاج فريق الدعم إلى قائمة بمقاطع TikTok العامة التي يناقش فيها الأشخاص ميزة غير واضحة أو يطرحون أسئلة عن منتج. يصعب تكرار البحث اليدوي بالطريقة نفسها، وقد تخزن استجابات واجهة برمجة التطبيقات الخاصة بالبحث مقاطع الفيديو في مواضع مختلفة من JSON. فيما يلي برنامج Python بسيط يطلب النتائج باستخدام كلمات مفتاحية، ويدمج بنيتي الاستجابة، ويحذف التكرارات بحسب المعرّف، ويحفظ السجلات التي يعثر عليها في ملف CSV.

ما النتيجة التي سيقدمها البرنامج؟

ستحصل في النهاية على جدول يتضمن معرّف الفيديو ورابطه ووصفه ووقت نشره واسم صاحبه، إلى جانب عدادات التفاعل المتاحة. ويمكن لفريقي الدعم أو التسويق أن يحددا يدويًا الموضوعات التي تتطلب إجابة أو تحديثًا للتعليمات أو تحققًا في نظام إدارة علاقات العملاء الخاص بهما. يعكس الجدول نتائج واجهة برمجة التطبيقات التي أُعيدت للاستعلامات المحددة فحسب؛ لذا اعتبره عينة عمل للمراجعة، لا دليلًا شاملًا على جميع النقاشات.

يعالج البرنامج مهمة الجمع والفرز الأولي. لكنه لا يحدد تلقائيًا ما إذا كان الوصف سؤالًا أو شكوى أو مزحة؛ ومن الأفضل إضافة هذا التصنيف بعد مراجعة يدوية، أو باستخدام مصنّف منفصل مع تسجيل النص الأصلي وسبب القرار.

ما الذي ينبغي طلبه وكيف تبدو الاستجابة؟

توثّق 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 وتوثيق مسار البحث.