كيفية الحصول على مفتاح TMDB API والاستعلام من واجهة برمجة تطبيقات قاعدة بيانات الأفلام

قاعدة بيانات الأفلام (TMDB) هي فهرس مبني بواسطة المجتمع للأفلام والبرامج التلفزيونية والممثلين والأعمال الفنية. واجهة برمجتها (API) مجانية للاستخدام غير التجاري طالما أنك تنسب الفضل إلى TMDB، مما يجعلها نقطة البداية المعتادة في أي قائمة من واجهات برمجة تطبيقات الأفلام المجانية. الصعوبة تكمن في عملية الإعداد: تمنحك TMDB بيانات اعتماد مختلفة، ويفترض دليل البدء الرسمي أنك تعرف بالفعل أي منها تستخدم.

يغطي هذا الدليل المسار بأكمله: الحساب، طلب المفتاح، مفتاح v3 مقابل رمز الوصول للقراءة v4، أول استدعاءات للبحث والتفاصيل في curl و Python، نفس الاستدعاءات المحفوظة كاختبار في Apidog، بالإضافة إلى حدود المعدل وقواعد الإسناد والأخطاء التي ستواجهها في اليوم الأول.

ما تحتاجه قبل أن تبدأ

• حساب TMDB مع عنوان بريد إلكتروني تم التحقق منه. ترفض واجهة برمجة التطبيقات (API) الحسابات غير المؤكدة برمز 401.
• متصفح سطح مكتب. تشير وثائق TMDB إلى أن صفحات تسجيل API ليست محسّنة للأجهزة المحمولة.
• curl، أو Python 3 مع حزمة requests.
• Apidog، لتخزين الرمز بأمان والاحتفاظ بالطلبات. حمل Apidog لأنظمة macOS أو Windows أو Linux.

الخطوة 1: إنشاء حساب TMDB

اذهب إلى themoviedb.org، انقر على "Join TMDB" (انضم إلى TMDB)، واشترك باستخدام عنوان بريد إلكتروني. افتح رسالة التحقق الإلكترونية وأكدها قبل أن تلمس إعدادات API. إذا تخطيت هذه الخطوة، فستواجه رمز 401 محيرًا لاحقًا، رمز الحالة 32: "البريد الإلكتروني غير متحقق منه: لم يتم التحقق من عنوان بريدك الإلكتروني."

الخطوة 2: طلب مفتاح API

بمجرد تسجيل الدخول، افتح إعدادات حسابك وانقر على "API" في الشريط الجانبي الأيسر. يصف الأسئلة الشائعة لـ TMDB هذا بأنه المسار الوحيد: "يمكنك التقدم بطلب للحصول على مفتاح API بالنقر على رابط "API" من الشريط الجانبي الأيسر داخل صفحة إعدادات حسابك."

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

بعد الإرسال، تعرض نفس صفحة الإعدادات بيانات اعتماد اثنتين:

• مفتاح API، مخصص لمصادقة v3. سلسلة سداسية عشرية من 32 حرفًا.
• رمز الوصول للقراءة لـ API، وهو سلسلة أطول بكثير على غرار JWT.

لا تنشر TMDB جدولًا زمنيًا للمراجعة؛ عمليًا تظهر القيمتان بمجرد اكتمال النموذج. تعامل معهما كأي سر آخر واحرص على إبقائهما بعيدًا عن الالتزامات (commits) ونوافذ الدردشة ولقطات الشاشة.

مفتاح API v3 مقابل رمز الوصول للقراءة v4

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

توصية TMDB الخاصة هي رمز Bearer: "الطريقة الافتراضية للمصادقة هي باستخدام رمز الوصول الخاص بك"، وله "فائدة إضافية تتمثل في كونه عملية مصادقة واحدة يمكنك استخدامها عبر طريقتي v3 و v4."

استخدم ترويسة Bearer ما لم يكن عميلك لا يستطيع تعيين الترويسات. إبقاء بيانات الاعتماد خارج الرابط URL هو نفس الحجة وراء أي قرار لمفتاح API مقابل رمز Bearer: يتم تسجيل الروابط URL وتخزينها مؤقتًا ومشاركتها.

تمييز آخر. كل شيء في هذه المقالة هو بيانات كتالوج للقراءة فقط، والتي تحتاج فقط إلى بيانات اعتماد التطبيق. تضيف واجهة برمجة تطبيقات v4 ميزات الحساب مثل القوائم والمفضلات والتقييمات وقوائم المشاهدة. تتطلب الكتابة إليها لمستخدم TMDB عملية مصافحة إضافية: رمز طلب من /4/auth/request_token، موافقة المستخدم، ثم رمز وصول المستخدم من /4/auth/access_token. لا شيء من هذا ضروري للبحث عن الأفلام أو قراءة التفاصيل.

الخطوة 3: قم بأول طلب لك

جميع استدعاءات v3 تذهب إلى https://api.themoviedb.org/3. تغطي نقطتان نهائيتان معظم المشاريع الأولى: البحث بالعنوان، ثم جلب التفاصيل بالمعرف.

البحث عن فيلم باستخدام curl

curl --request GET \
  --url 'https://api.themoviedb.org/3/search/movie?query=fight%20club&include_adult=false&language=en-US&page=1' \
  --header 'Authorization: Bearer YOUR_READ_ACCESS_TOKEN' \
  --header 'accept: application/json'

الاستجابة هي كائن صفحة يحتوي على page و results و total_pages و total_results. يحمل كل نتيجة id و title و release_date و overview و poster_path و genre_ids و vote_average. في مثال البحث الخاص بـ TMDB، أول نتيجة لـ "fight club" هي المعرف 550، صدر في 15-10-1999.

يبدو نفس الاستدعاء بمفتاح v3 هكذا. لاحظ أنه لا توجد ترويسة مصادقة على الإطلاق:

curl 'https://api.themoviedb.org/3/search/movie?query=fight%20club&api_key=YOUR_API_KEY'

الحصول على تفاصيل الفيلم باستخدام Python

الآن، خذ المعرف من البحث واطلب السجل الكامل. تعيد نقطة نهاية تفاصيل الفيلم runtime و genres و budget و revenue و overview. تضيف معلمة append_to_response الخاصة بها موارد فرعية مثل الاعتمادات إلى نفس الرحلة، بحد أقصى 20 لكل طلب.

import os
import requests

TOKEN = os.environ["TMDB_READ_ACCESS_TOKEN"]
BASE = "https://api.themoviedb.org/3"
HEADERS = {"Authorization": f"Bearer {TOKEN}", "accept": "application/json"}


def search_movie(title):
    r = requests.get(
        f"{BASE}/search/movie",
        params={"query": title, "include_adult": "false", "language": "en-US"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()["results"]


def movie_details(movie_id):
    r = requests.get(
        f"{BASE}/movie/{movie_id}",
        params={"append_to_response": "credits"},
        headers=HEADERS,
        timeout=10,
    )
    r.raise_for_status()
    return r.json()


hit = search_movie("Fight Club")[0]
movie = movie_details(hit["id"])
print(movie["title"], movie["release_date"], f'{movie["runtime"]} min')
print("https://image.tmdb.org/t/p/w500" + movie["poster_path"])

السطر الأخير هو الجزء الذي يغفله الناس. poster_path هو مجرد مسار. كما يوضح دليل أساسيات الصور، فإن رابط URL يعمل هو https://image.tmdb.org/t/p/، ثم حجم مثل w500 أو original، ثم المسار. /3/configuration يسرد كل حجم صالح.

الخطوة 4: تشغيل وحفظ الطلبات في Apidog

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

1. أنشئ مشروعًا وأضف بيئة تسمى "TMDB" بمتغيرين: base_url مضبوط على https://api.themoviedb.org/3، و tmdb_token يحتوي على رمز الوصول للقراءة الخاص بك. ضع علامة على الرمز كسر بحيث يتم إخفاؤه في واجهة المستخدم ويُحفظ بعيدًا عن عمليات التصدير؛ يغطي دليل متغيرات البيئة والسرية الخيارات.
2. أضف طلب GET إلى {{base_url}}/search/movie مع معلمة query. في علامة تبويب المصادقة (Auth)، اختر Bearer Token وأدخل {{tmdb_token}}. أرسله وتأكد من حصولك على رمز 200 ومصفوفة results.
3. أضف طلب GET ثانيًا إلى {{base_url}}/movie/{{movie_id}}. في المعالج اللاحق للطلب الأول، استخرج results[0].id إلى movie_id بحيث يتبع الاستدعاء الثاني دائمًا الأول.
4. احفظ كلاهما كسيناريو اختبار مع تأكيدات: الحالة تساوي 200، total_results أكبر من 0، و title في استجابة التفاصيل غير فارغ. قم بتشغيله كلما تغير التكامل.

هل تبني واجهة أمامية باستخدام هذه البيانات؟ قم بتشغيل الخادم الوهمي (mock server) لنقطة نهاية البحث. يولد Apidog استجابة مطابقة للمخطط (schema-matching)، بحيث يمكن لفريق واجهة المستخدم بناء شبكة الملصقات دون الحاجة إلى رمز مباشر أو طلبات حقيقية ضد قيود TMDB.

حدود المعدل وقواعد الإسناد

كل ما يلي مقتبس من وثائق TMDB.

حدود المعدل. تشير صفحة تحديد المعدل في TMDB إلى أن الحد الأصلي البالغ 40 طلبًا كل 10 ثوانٍ تم تعطيله في 16 ديسمبر 2019. تظل الحدود العليا قائمة "للمساعدة في تخفيف الكشط بالجملة غير الضروري"، وهي "تقع في نطاق 40 طلبًا في الثانية". يمكن أن يتغير هذا الرقم دون إشعار، لذا احترم أي رمز HTTP 429، وتراجع، وحاول مرة أخرى.

التكلفة. من الأسئلة الشائعة: "واجهة برمجتنا (API) مجانية للاستخدام غير التجاري طالما أنك تنسب الفضل إلى TMDB كمصدر للبيانات و/أو الصور." يجب على المشاريع التجارية الاتصال بـ sales@themoviedb.org.

الإسناد. اعرض شعار TMDB وهذا الإشعار في تطبيقك: "يستخدم هذا المنتج واجهة برمجة تطبيقات TMDB ولكنه غير معتمد أو مصدق من قبل TMDB." تستخدم شروط استخدام API صياغة أطول قليلاً وتتطلب أن يكون الشعار أقل بروزًا من علامتك التجارية الخاصة، ولا يجب أبدًا إعادة تلوينه أو تمديده أو قلبه أو تدويره.

التخزين المؤقت. تحظر الشروط تخزين أي بيانات TMDB مؤقتًا لمدة تزيد عن ستة أشهر. قم بتخزين ما تحتاجه، ولكن خطط للتحديث.

لا يوجد SLA. تقول TMDB ذلك بوضوح. قم ببناء مهلات وإعادة محاولات.

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

الأخطاء الشائعة وما تعنيه

تعيد TMDB جسم JSON يحتوي على status_code و status_message بجانب حالة HTTP. يسرد مرجع الأخطاء عشرات الرموز؛ هذه هي الرموز التي ستراها أولاً.

الأسئلة الشائعة

هل مفتاح API لـ TMDB مجاني؟

نعم، للاستخدام غير التجاري مع الإسناد. لا توجد طبقة خدمة ذاتية مدفوعة. إذا كان مشروعك يحقق إيرادات، تطلب منك TMDB ترتيب اتفاقية تجارية من خلال فريق مبيعاتها.

هل يجب أن أستخدم مفتاح API أم رمز الوصول للقراءة؟

استخدم رمز الوصول للقراءة كترويسة Bearer. تسميه TMDB الافتراضي، وهو يعمل على كل من v3 و v4، ويبقى خارج روابط URL الخاصة بك. يوجد مفتاح v3 للأدوات التي يمكنها فقط إرسال معلمات الاستعلام. إذا كان المفهوم جديدًا، فإن هذا التمهيد حول ما هو مفتاح API يشرح النموذج الذي تتبعه TMDB.

هل يمكنني استدعاء TMDB مباشرة من متصفح أو تطبيق جوال؟

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

ما الفرق بين v3 و v4؟

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

إلى أين تتجه من هنا

لديك الآن مفتاح API يعمل لـ TMDB، وقاعدة لتحديد أي بيانات اعتماد ترسلها، وسير عمل البحث ثم التفاصيل في curl و Python، ونفس سير العمل محفوظًا كسيناريو اختبار Apidog. بعد ذلك، أضف discover/movie للتصفح المفلتر وضع إشعار الإسناد في تطبيقك قبل مشاركته. كل شيء آخر في الكتالوج يستخدم نفس عنوان URL الأساسي، وترويسة Bearer، وأشكال الأخطاء.