مراقبة وسوم TikTok باستخدام Python: طلب عملي إلى واجهة API

يلحظ فريق التسويق ظهور مقاطع فيديو عن منتج جديد على TikTok، لكن التحقق اليدوي من عدة وسوم كل يوم أمر صعب. ولمقارنة المنشورات والمؤشرات الظاهرة بمرور الوقت، يلزم جمع البيانات بطريقة قابلة للتكرار، مع طابع زمني وأرشيف للاستجابات الأصلية والتحقق من التغييرات.

يصلح لهذا النموذج الأولي استخدام TikTok Scraper API من jsonscraper؛ إذ تسرد صفحة المنتج مسارات للوسوم والمستخدمين ومقاطع الفيديو والبحث. تتمثل الخطوة الأولى في التحقق من المسار المطلوب وتنسيق الاستجابة في Postman، ثم نقل الإعدادات التي جرى التحقق منها إلى Python. وبهذا يمكن بناء عملية قابلة للتكرار، واستخراج الحقول الموجودة فعلًا في الاستجابة فقط.

المهمة: رصد التغيّر بمرور الوقت، لا مقطعًا رائجًا واحدًا

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

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

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

ما الذي تؤكده وثائق API

تذكر صفحة TikTok Scraper API العنوان الأساسي https://tiktok.evelode.com، وتسرد مسارات فئة Hashtag: GET /getHashtagInfo وGET /getHashtagFeed وGET /getHashtagFeedByID. كما تعرض الصفحة مثالًا على طلب إلى مسار آخر يتضمن المعلمة license_key، وتشرح إعداد المفتاح في مجموعة Postman.

بالنسبة إلى GET /getHashtagFeed، تحدد مواصفات المسارات الرسمية المعلمة الإلزامية query (عنوان URL للوسم أو اسم الوسم)، إلى جانب المعلمات الاختيارية cursor وcount وregion وcache_timeout. يُتوقع أن تحتوي استجابة الموجز على المصفوفة tiktok.aweme_list؛ ومن الحقول المذكورة لكل عنصر aweme_id وdesc وcreate_time وshare_url وبيانات المؤلف وstatistics. قد لا تتوفر بعض الحقول، لذا تحقّق من ملف JSON الفعلي قبل معالجته.

تتيح مجموعة jsonscraper في Postman تنفيذ طلب تجريبي ومراجعة الاستجابة الفعلية والحصول على مثال للاختبار اللاحق للكود. تُمرر قيمة license_key للمصادقة؛ احفظ المفتاح في متغير بيئة ولا تُدرجه في السجلات.

تحقّق من الطلب أولًا في Postman

ابدأ بوسم واحد للاختبار. اختر مسار موجز الوسم في المجموعة، واضبط license_key بالطريقة المحددة في الوثائق، وأرسل اسم الوسم في query. أضف count ورمز الدولة في region عند الحاجة. نفّذ الطلب، ثم تحقّق من حالة HTTP، والحقل الأعلى مستوى status، ومحتوى tiktok.aweme_list.

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

احفظ مفتاح API في متغير بيئة بدلًا من وضعه في الملف المصدري. وإذا أُرسل المفتاح في عنوان URL، فاحجبه عند تسجيل الطلب كيلا يظهر العنوان الكامل في السجلات.

عميل Python للطلب والأرشفة

يتوافق المسار وأسماء المعلمات أدناه مع المواصفات المنشورة: تُستخدم query للوسم، وتُمرر قيمة license_key للمصادقة. المثال متوافق مع Python 3.8+ ويحفظ الاستجابة الأصلية مع بيانات التشغيل الوصفية.

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

import requests

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


def fetch_hashtag_feed(hashtag: str) -> dict:
    params = {
        "license_key": API_KEY,
        "query": hashtag,
        "count": 20,
    }
    response = requests.get(
        f"{BASE_URL}/getHashtagFeed",
        params=params,
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("status") != "ok":
        raise RuntimeError("API أعادت حالة تختلف عن ok")
    return payload


def archive_response(hashtag: str, payload: dict) -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_tag = hashtag.lstrip("#").replace("/", "_")
    output_dir = Path("data/raw") / safe_tag
    output_dir.mkdir(parents=True, exist_ok=True)

    filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
    file_path = output_dir / filename
    file_path.write_text(
        json.dumps(
            {
                "hashtag": hashtag,
                "collected_at": collected_at,
                "response": payload,
            },
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return file_path


if __name__ == "__main__":
    tag = "#وسم_تجريبي"
    payload = fetch_hashtag_feed(tag)
    saved_path = archive_response(tag, payload)
    print(f"حُفظ الأرشيف: {saved_path}")

قبل التشغيل، عيّن متغير البيئة JSONSCRAPER_TIKTOK_LICENSE_KEY. يستخدم الطلب المعلمة المؤكدة query، ويحدّ عدد العناصر المطلوبة عبر count. وتُفحص حالة HTTP وحالة JSON، فيما يحفظ الأرشيف البيانات الفعلية للمعالجة اللاحقة. اختبر التشغيل على وسم واحد قبل إضافة الجدولة والتحليلات.

إضافة التطبيع من دون افتراضات هشة

تحدد الوثائق أن استجابة الموجز تتضمن المصفوفة tiktok.aweme_list. تحقّق قبل التحويل من أن tiktok كائن وأن aweme_list قائمة. واستخرج من كل عنصر الحقول المؤكدة فقط، مثل aweme_id وdesc وcreate_time وshare_url والقيم من statistics إن وُجدت.

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

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

المقاييس المستندة إلى الملاحظات المتكررة

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

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

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

الجدولة ومعالجة الأخطاء

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

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

تدعم المواصفات ترقيم صفحات موجز الوسم باستخدام المعلمة cursor. إذا احتجت إليه، فاحفظ المؤشر من الاستجابة وأرسله في الطلب التالي دون تحويل؛ وعالج النتائج التي أُعيدت فقط، وراقب has_more إن وُجد. وإذا أعادت الطلبات الخاصة بعدة وسوم المنشور نفسه، فاختر مفتاح إزالة التكرار بما يناسب المهمة: إما احتساب المنشور لكل وسم على حدة، أو احتساب مقاطع الفيديو الفريدة فقط.

التصنيف وأتمتة التقارير

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

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

وفي سيناريو بلا كود، يمكن ربط الخطوات نفسها في أداة أتمتة: الجدولة، وطلب HTTP وفق إعداد تم التحقق منه، وفحص الاستجابة، وحفظ JSON، وتحويل الحقول المؤكدة، والإشعار بالأخطاء. تحقّق أولًا من واجهة الطلب في Postman، ثم انقلها إلى Python أو n8n أو Make.

النتيجة المتوقعة والخطوة التالية

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

ابدأ بمسار واحد واستجابة فعلية واحدة: نفّذ طلب /getHashtagFeed باستخدام المعلمة query، واحفظ JSON، ثم أضف تحليل الحقول والجدولة. تعرض صفحة TikTok Scraper API العنوان الأساسي وخريطة المسارات، بينما تتضمن مواصفات المسارات أسماء المعلمات اللازمة لتنفيذ العميل.