واجهة TikTok Scraper API: كيفية جلب بيانات الفيديو بصيغة JSON باستخدام jsonscraper

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

تعرض صفحة TikTok Scraper API من jsonscraper مسارات للفيديوهات والمستخدمين والبحث والوسوم والموسيقى وأنواع أخرى من البيانات. سنستعرض أدناه الطلب الموثق getVideoByID وطرق معالجة استجابته بأمان. تستند الأمثلة إلى مواد المورّد؛ تحقّق منها باستخدام مفتاح ساري المفعول والوثائق الحالية قبل الاستخدام.

الطلب الأول: جلب معلومات الفيديو

تحدد وثائق getVideoByID في Postman طريقة GET ومعامل video_id. كما يعرض المثال region وcache_timeout. العنوان الأساسي المنشور على صفحة الخدمة هو https://tiktok.evelode.com.

مثال على الطلب باستخدام cURL:

export JSONSCRAPER_LICENSE_KEY="ваш_ключ"

curl --get "https://tiktok.evelode.com/getVideoByID" \
  --data-urlencode "video_id=7106855913906081070" \
  --data-urlencode "license_key=$JSONSCRAPER_LICENSE_KEY" \
  --data-urlencode "region=US"

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

تصف Postman قيمة region بأنها رمز المنطقة، وتشير إلى US كقيمة افتراضية. وبالنسبة إلى cache_timeout، تذكر الوثائق أن مدة التخزين المؤقت الافتراضية هي 3600 ثانية، وأن القيمة 0 تعطل التخزين المؤقت. إذا احتاج سيناريو عملك إلى هذا المعامل، فيمكنك تمريره صراحةً:

curl --get "https://tiktok.evelode.com/getVideoByID" \
  --data-urlencode "video_id=7106855913906081070" \
  --data-urlencode "license_key=$JSONSCRAPER_LICENSE_KEY" \
  --data-urlencode "region=US" \
  --data-urlencode "cache_timeout=0"

هذا تكييف للمعاملات المنشورة لهذا المسار، وليس ضمانًا بأن تكون بنية جميع الاستجابات متطابقة أو بأن تعطيل التخزين المؤقت مناسب لكل مهمة. قبل التنفيذ، راجع إعدادات المصادقة والمعاملات في المجموعة الحالية: قد تمرر Postman المفتاح عبر إعداد API Key، بينما يعرض مثال cURL أعلاه المفتاح كمعامل في عنوان URL.

الطلب نفسه باستخدام Python

فيما يلي طريقة باستخدام مكتبة Python القياسية. تنشئ طلب GET، وتمرر المعاملات، وتعالج أخطاء الشبكة وHTTP وJSON غير الصالح.

import json
import os
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

base_url = "https://tiktok.evelode.com/getVideoByID"
license_key = os.environ.get("JSONSCRAPER_LICENSE_KEY")

if not license_key:
    raise RuntimeError("Задайте переменную JSONSCRAPER_LICENSE_KEY")

params = {
    "video_id": "7106855913906081070",
    "license_key": license_key,
    "region": "US",
}

url = f"{base_url}?{urlencode(params)}"
request = Request(url, method="GET")

try:
    with urlopen(request, timeout=30) as response:
        status_code = response.status
        payload = json.loads(response.read().decode("utf-8"))
except HTTPError as error:
    print(f"HTTP-ошибка: {error.code}")
    raise
except URLError as error:
    print(f"Сетевая ошибка: {error.reason}")
    raise
except json.JSONDecodeError:
    raise RuntimeError("Ответ сервиса не удалось разобрать как JSON")

print("HTTP-статус:", status_code)
print("Верхнеуровневые ключи:", list(payload.keys()))

هذا تكييف للطلب الموثق، وليس مثالًا اختبره المورّد بصورة مستقلة لـPython. كما أنه لا يغطي جميع استجابات الخدمة المحتملة. وبما أن المفتاح يُمرر في عنوان URL، فلا تطبع عنوان URL كاملًا في السجلات؛ فقد يتضمن سرًا.

كيفية التحقق من استجابة JSON

تتضمن الاستجابة المنشورة في Postman الحقل status والكائن المتداخل tiktok.aweme_detail الذي يحتوي على بيانات الفيديو وصاحبه. هذا مثال على شكل استجابة واحدة، وليس ضمانًا لثبات المخطط. يمكنك الاطلاع عليه في مثال استجابة getVideoByID.

عند قراءة الحقول المتداخلة، تحقّق من كل مستوى:

def get_video_details(payload):
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        return None

    details = tiktok.get("aweme_detail")
    if not isinstance(details, dict):
        return None

    return details

details = get_video_details(payload)

if details is None:
    print("В ответе нет ожидаемого объекта с данными видео")
else:
    video_id = details.get("id")
    description = details.get("desc")
    author = details.get("author")

    print("ID:", video_id)
    print("Описание:", description)
    print("Автор:", author)

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

من المفيد الفصل بين ثلاثة أنواع من التحقق:

1. النقل: هل وصل رد HTTP، وما حالته؟
2. التنسيق: هل أمكن تحليل نص الاستجابة بوصفه JSON؟
3. المحتوى: هل تتوفر البيانات التي يحتاجها التطبيق؟

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

من طلب واحد إلى مسار معالجة عملي

يكفي في النموذج الأولي إرسال الطلب وعرض بعض القيم. أما المعالجة المنتظمة، فقسّمها إلى مراحل:

الطلب ← التحقق ← التطبيع ← إزالة التكرار ← التخزين.

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

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

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

التخزين المؤقت والمنطقة

في وصف المسار getVideoByID، يحدد المعامل cache_timeout مدة التخزين المؤقت بالثواني: القيمة الافتراضية المذكورة هي 3600 ثانية، وتعطّل القيمة 0 التخزين المؤقت. ويُوصف المعامل region بأنه رمز البلد؛ وتورد الوثائق US مثالًا. قبل التنفيذ، راجع هذه المعلومات في وثائق الطلب الحالية في Postman.

وجود إعداد للتخزين المؤقت لا يؤكد حداثة استجابة بعينها. إذا كانت حداثة البيانات مهمة، فتحقّق من نتائج الطلبات المتكررة باستخدام بيانات سيناريوك واختر السلوك المناسب.

مهام أخرى يمكنك استكشافها

تسرد صفحة المنتج مسارات للبحث عن الفيديوهات والمستخدمين والوسوم والمواقع والموسيقى والاتجاهات. ومن الأمثلة searchVideo وsearchHashtag وgetUserFeed وgetTrendingFeed. هذه خريطة المسارات التي نشرها المورّد، وليست تحققًا مستقلًا من كل مسار. راجع معاملات كل مسار وشكل استجابته في وثائقه الخاصة؛ فلا يمكن نقلها تلقائيًا من مثال getVideoByID.

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

ما ينبغي التحقق منه قبل الاستخدام في التطبيق

قبل إدراج الطلب في عملية منتظمة، اختبره باستخدام الفيديو والمعاملات التي يحتاج إليها المشروع:

• هل ينجح الطلب باستخدام مفتاح ساري المفعول ومعرّف صحيح؟
• كيف يتعامل التطبيق مع معامل غير صحيح أو مفقود؟
• ماذا يحدث إذا كان JSON صالحًا لكن الحقل المطلوب غير موجود؟
• كيف تُعالج أخطاء HTTP وفشل الشبكة وانتهاء المهلة؟
• ما الحقول المناسبة للتعريف وإزالة التكرار في مهمتك تحديدًا؟
• كيف تتغير نتيجة الطلب المتكرر مع قيم مختلفة لـcache_timeout، إذا كنت تستخدم هذا المعامل؟

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

ابدأ بسيناريو واحد قابل لإعادة الإنتاج

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

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