كيف لا تفقد نتائج بحث TikTok عند تحليل JSON

عند البحث عن مقاطع فيديو في TikTok عبر واجهة API، قد لا تظهر المقاطع في المصفوفة التي يتوقع معالج البيانات العثور عليها أولًا. ففي استجابة jsonscraper التي جرى التحقق منها للمسار `\u002FsearchVideo`، كان الحقل `aweme_list` فارغًا، بينما وُجدت عناصر بيانات الفيديو في `search_item_list[].aweme_info`. إذا كان البرنامج يقرأ `aweme_list` وحدها، فسيحفظ صفرًا من المقاطع، مع أن الاستجابة تتضمن مقاطع عُثر عليها. وهذه مشكلة موثوقية محددة للمطوّر: استخراج البيانات من كلا الموضعين وتوحيدها في قائمة واحدة قبل حفظها في قاعدة بيانات أو إرسالها إلى تقرير.

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

لماذا قد يعيد المحلّل قائمة فارغة

يبحث المسار `GET https://tiktok.evelode.com/searchVideo` عن مقاطع الفيديو باستخدام المعامل الإلزامي `keyword`. كما يسرد التوثيق المعاملات `cursor` و`count` و`cache_timeout` و`date_posted` و`sort_by` و`region`. وفي مخطط الاستجابة التي رُصدت، يحتوي الكائن الأعلى مستوى على `status` وكائن متداخل هو `tiktok`؛ وداخله توجد الحقول `cursor` و`has_more` و`status_code` و`aweme_list` و`search_item_list`.

في الحالة المحددة التي رُصدت لطلب يتضمن كلمة مفتاحية و`count=3`، كانت مصفوفة `aweme_list` فارغة. وفي المقابل، اشتملت `search_item_list` على عناصر توجد فيها معلومات الفيديو ضمن `aweme_info`. وقد تتضمن هذه الكائنات معرّف الفيديو والوصف وعنوان URL للمنشور والمؤلف والإحصاءات، مثل عدد المشاهدات أو الإعجابات أو التعليقات. تعكس الحقول المذكورة المخطط الذي رُصد؛ ومع ذلك، ينبغي أن يتعامل المعالج مع القيم المفقودة.

الخلاصة العملية هي أن نجاح طلب HTTP ووجود مصفوفة غير فارغة في حقل واحد متوقع هما اختباران مختلفان. تحقّق أولًا من الحالة الخارجية ووجود `tiktok`، ثم اجمع مقاطع الفيديو من كل موضع موثق. ولأغراض التحليلات، احتفظ بالمعرّف والاستجابة الأصلية، كي تتمكن من تتبع كيفية استخراج سجل معين وتوحيده.

وحّد الاستجابة قبل حفظها في التخزين

من المفيد إنشاء حد فاصل بين واجهة API ونظامك، على هيئة دالة تتلقى الكائن المتداخل `tiktok` وتعيد عناصر موحدة. ينبغي لها معالجة كلتا المصفوفتين، وتجاهل العناصر الفارغة أو غير القاموسية، وإزالة تكرار الفيديو نفسه بحسب `aweme_id`. اترك العدادات فارغة عندما لا يعيدها المزوّد: فالصفر يعني قيمة مقاسة، بينما تشير `None` إلى غياب الحقل.

فيما يلي مثال مختصر لـ Python 3.8+. ينفّذ طلبًا واحدًا، ويتحقق من حالة النقل والحالة الأعلى مستوى، ويوحّد صيغتي النتائج، ثم يطبع الحقول المختارة. ويُقرأ المفتاح من متغير بيئة ولا يُطبع في السجل.

import os
import requests

BASE_URL = "https://tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

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

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

ثبّت الاعتمادية باستخدام الأمر python -m pip install requests، واضبط `JSONSCRAPER_TIKTOK_LICENSE_KEY` في بيئة التشغيل، واحفظ الملف مثلًا باسم `search_videos.py`. تطابق معاملات الطلب الأسماء الموثقة: `keyword` و`count` و`region`؛ ويُمرر `license_key` بوصفه معامل استعلام. يفترض الكود أن الاستجابة تتضمن `status: "ok"` كما في المثال المسجل. فإذا أعادت واجهة API حالة أخرى، تتوقف المعالجة قبل تمرير بنية مشكوك فيها إلى المراحل التالية.

حوّل المثال إلى عملية جمع قابلة للتكرار

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

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

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

تحقّق من جودة البيانات، لا من نجاح الطلب فحسب

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

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

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

النتيجة: جدول موحد بدلًا من مقاطع الفيديو المفقودة

بعد التوحيد، يتلقى الكود اللاحق قائمة واحدة من مقاطع الفيديو، سواء أكان العنصر واردًا في `aweme_list` أم في `search_item_list[].aweme_info`. يتيح المعرّف إزالة التكرار، فيما تظل الحقول الاختيارية فارغة بوضوح. وهذا يقلل احتمال صدور تقارير فارغة بسبب قراءة مصفوفة واحدة فقط، ويجعل الخطوة التالية — التصدير أو التصفية أو التصنيف — أكثر قابلية للتوقع.

يمكن بدء التحقق من صفحة TikTok Scraper API، التي تعرض نقطة API الأساسية وتتيح الانتقال إلى العرض التجريبي. استخدم التوثيق الرسمي للتكامل، واختبر المعالجة أولًا على عدد صغير من العناصر؛ ثم زد `count` وواصل النتائج باستخدام المؤشر الموثق عند الحاجة. وستحصل بذلك على طبقة بيانات منظمة لمهامك، لا على افتراض بأنك غطيت TikTok بالكامل.