إرشادات التوافق مع الإصدارات القديمة

يمكن لكل طلب من طلبات YouTube Data API تحديد إصدار واجهة برمجة التطبيقات الذي يجب أن تستخدمه منصة YouTube لمعالجة هذا الطلب. إذا لم يحدّد الطلب إصدار واجهة برمجة التطبيقات، ستستخدم YouTube أقدم إصدار متوافق من واجهة برمجة التطبيقات لمعالجة هذا الطلب. إنّ أقدم إصدار متوافق حاليًا هو 1. يُرجى مراعاة الخصائص التالية لأرقام إصدارات واجهة برمجة التطبيقات:

  • قد تُصدر YouTube تحديثات لإصدار معيّن من واجهة برمجة التطبيقات لا يتم تخصيص رقم إصدار جديد له. يمكن أن تتضمّن هذه التحديثات المتوافقة مع الإصدارات القديمة ميزات اختيارية لواجهة برمجة التطبيقات أو إصلاحات للأخطاء أو كليهما.

  • تشير الزيادة في رقم إصدار واجهة برمجة التطبيقات إلى إصدار يحتوي على تغييرات غير متوافقة مع إصدارات واجهة برمجة التطبيقات السابقة.

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

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

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

لمحة عن هذا المستند

يحتوي هذا المستند على الأقسام التالية:

  • يحدِّد قسم طلبات واجهة برمجة التطبيقات إرشادات التوافق مع الإصدارات القديمة ذات الصلة بعناوين طلبات HTTP ومعلمات طلبات واجهة برمجة التطبيقات وأسماء عناصر XML (كما تظهر في طلبات واجهة برمجة التطبيقات) وطلبات واجهة برمجة التطبيقات التي تم إنشاؤها بشكل غير صحيح.

  • يحدِّد قسم ردود واجهة برمجة التطبيقات إرشادات التوافق مع الإصدارات القديمة ذات الصلة بأسماء عناصر XML (كما تظهر في ردود واجهة برمجة التطبيقات) والترتيب الذي تظهر به علامات XML وسمات XML في ردود واجهة برمجة التطبيقات.

  • يوضّح قسم أفضل الممارسات اقتراحات لدمج YouTube API مع تطبيق العميل.

طلبات البيانات من واجهة برمجة التطبيقات

الوظائف التي لا يُفترض أن تتغيّر

  • مَعلمات الطلب الحالية

  • قيم المَعلمات الحالية للمَعلمات التي تحتوي على قيم محدّدة أو معاني قيم المَعلمات هذه

  • أسماء عناصر XML المستخدَمة في طلبات POST (إدراج) أو PUT (تعديل) لواجهة برمجة التطبيقات.

  • مجموعة عناوين طلبات HTTP المطلوبة لكل نوع من أنواع طلبات واجهة برمجة التطبيقات يعني هذا الإرشاد أنّ YouTube لا تنوي إضافة رؤوس طلبات HTTP مطلوبة أو تغيير رؤوس الطلبات الاختيارية الحالية لتكون مطلوبة.

  • سلوك تجاهل المَعلمات غير المتوافقة في طلب البيانات من واجهة برمجة التطبيقات ما لم يستخدم الطلب المَعلمة strict التي تطلب من YouTube رفض طلب البيانات من واجهة برمجة التطبيقات الذي يحتوي على مَعلمات طلب غير صالحة

الوظائف التي قد تتغيّر

  • قد تضيف YouTube مَعلمات طلب اختيارية.

  • قد تضيف YouTube قيمًا جديدة للمَعلمات الحالية التي تحتوي على مجموعات مُدرَجة من القيم.

  • يمكن لمنصة YouTube رفض أي طلب تتضمّن فيه المَعلمات الصالحة قيم مَعلمات غير صالحة. نتيجةً لذلك، قد يتم رفض الطلبات التي تم قبولها بسبب التحليل المتساهل للغاية إذا تم تصحيح منطق التحليل.

  • قد تضيف YouTube عناوين طلبات HTTP اختيارية.

  • يجوز لمنصة YouTube تغيير المعلومات التي تحتفظ بها (تخزّنها) عند إدراج مورد أو تعديله. ومع ذلك، لن يؤثّر هذا القرار في طلبات واجهة برمجة التطبيقات المقابلة أو يتطلّب إجراء تغييرات عليها.

  • يجوز لمنصة YouTube تغيير مجموعة الفئات القابلة للتصفّح أو مجموعة الفئات التي يمكن تصنيف الفيديوهات المحمَّلة حديثًا ضمنها.

  • قد تتم إزالة الوظائف غير الموثَّقة أو تغييرها في أي وقت.

الردود من واجهة برمجة التطبيقات

الوظائف التي لا يُفترض أن تتغيّر

  • أسماء علامات XML الحالية

  • اتّباع مواصفات RSS للوسائط لتحديد ترتيب العناصر المحدّدة في هذه المواصفات والتي تظهر عدة مرات في إدخال الخلاصة على سبيل المثال، إذا كان الإدخال يحتوي على علامات <media:thumbnail> متعددة، يتم ترتيبها حسب الأهمية.

  • قيمة سمة term لعلامة <category> التي تحدّد نوع العنصر الموضّح في خلاصة أو إدخال خلاصة. ضمن علامة <feed> أو <entry>، تحدّد علامة <id> المورد الفريد الذي يحدّده الإدخال، وتحدّد علامة <category> نوع المورد الذي يصفه الإدخال. بالنسبة إلى علامة <category> هذه، تكون قيمة سمة المخطّط هي http://schemas.google.com/g/2005#kind، وتشير قيمة سمة العبارة إلى ما إذا كانت إدخالات الخلاصة تصف الفيديوهات أو روابط قوائم التشغيل أو الاشتراكات أو جهات الاتصال أو نوع عنصر آخر.

الوظائف التي قد تتغيّر

  • قد تضيف YouTube علامات XML جديدة إلى ردود واجهة برمجة التطبيقات.

  • قد تضيف YouTube سمات جديدة إلى علامات XML الحالية.

  • قد يتم تكرار علامات واجهة برمجة التطبيقات الحالية بقيم مختلفة. على سبيل المثال، يمكن أن تضيف YouTube علامة <media:restriction> جديدة بقيمة type مختلفة أو علامة <media:credit> جديدة بقيم مختلفة لكل من scheme وrole.

  • قد يتغيّر ترتيب علامات XML وسمات XML في استجابة واجهة برمجة التطبيقات.

  • قد تتم إزالة العلامات الفرعية الاختيارية من ردود واجهة برمجة التطبيقات.

  • قد تتم إزالة الوظائف غير الموثَّقة أو تغييرها في أي وقت.

أفضل الممارسات

  • استخدِم قيمة العلامة <id> لتحديد إدخال.

  • استخدِم الرابط self لاسترداد إدخال.

  • استخدِم الرابط edit لتعديل إدخال أو تعديله.

  • استخدِم قيمة العلامة <yt:videoid> لإدخال فيديو للحصول على القيمة التي تستخدمها YouTube لتحديد هذا الفيديو بشكل فريد. لا تُحلِّل رقم تعريف الفيديو من رابط.

  • استخدِم عناوين URL المحدّدة في علامات <link> و<content> و<gd:feedLink> للتنقّل بين الخلاصات. تتيح منصة YouTube مجموعة محدودة من عناوين URL التي يمكنك إنشاؤها بشكل موثوق لاسترداد خلاصات معيّنة. بالإضافة إلى عناوين URL للخلاصات المدرَجة أدناه، يجب عدم إنشاء عناوين URL للخلاصات بنفسك لأنّها قد تتوقف عن العمل بشكل غير متوقّع.

    • /feeds/api/videos/<videoid>
    • /feeds/api/users/default
    • /feeds/api/users/default/uploads
    • /feeds/api/users/default/favorites
    • /feeds/api/users/default/contacts
    • /feeds/api/users/default/inbox
    • /feeds/api/users/default/playlists
    • /feeds/api/users/default/subscriptions
    • /feeds/api/users/default/newsubscriptionvideos
    • ‎/feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME (اطّلِع على الدليل المرجعي للحصول على مزيد من المعلومات)

  • لا تحاول تحليل المعرّفات الرقمية أو الأبجدية الرقمية من عناوين URL في استجابة واجهة برمجة التطبيقات. تتضمّن ردود واجهات برمجة التطبيقات علامات محدّدة للمعرّفات التي تؤدي إلى مراجع على موقع YouTube الإلكتروني، مثل أرقام تعريف الفيديوهات (<yt:videoid>) وأسماء المستخدمين (<name> و<media:credit>).).

  • إذا أرسلت طلبًا إلى واجهة برمجة التطبيقات لإدراج (POST) معلومات أو تعديلها (PUT)، استخدِم ردّ XML على هذا الطلب لتحديد قيم العلامات في الطلب التي حفظتها YouTube فعليًا. كما هو موضّح في إرشادات التوافق مع الإصدارات القديمة لطلبات واجهة برمجة التطبيقات، قد تغيّر YouTube المعلومات التي تحتفظ بها (تخزّنها) عند إدراج مورد أو تعديله، ما يعني أنّه قد يتم تجاهل بعض العلامات في الطلب.

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

    يوضّح المثال التالي أفضل ممارسة:

    1. يتيح تطبيقك للمستخدم تعديل وصف الفيديو.
    2. يستردّ تطبيقك إدخال الفيديو باستخدام واجهة برمجة التطبيقات، ولكنه لا يتعرّف على إحدى العلامات في الإدخال.
    3. عدّل المستخدم وصف الفيديو.
    4. يجب أن يرسل تطبيقك إدخال فيديو كاملاً إلى واجهة برمجة التطبيقات. يجب أن يتضمّن الإدخال العلامة غير المعروفة من الخطوة 2، وإلا قد يتم حذف هذه القيمة.

  • تأكَّد من توفّر علامة وتتضمّن قيمة غير فارغة قبل محاولة عرض قيمة العلامة.

  • كما ذكرنا أعلاه، قد تضيف YouTube قيمًا جديدة إلى العلامات أو السمات الحالية التي تحتوي على مجموعات مُدرَجة من القيم. وكقاعدة عامة، يجب أن تُحلِّل الرموز البرمجية قيم عناصر XML التي تحتوي على مجموعات مُدرَجة من القيم، ثم تحدِّد الإجراءات المناسبة لهذه القيم. ننصح باتّباع هذه الممارسة حتى إذا تم إدراج قيمة محتملة واحدة فقط للعنصر.

    على سبيل المثال، تحدد العلامة <media:credit> مالك الفيديو. إنّ القيمة الوحيدة الموثَّقة لسمة العلامة role هي uploader، ما يشير إلى أنّ شريكًا في YouTube حمّل الفيديو. تشترط أفضل الممارسات هذه أن يؤكد تطبيقك أنّ قيمة سمة role للعلامة هي uploader قبل تحديد المستخدم المقابل كصاحب الفيديو. (يضمن هذا الإجراء الوقائي عدم تحديد رمزك مالك الفيديو بشكل غير دقيق إذا أضافت YouTube أنواعًا أخرى من المساهمين في الفيديو، مثل المخرج).

    • إذا كانت العلامة تتضمّن مجموعة محدّدة من القيم ولا تعرف قيمة هذه العلامة، عليك تجاهل <entry> بالكامل الذي تظهر فيه هذه العلامة.

    • تجاهل إدخال خلاصة الاشتراكات إذا لم تتعرّف على قيمة سمة term لعلامة <category> التي تحتوي على قيمة سمة scheme‏ = http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. وتحدِّد هذه العلامة المحدّدة نوع الاشتراك الذي يحدِّده الإدخال. إذا لم يتعرّف تطبيقك على نوع الاشتراك، يجب ألّا يعرض معلومات عن هذا الإدخال.

    • إذا كانت أي سمة أخرى تحتوي على مجموعة مُدرَجة من القيم ولا تعرف قيمة هذه السمة، عليك تجاهل العلامة التي تظهر فيها السمة.

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

  • يمكن أن تضيف YouTube فئات جديدة لتصنيف الفيديوهات في أي وقت. وقد تعدّل YouTube أيضًا الفئات الحالية أو تُوقف استخدامها نهائيًا. يمكنك استرداد ملف الفئات الحالي من http://gdata.youtube.com/schemas/2007/categories.cat.

    • إذا كان تطبيقك يتيح للمستخدمين تصفُّح الفيديوهات حسب الفئة أو تحميل الفيديوهات، يمكنك استرداد ملف الفئات المعدَّل أسبوعيًا.

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

    • إذا كان تطبيقك يتيح للمستخدمين تحميل الفيديوهات، يمكنك أيضًا استرداد ملف الفئات المعدَّل قبل تحميل فيديو والتأكّد من أنّ الفئة المرتبطة بالفيديو المحمَّل لا تزال قابلة للتحديد. اطّلِع على الدليل المرجعي للحصول على مزيد من المعلومات. (يُرجى العِلم أنّه في حال محاولة إضافة فيديو إلى فئة لا يمكن إضافته إليها، ستعرض واجهة برمجة التطبيقات رسالة خطأ تكون قيمة علامة <code> فيها deprecated).

  • استخدِم علامات <link> في استجابة واجهة برمجة التطبيقات لتحديد روابط تقسيم الصفحات للصفحة السابقة و/أو التالية من الإدخالات في خلاصة. راجِع قسم التنقّل بين النتائج في الدليل المرجعي للحصول على مزيد من المعلومات.