كيف تحلّل موضوعات صنّاع TikTok: مسار عمل عملي باستخدام Python

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

النهج العملي هو إعداد قائمة صغيرة من الحسابات العامة، وجلب معلومات فيديوهاتها بانتظام بصيغة منظّمة، وحفظ كل عملية جمع كلقطة مستقلة. بعد ذلك، يمكن مقارنة المنشورات والمقاييس المتاحة بمرور الوقت، واستخدام نموذج لغوي لتجميع الأوصاف مبدئيًا. فيما يلي مخطط لمسار عمل بحثي باستخدام Python وTikTok Scraper API من jsonscraper.

حدّد سؤال البحث قبل جمع البيانات

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

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

قبل توصيل API، دوّن بروتوكول البحث: قائمة الحسابات، وتاريخ البدء، ودورية الجمع، والحقول المراد تحليلها، ومعايير إدراج المنشورات. وسجّل وقت كل طلب، كي تتمكن من التمييز بين تغير مقياس فيديو واحد والاختلاف بين مجموعتين من المشاهدات.

ما الذي ينبغي جمعه واحتسابه

يتطلب المشروع الصغير ثلاث طبقات من البيانات. الأولى: معرّف الحساب ووقت بدء الجمع. والثانية: رد API الأصلي، المحفوظ للرجوع إليه والتحقق منه لاحقًا. والثالثة: حقول موحّدة للاستعلامات والتقارير، مثل معرّف الفيديو، والوصف، ووقت النشر، وعدّادات التفاعل المتاحة.

ينبغي تحديد أسماء الحقول وبنية الرد من عينة للمسار المحدد. لا تفترض مسبقًا أن القائمة تسمى دائمًا videos أو أن عداد المشاهدات هو views. نفّذ أولًا الطلب الموثق وافحص JSON الفعلي، ثم اضبط التحويل ليتوافق مع مخططك الخاص.

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

الاتصال بـ TikTok Scraper API

تذكر صفحة TikTok Scraper API العنوان الأساسي https://tiktok.evelode.com، ويؤكد مرجع المسارات المسار GET /getUserFeed ومعاملاته: query وmax_cursor وcount وregion وwith_pinned_posts وsort_type وcache_timeout. يكفي للطلب الأول تحديد الملف الشخصي في query، وعدد العناصر مثلًا عبر count. يُمرّر المفتاح license_key ضمن سلسلة الاستعلام؛ كما يشرح مرجع API كيفية ضبطه. ويمكنك مراجعة نقطة النهاية والتحقق من الرد قبل الدمج عبر مجموعة Postman.

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

طلب أساسي قابل للتشغيل باستخدام Python

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

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

import requests

API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
ENDPOINT_URL = "https://tiktok.evelode.com/getUserFeed"


def fetch_user_feed(handle: str, count: int = 20) -> dict:
    response = requests.get(
        ENDPOINT_URL,
        params={
            "license_key": API_KEY,
            "query": handle,
            "count": count,
            "region": "US",
        },
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if not isinstance(payload, dict):
        raise ValueError("Ожидался объект JSON")
    if payload.get("status") != "ok":
        raise RuntimeError(f"API вернул статус: {payload.get('status')!r}")
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise ValueError("В ответе отсутствует объект tiktok")
    return payload


def save_raw(payload: dict, account: str, output_dir: str = "data/raw") -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_account = "".join(c for c in account if c.isalnum() or c in "-_@")
    path = Path(output_dir) / f"{safe_account}_{collected_at.replace(':', '-')}.json"
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        json.dumps(
            {"collected_at": collected_at, "account": account, "payload": payload},
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return path


def normalize_items(payload: dict, account: str, collected_at: str) -> list:
    items = payload["tiktok"].get("aweme_list", [])
    if not isinstance(items, list):
        raise ValueError("Поле tiktok.aweme_list не является списком")

    observations = []
    for item in items:
        if not isinstance(item, dict):
            continue
        stats = item.get("statistics")
        stats = stats if isinstance(stats, dict) else {}
        author = item.get("author")
        author = author if isinstance(author, dict) else {}
        observations.append({
            "account_handle": account,
            "collected_at": collected_at,
            "video_id": item.get("aweme_id"),
            "caption": item.get("desc"),
            "published_at_epoch": item.get("create_time"),
            "author_handle": author.get("unique_id"),
            "views": stats.get("play_count"),
            "likes": stats.get("digg_count"),
            "comments": stats.get("comment_count"),
            "shares": stats.get("share_count"),
        })
    return observations


if __name__ == "__main__":
    account = "creator_handle"
    payload = fetch_user_feed(account, count=20)
    collected_at = datetime.now(timezone.utc).isoformat()
    raw_path = save_raw(payload, account)
    observations = normalize_items(payload, account, collected_at)
    print(f"Сохранено: {raw_path}; записей: {len(observations)}")

قبل التشغيل، عيّن JSONSCRAPER_TIKTOK_LICENSE_KEY في البيئة وثبّت مكتبة requests. يتحقق البرنامج من رد HTTP والحالة الخارجية ووجود كائن tiktok، ثم يقرأ aweme_list. ويحفظ JSON الخام ويستخرج الحقول التي يؤكدها المرجع، مع ترك القيم غير المتاحة فارغة. والخلاصة المستلمة هي مجموعة النتائج التي أعادها API، لذلك ينبغي ربط التقرير بوقت الطلب والملف الشخصي المحدد.

احفظ اللقطات وقارن المنشورات

يناسب SQLite أو PostgreSQL المشاريع الصغيرة. احفظ الرد الخام منفصلًا عن السجلات الموحّدة. ويمكن استخدام المخطط التالي لجدول المشاهدات:

CREATE TABLE IF NOT EXISTS video_observations (
    account_handle TEXT NOT NULL,
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    published_at_epoch INTEGER,
    caption TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    raw_file TEXT,
    PRIMARY KEY (account_handle, video_id, collected_at)
);

تضيف كل عملية تشغيل لقطة جديدة بدلًا من الكتابة فوق البيانات السابقة. وعند مقارنة العدادات، احسب الفرق فقط عند توفر القيمتين للفيديو نفسه. أدرج الفاصل الزمني بين الطلبات ووقت الرصد في التقرير، لتوضيح المدة التي تراكم خلالها التغير.

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

أضف نموذجًا لغويًا مع تصنيف قابل للتحقق

يمكن للنموذج أن يوزع الأوصاف مبدئيًا على موضوعات مثل «الوصفات» و«التدريبات» و«مراجعات المنتجات» و«القصص الشخصية». ابدأ بتصنيف بضع عشرات من المنشورات يدويًا. قارن التصنيفات الآلية بهذه العينات، ونقّح تعريفات الفئات، ثم أعد التقييم بعد تغيير التعليمات أو النموذج.

من الأوثق احتساب عدد المنشورات الجديدة ووسيط العدادات والفروق بين اللقطات باستخدام شيفرة عادية. استخدم النموذج لتصنيف النص وإعداد تفسيرات موجزة. وأبقِ الأوصاف الأصلية والمشاهدات الرقمية متاحة للتحقق.

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

أتمتة التشغيل

بعد التحقق من تشغيل يدوي، انقل البرنامج النصي إلى cron أو GitHub Actions أو n8n أو Make. يشغّل المجدول عملية الجمع وفق جدول زمني، ويمرر قائمة الحسابات، ويسجل النتيجة، ويوجه التقرير إلى مساحة التخزين المختارة. احتفظ بالمفتاح ضمن أسرار بيئة التنفيذ. اختبر العملية أولًا على حساب واحد، ثم وسّع القائمة.

قسّم الأتمتة إلى مراحل: قائمة انتظار الحسابات، واستدعاء API، وحفظ الرد الخام، والتوحيد، وتسجيل اللقطة، وإعداد التقرير. ينبغي ألا يؤدي تعطل حساب واحد إلى محو نتائج الحسابات الأخرى. ويمكن جعل إعادة التشغيل آمنة من التكرار باستخدام معرّف تشغيل وقيود التفرد في قاعدة البيانات.

سجّل الوقت والحساب والمسار وحالة HTTP والمدة وعدد العناصر المعالجة ووصف الخطأ. لا تسجّل مفتاح API. وقد أُدرج المعامل cache_timeout للمسار /getUserFeed؛ ويمكن إضافته إلى الطلب إذا كنت بحاجة إلى مدة تخزين مؤقت محددة. ويذكر مرجع API أن القيمة الافتراضية هي 3600 ثانية.

تحقق من الجودة قبل نشر التقرير

طابق عدة سجلات موحّدة مع JSON الخام. تحقق من أن الجمع المتكرر يتعرف على الفيديو نفسه عبر معرّفه، وأن التواريخ تُفسر بالشكل المتوقع، وأن الحقول الرقمية من النوع المناسب، وأن نسبة القيم المفقودة معروفة. ثم أعد التشغيل وتأكد من أن قاعدة البيانات احتفظت بالمشاهدات السابقة وأضافت الجديدة.

لا تخلط الحسابات أو فترات الجمع. عند مقارنة الموضوعات، استخدم فترات متساوية الطول أو اعرض طول الفترة بوضوح في التقرير. ولتتبع تغير العدادات، سجّل المدة بين اللقطات حتى يفهم القارئ نطاق الفترات التي يقارنها.

احتفظ بنص الوصف الأصلي وأنشئ نسخة منقّحة منفصلة. فقد تؤثر الرموز التعبيرية والوسوم والروابط والخصائص اللغوية في التصنيف؛ وتساعد الحقول المنفصلة على التحقق من أثر التنقيح وإعادة احتساب الفئات من دون استدعاء API مجددًا.

ما النتائج التي يتيحها مسار العمل؟

بعد عدة دورات، سيحصل الفريق على جدول للمنشورات واللقطات، وتجميع أولي للأوصاف حسب الموضوع، وتقرير عن الفيديوهات الجديدة خلال فترة محددة. ويساعد ذلك على اختيار مقاطع للمراجعة المتخصصة، ورصد الموضوعات المتكررة لدى الحسابات المختارة، والتحقق من تغير العدادات العامة بين مواعيد الرصد.

يمكن الاستناد إلى هذه البيانات لصياغة فرضيات للتقويم التحريري: قارن طرق تناول سؤال واحد، أو حدّد موضوعات لاختبارها في المحتوى الخاص بك. ولتقييم الأثر التجاري، قارِن المشاهدات ببيانات الحملات الداخلية.

للبدء، اختر قائمة صغيرة من الحسابات العامة، واختبر GET /getUserFeed في مجموعة طلبات Postman. لا تنقل إلى الشيفرة إلا المعاملات ومسارات الحقول التي تؤكدها وثائق المسار والرد الفعلي.

جمع البيانات العامة بمسؤولية

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

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

قائمة تحقق موجزة للبدء

1. حدّد المجال وقائمة الحسابات والفترة وأسئلة التحليل.
2. تحقق من معاملات GET /getUserFeed في المرجع ومن الرد الفعلي في Postman.
3. احفظ عينة JSON واضبط أداة التوحيد على الحقول المؤكدة.
4. سجّل الرد الخام واللقطات المنفصلة مع وقت الجمع.
5. احسب المقاييس الرقمية بالشيفرة، واستخدم الذكاء الاصطناعي للتجميع الأولي للنصوص.
6. أضف الجدولة والتسجيل ومعالجة التكرار ومدة الاحتفاظ.

بهذا تصبح المراقبة بحثًا قابلًا لإعادة الإنتاج: يرتبط كل استنتاج بمنشور ووقت رصد، وتستند الشيفرة إلى المخطط الفعلي للمسار المختار.