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

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

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

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

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

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

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

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

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

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

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

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

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

الوظائف التي لا يُقصد تغييرها

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

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

  • أسماء عناصر 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 وتشير قيمة السمة term إلى ما إذا كانت إدخالات الخلاصة تصف مقاطع الفيديو أو روابط قوائم التشغيل أو الاشتراكات أو جهات الاتصال أو نوع كيان آخر.

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

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

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

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

  • قد يتغير ترتيب علامات وسمات 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 غير معروفة ومرتبطة بأحد إدخالات الخلاصة إذا كان التطبيق يمكّن المستخدم من تحديث هذا الإدخال. إذا حدَّث المستخدم المورد، يجب أن يتضمن تطبيقك أي علامات وسمات غير معروفة في طلب التحديث. تضمن هذه الممارسة عدم حذف تطبيقك بدون قصد معلومات ذات صلة بميزات واجهة برمجة التطبيقات الجديدة أثناء عملية تحديث المورد.

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

    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> في استجابة واجهة برمجة التطبيقات للتعرّف على روابط التقسيم على صفحات في الصفحة السابقة و/أو الصفحة التالية من الإدخالات في الخلاصة. راجع قسم ترحيل الصفحات من خلال النتائج في الدليل المرجعي لمزيد من المعلومات.