PlaylistItems: update

مورد فهرست پخش را اصلاح می‌کند. برای مثال، می‌توانید موقعیت مورد را در فهرست پخش به‌روز کنید.

تأثیر سهمیه: فراخوانی این روش هزینه سهمیه ۵۰ واحدی دارد.

موارد استفاده رایج

درخواست

درخواست HTTP

PUT https://www.googleapis.com/youtube/v3/playlistItems

صدور مجوز

این درخواست به مجوز با حداقل یکی از دامنه‌های زیر نیاز دارد (درباره اصالت‌سنجی و مجوز بیشتر بخوانید).

حوزه
https://www.googleapis.com/auth/youtubepartner
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl

پارامترها

جدول زیر پارامترهایی را که این پُرسمان پشتیبانی می‌کند فهرست می‌کند. همه پارامترهای فهرست‌شده پارامترهای پُرسمان هستند.

پارامترها
پارامترهای الزامی
part string
پارامتر part در این عملیات دو هدف دارد. این روش مشخص می‌کند که عملیات نوشتن کدام دارایی‌ها را تنظیم می‌کند و پاسخ API کدام دارایی‌ها را دربرمی‌گیرد.

توجه داشته باشید که این روش مقادیر موجود را برای همه دارایی‌های تغییرپذیری که در هر بخشی که مقدار پارامتر مشخص می‌کند وجود دارد ملغی می‌کند. برای مثال، یک مورد فهرست پخش می‌تواند زمان شروع و پایان را مشخص کند که بخش زمانی ویدیو را که باید هنگام تماشای ویدیو در فهرست پخش پخش شود، تعیین می‌کند. اگر درخواست شما درحال به‌روزرسانی یک عنصر فهرست پخش است که این مقادیر را تنظیم می‌کند، و مقدار پارامتر part درخواست شامل بخش contentDetails است، زمان‌های شروع و پایان عنصر فهرست پخش به هر مقداری که در بدنه درخواست مشخص شده است به‌روزرسانی خواهند شد. اگر بدنه درخواست مقادیر را مشخص نکند، زمان‌های شروع و پایان موجود برداشته می‌شوند و با تنظیمات پیش‌فرض جایگزین می‌شوند.

فهرست زیر حاوی نام‌های part است که می‌توانید در مقدار پارامتر اضافه کنید:
  • contentDetails
  • id
  • snippet
  • status
پارامترهای اختیاری
onBehalfOfContentOwner string
توجه: پارامتر onBehalfOfContentOwner منحصراً برای شرکای محتوای YouTube درنظر گرفته شده است و فقط در یک درخواست مجاز به‌درستی قابل استفاده است.

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

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

متن درخواست

یک منبع playlistItem در بدنه درخواست ارائه دهید. برای آن منبع:

  • باید مقداری برای این ویژگی‌ها مشخص کنید:

    • id
    • snippet.playlistId
    • snippet.resourceId

  • می‌توانید برای این مشخصات مقدار تنظیم کنید:

    • snippet.position
    • contentDetails.note
    • contentDetails.startAt
    • contentDetails.endAt

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

پاسخ

درصورت موفقیت، این روش یک منبع playlistItem را در بدنه پاسخ برمی‌گرداند.

خطاها

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

نوع خطا جزئیات خطا شرح
forbidden (403) playlistItemsNotAccessible درخواست برای به‌روزرسانی مورد فهرست پخش مشخص‌شده به‌درستی مجاز نیست.
invalidValue (400) invalidPlaylistItemPosition درخواست تلاش می‌کند موقعیت عنصر فهرست پخش را روی مقدار نامعتبر یا پشتیبانی‌نشده تنظیم کند. مقدار ویژگی position را در snippet منبع بررسی کنید.
invalidValue (400) invalidResourceType ‫type مشخص‌شده برای شناسه منبع برای این عملیات پشتیبانی نمی‌شود. شناسه منبع مورد اضافه‌شده به فهرست پخش را شناسایی می‌کند – برای نمونه youtube#video.
invalidValue (400) invalidSnippet درخواست، دارایی معتبر snippet را مشخص نمی‌کند.
invalidValue (400) manualSortRequired درخواست تلاش می‌کند جایگاه مورد فهرست پخش را تنظیم کند، اما فهرست پخش از مرتب‌سازی دستی استفاده نمی‌کند. (برای مثال، موارد فهرست پخش ممکن است براساس تاریخ یا محبوبیت مرتب شوند.) می‌توانید با برداشتن عنصر snippet.position از منبعی که درخواست در آن درج می‌شود، خطا را برطرف کنید. اگر می‌خواهید مورد فهرست پخش جایگاه خاصی در فهرست داشته باشد، ابتدا باید گزینه ترتیب فهرست پخش را در تنظیمات فهرست پخش به دستی به‌روز کنید. این تنظیمات را می‌توان در مدیر ویدیو YouTube تغییر داد.
notFound (404) playlistItemNotFound مورد فهرست پخش شناسایی‌شده با ویژگی id درخواست پیدا نشد.
notFound (404) playlistNotFound فهرست پخش شناسایی‌شده با پارامتر playlistId درخواست پیدا نشد.
required (400) channelIdRequired درخواست مقداری برای دارایی الزامی channelId مشخص نکرده است.
required (400) playlistIdRequired درخواست مقداری برای ویژگی الزامی playlistId مشخص نمی‌کند.
required (400) playlistItemIdRequired منبع مورد فهرست پخش مشخص‌شده در درخواست باید از ویژگی id برای شناسایی مورد فهرست پخش درحال به‌روزرسانی استفاده کند.
invalidValue (400) playlistOperationUnsupported API از قابلیت به‌روزرسانی ویدیوها در فهرست پخش مشخص‌شده پشتیبانی نمی‌کند. برای مثال، نمی‌توانید ویدیویی را در فهرست پخش ویدیوهای بارگذاری‌شده خود به‌روز کنید.

امتحان کنید!

برای فراخوانی این API و دیدن درخواست و پاسخ API، از APIs Explorer استفاده کنید.