TikTok: كيف تتحقق من أن مراقبة البحث تعمل فعلاً؟

لا تضمن استجابة HTTP 200 أن مراقبة TikTok اليومية جمعت مقاطع فيديو. فقد تكون نتائج البحث في aweme_list أو في search_item_list[].aweme_info؛ ويمكن لبرنامج نصي لا يقرأ إلا المصفوفة الأولى أن ينتهي من دون خطأ ويسجّل تقريراً فارغاً. ويتحقق الفحص الموثوق على نحو منفصل من حالة النقل والحالة التطبيقية، ويستخرج كلا شكلي البنية المدعومين، ويسجّل عدد مقاطع الفيديو الفريدة التي استخرجها هذا التشغيل.

ما الذي ينبغي تشخيصه تحديداً؟

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

يقبل مسار البحث /searchVideo في TikTok Scraper API من jsonscraper المعلمة الإلزامية keyword ومعلمات إضافية هي count وcursor وdate_posted وsort_by وregion. وتشرح وثائق المسار ترقيم الصفحات باستخدام cursor؛ وينبغي تمريره كقيمة معتمة مأخوذة من الاستجابة السابقة. تحدد المعلمة count العدد المطلوب للنتائج، ولا تضمن تغطية المنشورات كلها.

قسّم الفحص إلى أربع إشارات

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

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

طلب أساسي وتطبيع باستخدام Python

تحدد مواصفات jsonscraper العنوان الأساسي https://tiktok.evelode.com، وإرسال المفتاح في معلمة الطلب license_key. يستخدم المثال أدناه المعلمات الموثقة؛ ويُقرأ المفتاح من متغير بيئة ولا يُطبع في السجل. ثبّت الاعتمادية بالأمر python -m pip install requests، ثم عيّن JSONSCRAPER_TIKTOK_LICENSE_KEY في البيئة.

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

import requests

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


def extract_videos(payload):
    """جمع مقاطع الفيديو من شكلي استجابة البحث المعروفين."""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

    for item in tiktok.get("search_item_list") or []:
        if isinstance(item, dict):
            aweme = item.get("aweme_info")
            if isinstance(aweme, dict):
                videos.append(aweme)

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "مثال على استعلام عن منتج",
        "count": 20,
        "region": "US",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("أعادت API حالة خارجية لا تساوي ok")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("كائن tiktok غير موجود في الاستجابة")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("status_code الداخلي لا يساوي قيمة النجاح 0")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

يفحص البرنامج النصي مستوى النقل عبر raise_for_status()، ثم يتحقق من الحالة الخارجية ووجود كائن tiktok وقيمة status_code الداخلية. بعد ذلك يستخرج السجلات من شكلي البحث، ويزيل تكرارها باستخدام aweme_id، ويحفظ لقطة تتضمن وقت الجمع. وإذا لم توجد سجلات مناسبة، فسيظل الملف يتضمن معلومات التشغيل، ما يتيح التمييز بين نتيجة فارغة محفوظة وتقرير غير موجود.

تحويل اللقطات إلى إشارة للفريق

شغّل البرنامج وفق جدول زمني باستخدام cron أو CI أو مجدول سير العمل. احتفظ بلقطات منفصلة لكل استعلام، أو أضف الكلمة المفتاحية إلى اسم الملف. ويكفي أن يسجل جدول الحالة وقت التشغيل والحالة وعدد السجلات المستخرجة والفريدة، إلى جانب العلامة has_more. ومن المفيد إرسال إشعار عند فشل الطلب باستثناء، أو غياب أجزاء إلزامية من الاستجابة، أو حدوث تغير حاد في عدد السجلات المستخرجة مقارنة بسجلّك السابق.

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

لترقيم الصفحات، استخدم cursor الوارد في الاستجابة وأوقف التصفح عندما تفيد API بعدم وجود نتائج أخرى. احفظ المؤشرات والمعلمات المستخدمة للطلب كي يتسنى إعادة تنفيذ التشغيل. وتتيح المعلمتان date_posted وsort_by تحديد مرشح زمني وطريقة ترتيب؛ وإذا كانت المهمة تتطلب مقارنات قابلة للتكرار، فثبّتهما بين عمليات التشغيل.

كيفية قراءة النتيجة

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

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

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