دستورالعمل های سازگاری با عقب

هر درخواست YouTube Data API می‌تواند نسخه API را که YouTube باید برای رسیدگی به آن درخواست استفاده کند، مشخص کند. اگر درخواستی نسخه API را مشخص نکرده باشد، YouTube از قدیمی ترین نسخه پشتیبانی شده API برای رسیدگی به آن درخواست استفاده خواهد کرد. قدیمی ترین نسخه پشتیبانی شده در حال حاضر 1 است. لطفاً به ویژگی‌های زیر شماره‌های نسخه API توجه کنید:

• YouTube ممکن است به‌روزرسانی‌هایی را برای یک نسخه API خاص منتشر کند که شماره نسخه جدیدی برای آن اختصاص داده نشده است. این به روز رسانی های سازگار با عقب می تواند شامل ویژگی های اختیاری API، رفع اشکال یا هر دو باشد.

• افزایش شماره نسخه API، نسخه ای را مشخص می کند که حاوی تغییرات ناسازگار با نسخه های قبلی API است.

این سند دستورالعمل های سازگاری با عقب را برای به روز رسانی یک نسخه API خاص، اولین مورد ذکر شده در بالا، تعریف می کند. این دستورالعمل ها به دنبال تمایز بین انواع زیر از عملکرد API هستند:

• دستورالعمل ها عملکرد API را مشخص می کند که ممکن است تغییر کند حتی اگر نسخه API را که باید برای رسیدگی به درخواست های API خود استفاده شود تغییر ندهید. کد شما باید این تغییرات را بدون شکستگی انجام دهد. به عنوان مثال، اگر YouTube تگ های XML جدیدی را به پاسخ های API اضافه کند، کد شما باید آن تگ ها را نادیده بگیرد.

• دستورالعمل ها همچنین عملکرد API را تعریف می کنند که YouTube قصد ندارد هنگام به روز رسانی یک نسخه API خاص آن را تغییر دهد. به عبارت دیگر، تنها در صورتی باید انتظار داشته باشید که این عملکرد تغییر کند که یوتیوب یک نسخه API جدید منتشر کند، و نیازی نیست کد شما تلاشی برای مدیریت این نوع تغییرات داشته باشد.

در مورد این سند

این سند شامل بخش های زیر است:

• بخش درخواست‌های API دستورالعمل‌های سازگاری با عقب‌تر مربوط به سرصفحه‌های درخواست HTTP، پارامترهای درخواست API، نام‌های عناصر XML (همانطور که در درخواست‌های API ظاهر می‌شوند) و درخواست‌های API که به درستی شکل‌گرفته‌اند را تعریف می‌کند.

• بخش پاسخ‌های API دستورالعمل‌های سازگاری با عقب‌تر مربوط به نام‌های عناصر XML (همانطور که در پاسخ‌های API ظاهر می‌شوند) و ترتیب ظاهر شدن برچسب‌ها و ویژگی‌های XML در پاسخ‌های API را تعریف می‌کند.

• بخش بهترین روش‌ها توصیه‌هایی را برای ادغام YouTube API با برنامه مشتری شما ارائه می‌کند.

درخواست های API

عملکردی که قرار نیست تغییر کند

• پارامترهای درخواست موجود

• مقادیر پارامتر موجود برای پارامترهایی که دارای مقادیر شمارش شده یا معانی آن مقادیر پارامتر هستند.

• نام عناصر XML مورد استفاده در درخواست‌های API POST (درج) یا PUT (به‌روزرسانی).

• مجموعه ای از هدرهای درخواست HTTP که برای هر نوع درخواست API مورد نیاز است. این دستورالعمل به این معنی است که YouTube قصد ندارد سرصفحه‌های درخواست HTTP مورد نیاز را اضافه کند یا سرصفحه‌های درخواست اختیاری موجود را تغییر دهد.

• رفتار نادیده گرفتن پارامترهای پشتیبانی نشده در یک درخواست API، مگر اینکه درخواست از پارامتر strict استفاده کند، که به YouTube دستور می دهد درخواست API را که حاوی پارامترهای درخواست نامعتبر است رد کند.

عملکردی که ممکن است تغییر کند

• YouTube ممکن است پارامترهای درخواست اختیاری را اضافه کند.

• YouTube ممکن است مقادیر جدیدی برای پارامترهای موجود که مجموعه‌ای از مقادیر را برشمرده‌اند، اضافه کند.

• YouTube می‌تواند هر درخواستی را که در آن پارامترهای معتبر حاوی مقادیر پارامتر نامعتبر هستند، رد کند. در نتیجه، درخواست‌های نادرست شکل‌گرفته که به دلیل تجزیه بیش از حد نرم پذیرفته شده‌اند، در صورت اصلاح منطق تجزیه، ممکن است رد شوند.

• YouTube ممکن است سرصفحه های درخواست HTTP اختیاری را اضافه کند.

• YouTube ممکن است اطلاعاتی را که هنگام درج یا به‌روزرسانی یک منبع حفظ می‌کند (ذخیره می‌کند) تغییر دهد. با این حال، چنین تصمیمی بر نحو درخواست‌های API مربوطه تأثیر نمی‌گذارد یا نیاز به تغییراتی در آن ندارد.

• YouTube ممکن است مجموعه دسته‌های قابل مرور یا مجموعه دسته‌هایی را که ویدیوهای آپلود شده جدید می‌توانند به آن‌ها اختصاص داده شوند را تغییر دهد.

• عملکرد غیرمستند ممکن است در هر زمان حذف یا تغییر یابد.

پاسخ های API

عملکردی که قرار نیست تغییر کند

• نام تگ های XML موجود.

• پیروی از مشخصات RSS Media برای تعیین ترتیب عناصری که در آن مشخصات تعریف شده اند و چندین بار در یک ورودی خوراک ظاهر می شوند. برای مثال، اگر یک ورودی حاوی چندین تگ <media:thumbnail> باشد، آنها بر اساس اهمیت مرتب می شوند.

• term مقدار ویژگی تگ <category> که نوع مورد توصیف شده در یک فید یا ورودی فید را مشخص می کند. در تگ <feed> یا <entry> ، تگ <id> منبع منحصربه‌فرد شناسایی‌شده توسط ورودی را مشخص می‌کند، و تگ <category> نوع منبع توصیف‌شده توسط ورودی را مشخص می‌کند. برای این تگ <category> ، مقدار ویژگی scheme http://schemas.google.com/g/2005#kind است و مقدار ویژگی عبارت نشان می‌دهد که آیا ورودی‌های فید ویدیوها، پیوندهای لیست پخش، اشتراک‌ها، مخاطبین یا یک نوع موجودیت دیگر

عملکردی که ممکن است تغییر کند

• YouTube ممکن است برچسب‌های XML جدیدی را به پاسخ‌های API اضافه کند.

• YouTube ممکن است ویژگی‌های جدیدی را به برچسب‌های XML موجود اضافه کند.

• تگ های API موجود ممکن است با مقادیر متفاوتی تکرار شوند. برای مثال، YouTube می‌تواند یک تگ <media:restriction> جدید با مقدار type متفاوت یا یک تگ <media:credit> جدید با scheme و role متفاوت اضافه کند.

• ترتیب تگ‌ها و ویژگی‌های XML در پاسخ API ممکن است تغییر کند.

• برچسب‌های فرزند اختیاری ممکن است از پاسخ‌های API حذف شوند.

• عملکرد غیرمستند ممکن است در هر زمان حذف یا تغییر یابد.

بهترین شیوه ها

• از مقدار تگ <id> برای شناسایی یک ورودی استفاده کنید.

• از پیوند self برای بازیابی ورودی استفاده کنید.

• از پیوند edit برای ویرایش یا به روز رسانی یک ورودی استفاده کنید.

• از ارزش تگ <yt:videoid> برای ورودی ویدیو استفاده کنید تا مقداری را که YouTube برای شناسایی منحصر به فرد آن ویدیو استفاده می کند، به دست آورید. شناسه ویدیو را از پیوند تجزیه نکنید.

• برای پیمایش بین فیدها از نشانی‌های اینترنتی مشخص شده در تگ‌های <link> ، <content> و <gd:feedLink> استفاده کنید. YouTube از مجموعه محدودی از نشانی‌های اینترنتی پشتیبانی می‌کند که می‌توانید با اطمینان آن‌ها را برای بازیابی فیدهای خاص بسازید. جدا از آن 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 ها در پاسخ API تجزیه کنید. پاسخ‌های API شامل برچسب‌های خاصی برای شناسه‌هایی است که به منابع موجود در وب‌سایت YouTube پیوند دارند، مانند شناسه‌های ویدیو ( <yt:videoid> ) و نام‌های کاربری ( <name> و <media:credit>).

• اگر یک درخواست API برای درج (POST) یا به‌روزرسانی (PUT) اطلاعات ارسال می‌کنید، از پاسخ XML به آن درخواست برای تعیین اینکه کدام مقادیر برچسب در درخواست واقعاً توسط YouTube ذخیره شده است استفاده کنید. همانطور که در دستورالعمل‌های سازگاری با عقب برای درخواست‌های API ذکر شده است، YouTube ممکن است اطلاعاتی را که هنگام درج یا به‌روزرسانی یک منبع حفظ می‌کند (ذخیره می‌کند) تغییر دهد، به این معنی که برخی از برچسب‌های موجود در درخواست ممکن است نادیده گرفته شوند.

• هنگامی که یک فید XML را بازیابی می کنید، اگر برنامه شما به کاربر امکان می دهد آن ورودی را به روز کند، برچسب ها و ویژگی های XML ناشناخته مربوط به ورودی فید را ذخیره کنید. اگر کاربر منبع را به روز کند، برنامه شما باید هر گونه برچسب و ویژگی ناشناخته را در درخواست به روز رسانی شامل شود. این عمل تضمین می کند که برنامه شما سهواً اطلاعات مربوط به ویژگی های جدید API را در فرآیند به روز رسانی یک منبع حذف نمی کند.

  مثال زیر این بهترین روش را نشان می دهد:

  1. برنامه شما به کاربر امکان می دهد توضیحات ویدیو را به روز کند.
  2. برنامه شما ورودی ویدیو را با استفاده از API بازیابی می کند اما یکی از برچسب های ورودی را نمی شناسد.
  3. کاربر توضیحات ویدیو را تغییر می دهد.
  4. برنامه شما باید یک ورودی ویدیویی کامل را به API ارسال کند. ورودی باید شامل برچسب ناشناخته از مرحله 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 باشد. در صورتی که یک عملیات API با شکست مواجه شود، برنامه شما باید خطا را شناسایی کرده و یک پیام معنادار برای کاربر نمایش دهد.

• YouTube ممکن است در هر زمان دسته‌های جدیدی را برای طبقه‌بندی ویدیوها اضافه کند. YouTube همچنین ممکن است دسته‌های موجود را به‌روزرسانی یا منسوخ کند. می توانید یک فایل دسته بندی فعلی را از http://gdata.youtube.com/schemas/2007/categories.cat بازیابی کنید.

  • اگر برنامه شما به کاربران امکان می دهد ویدیوها را بر اساس دسته بندی مرور کنند یا ویدیوها را آپلود کنند، یک فایل دسته بندی به روز شده را به صورت هفتگی بازیابی کنید.

  • اگر برنامه شما به کاربران امکان می‌دهد ویدیوها را بر اساس دسته مرور کنند، اگر API در پاسخ به جستجوی دسته‌بندی، فید خالی را برمی‌گرداند، یک فایل دسته‌بندی به‌روزرسانی شده را نیز بازیابی کنید.

  • اگر برنامه شما به کاربران امکان می‌دهد ویدیوها را آپلود کنند، قبل از آپلود ویدیو، یک فایل دسته‌بندی به‌روز شده را نیز بازیابی کنید و تأیید کنید که دسته مرتبط با ویدیوی آپلود شده هنوز قابل تخصیص است. برای اطلاعات بیشتر به راهنمای مرجع مراجعه کنید. (توجه داشته باشید که اگر بخواهید ویدیویی را به دسته‌ای غیرقابل تخصیص اختصاص دهید، API یک پیام خطایی برمی‌گرداند که برای آن مقدار تگ <code> deprecated است.)

• از تگ‌های <link> در پاسخ API برای شناسایی پیوندهای صفحه‌بندی برای صفحه قبلی و/یا بعدی ورودی‌های یک فید استفاده کنید. برای اطلاعات بیشتر به بخش Paging through results راهنمای مرجع مراجعه کنید.