يكون التقرير الأسبوعي للبحث في TikTok مفيدًا حين يبيّن مقاطع الفيديو التي ظهرت في العينة الجديدة منذ التشغيل السابق. يكفي لذلك حفظ معرّفات المقاطع التي سبق رصدها وإضافة النتائج الجديدة إلى ملف CSV. فيما يلي سكربت Python قابل لإعادة التنفيذ باستخدام TikTok Scraper API: يطلب مقاطع الفيديو وفق كلمة مفتاحية، ويعالج شكلي الاستجابة الموثّقين، ويحفظ قاعدة محلية للمعرّفات.
المهمة: رصد السجلات الجديدة بدل مراجعة نتائج البحث كلها
قد يحتاج فريق دعم أو باحث سوق أو محلل محتوى إلى عينة دورية من مقاطع الفيديو العامة التي تطابق استعلامًا عن منتج. إذا صُدّرت النتائج كاملة في كل مرة، فستجعل المقاطع المتكررة مراجعتها أصعب، وقد تضيع السجلات الجديدة بين ما سبق التعامل معه. يتيح سجل المعرّفات مقارنة نتائج كل تشغيل: يحتوي ملف CSV على مقاطع الفيديو الجديدة على هذه العملية والحقول الأساسية التي وردت في الاستجابة.
يجيب هذا السجل عن سؤال محدود لكنه عملي: ما العناصر التي ظهرت في استجابة التشغيل الحالي ولم تكن موجودة في مجموعة المعرّفات المحفوظة؟ وهذا مفيد لإنشاء قائمة انتظار للمراجعة اليدوية أو لنقل البيانات إلى جدول أو إلى تحليل لاحق. تعكس العينة نتائج API للاستعلام المحدد؛ ولا تمثل بحد ذاتها جميع منشورات TikTok.
ما الذي تحتاج إلى إعداده
- Python 3.8 أو إصدار أحدث.
- إمكانية الوصول إلى TikTok Scraper API ومفتاح ترخيص.
- استعلام يمكن تكراره من دون تغيير معناه، مثل اسم منتج أو عبارة محددة.
احفظ المفتاح في متغير البيئة JSONSCRAPER_TIKTOK_LICENSE_KEY بدلًا من وضعه في ملف السكربت. في المثال أدناه، يُمرَّر المفتاح بوصفه معلمة الطلب license_key وفق مخطط API. لا تطبعه في سجل التنفيذ.
export JSONSCRAPER_TIKTOK_LICENSE_KEY="مفتاحك"
python -m pip install requests
في Windows PowerShell، يمكن تعيين المتغير للجلسة الحالية بهذه الطريقة: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="مفتاحك". لا تضف أسرارًا حقيقية إلى Git أو إلى ملف CSV مشترك.
التكامل: إجراء البحث وتوحيد بنية JSON
تصف الوثائق مسار GET /searchVideo للبحث عن مقاطع الفيديو، مع المعلمة الإلزامية keyword. ويمكن أيضًا تحديد count والمنطقة والترتيب والمرشح الزمني والمؤشر للتنقل بين النتائج. يستخدم هذا المثال المبسط الكلمة المفتاحية وعدد العناصر المطلوبة ومنطقة الولايات المتحدة فقط. يسرد مرجع مسارات TikTok API أسماء المعلمات بدقة.
تتطلب بنية استجابة البحث انتباهًا خاصًا: قد تكون مصفوفة aweme_list فارغة، وقد توجد عناصر الفيديو في search_item_list مع تضمين البيانات في aweme_info. لذلك يتحقق الكود من المسارين، ثم يجمع العناصر ويزيل التكرار باستخدام aweme_id. وهذا يمنع أن تتحول استجابة JSON التي عولجت بنجاح، عن طريق الخطأ، إلى تقرير فارغ.
import csv
import json
import os
from pathlib import Path
from datetime import datetime, timezone
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "اسم المنتج"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise RuntimeError("عيّن JSONSCRAPER_TIKTOK_LICENSE_KEY")
response = requests.get(
BASE_URL,
params={
"license_key": license_key,
"keyword": KEYWORD,
"count": COUNT,
"region": REGION,
},
timeout=60,
)
response.raise_for_status()
data = response.json()
# يتضمن مثال الاستجابة status خارجيًا وكائنًا متداخلًا باسم tiktok.
if "status" in data and data["status"] != "ok":
raise RuntimeError("أعادت API حالة غير ok")
tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info")
if isinstance(info, dict):
items.append(info)
# عناصر فريدة من الاستجابة الحالية مع الحفاظ على الترتيب.
current = {}
for item in items:
video_id = item.get("aweme_id")
if video_id:
current[str(video_id)] = item
if STATE_FILE.exists():
seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
seen = set()
new_items = [(video_id, item) for video_id, item in current.items()
if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()
fields = ["collected_at_utc", "query", "aweme_id", "created_at",
"author", "description", "share_url", "play_count",
"digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fields)
if write_header:
writer.writeheader()
for video_id, item in new_items:
author = item.get("author") or {}
stats = item.get("statistics") or {}
writer.writerow({
"collected_at_utc": run_time,
"query": KEYWORD,
"aweme_id": video_id,
"created_at": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"description": item.get("desc"),
"share_url": item.get("share_url"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
})
seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"مقاطع الفيديو الفريدة في الاستجابة: {len(current)}؛ الجديدة: {len(new_items)}")
يكتب السكربت الخلايا فارغة للقيم غير الموجودة في JSON؛ فقد تغيب بعض الحقول والمقاييس عن سجل بعينه. لا يستبدل الكود القيم المفقودة بصفر، ولا يتعامل مع الصفر بوصفه قيمة مفقودة. ويُسجَّل وقت الجمع منفصلًا عن وقت النشر الذي تعيده API في الحقل create_time.
كيف تعمل مقارنة التغييرات
- يعيد الطلب صفحة نتائج بحث للكلمة المفتاحية المحددة.
- يجمع موحِّد البيانات السجلات من
aweme_listوsearch_item_list[].aweme_info. - يزيل السكربت التكرارات داخل الاستجابة باستخدام معرّف المقطع.
- تُقارن المعرّفات بسجل JSON المحلي.
- تُضاف المعرّفات الجديدة إلى CSV، ثم تُحفظ المجموعة الكاملة التي رُصدت لاستخدامها في التشغيل التالي.


يساعد تصوير هذه العملية عند تسليم السكربت إلى الزملاء: CSV سجل إضافي، أما JSON فيحفظ حالة إزالة التكرار. ويمكن تخزينهما منفصلين عن الكود وإنشاء نسخة احتياطية منهما معًا. وللتشغيل ضمن فريق أو في السحابة، استبدل ملف JSON المحلي بمخزن دائم مناسب، ونفّذ تحديثًا ذريًا للحالة حتى لا تتسبب عمليات التشغيل المتزامنة في استبدال بعضها بعضًا.
إعادة التشغيل وترقيم الصفحات
كرّر التشغيل وفق جدول زمني باستخدام مجدول نظام التشغيل أو مهمة CI أو سير عمل آلي. لا تغيّر الكلمة المفتاحية من دون تسجيل نسختها: فالاستعلامات المختلفة تنتج عينات مختلفة، وخلطها في سجل واحد يصعّب تفسير النتائج. يستخدم السكربت المعروض استعلامًا واحدًا للتبسيط؛ ويمكن معالجة قائمة استعلامات بحلقة، مع حفظ الحقل query لكل صف.
تدعم API المعلمة cursor للتنقل بين نتائج البحث. إذا أضفت ترقيم الصفحات، مرّر المؤشر الوارد في الاستجابة السابقة، وخزّنه بوصفه قيمة غير شفافة، وأوقف التصفح عندما لا تعود هناك حاجة إلى صفحات إضافية. تحدد count عدد العناصر المطلوبة، لكن ينبغي تحديد العدد الفعلي للسجلات من الاستجابة. وحتى عند جلب عدة صفحات، تظل هذه صفحات نتائج البحث المسترجعة، وليست ضمانًا لتغطية المنصة بالكامل.
لا يتضمن السيناريو الحالي عمدًا تصنيفًا آليًا للنص أو استنتاجًا بوجود «اتجاه رائج». يساعد CSV على تحديد السجلات الجديدة التي عُثر عليها بسرعة؛ ويمكن للمحلل بعد ذلك تصنيفها بحسب الموضوع أو القصد أو نوع السؤال، ومراجعة أمثلة يدويًا. وإذا ربطت نموذجًا لغويًا، فأرسل إليه الحقول النصية اللازمة فقط، واطلب منه إرجاع الفئات مع المعرّف الأصلي كي يمكن التحقق من النتيجة وربطها بالسجل.
الفحوص والأخطاء الشائعة
- خطأ HTTP. يوقف
raise_for_status()التنفيذ عند رمز HTTP خارج النطاق الناجح. تحقّق من توفر API والمعلمات والحساب قبل تحديث ملف الحالة. - حالة API ليست
ok. يوقف السكربت التنفيذ قبل تسجيل النتائج إذا احتوت الاستجابة على الحقل العلويstatusبقيمة أخرى. يحافظ ذلك على السجل السابق ويساعد على عدم تفسير استجابة معطوبة على أنها نتيجة بحث فارغة. - قائمة فارغة في
aweme_list. تحقّق أيضًا منsearch_item_list؛ فالكود يأخذ البنيتين في الحسبان. - تكرار مقاطع الفيديو بين عمليات التشغيل. هذا متوقع عند تداخل صفحات نتائج البحث؛ ولن تظهر المقاطع مجددًا في التقرير إذا كان معرّفها محفوظًا بالفعل.
- مقياس غير متوفر. تبقى الخلية فارغة. عند إجراء الحسابات، ميّز القيم المفقودة عن الأصفار الفعلية.
- فقدان الحالة. سيعدّ السكربت جميع المعرّفات التي تعود بها API جديدة. أنشئ نسخة احتياطية من
seen_video_ids.jsonمع CSV أو استخدم قاعدة بيانات دائمة.
عند التشغيل الآلي، احفظ معلومات التشخيص من دون المفتاح: وقت التشغيل، ورمز HTTP، وحالة API، وعدد السجلات التي عولجت، وعدد المعرّفات الجديدة. فهذا يساعد على التمييز بين عدم ظهور مقاطع فيديو جديدة وفشل الطلب. ويمكن أرشفة الاستجابة الكاملة الأصلية على نحو منفصل إذا لزم التحقق لاحقًا من المخطط؛ مع تقييد الوصول ومدة الاحتفاظ وفق احتياجات الفريق.
النتيجة
بعد التشغيل، سيكون لديك ملف CSV يحوي مقاطع الفيديو ذات المعرّفات الجديدة على السجل، مع الأوصاف والروابط والحقول العامة المتاحة، إضافة إلى حالة JSON للمقارنة عند التشغيل التالي. وتناسب هذه النتيجة قائمة إدخال موجزة لفريق الدعم أو التحليل أو المحتوى. يمكنك الاطلاع على وصف API وخيارات الوصول في صفحة TikTok Scraper API؛ وتحقّق من معلمات البحث الدقيقة في مرجع المسارات الرسمي.