PlaylistItems: update

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

تاثیر سهمیه ای: فراخوانی به این روش هزینه سهمیه ای 50 واحدی دارد.

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

درخواست

درخواست 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 Creator Studio پیوند داده شود.

درخواست بدن

یک منبع 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 از منبعی که درخواست درج می کند، خطا را برطرف کنید. اگر می‌خواهید مورد لیست پخش موقعیت خاصی در لیست داشته باشد، ابتدا باید در تنظیمات لیست پخش، گزینه Ordering لیست پخش را به Manual به‌روزرسانی کنید. این تنظیمات را می توان در مدیر ویدیوی 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 از توانایی به روز رسانی ویدیوها در لیست پخش مشخص شده پشتیبانی نمی کند. برای مثال، نمی‌توانید ویدیویی را در لیست پخش ویدیوهای آپلود شده خود به‌روزرسانی کنید.

آن را امتحان کنید!

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

،

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

تاثیر سهمیه ای: فراخوانی به این روش هزینه سهمیه ای 50 واحدی دارد.

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

درخواست

درخواست 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 Creator Studio پیوند داده شود.

درخواست بدن

یک منبع 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 از منبعی که درخواست درج می کند، خطا را برطرف کنید. اگر می‌خواهید مورد لیست پخش موقعیت خاصی در لیست داشته باشد، ابتدا باید در تنظیمات لیست پخش، گزینه Ordering لیست پخش را به Manual به‌روزرسانی کنید. این تنظیمات را می توان در مدیر ویدیوی 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 از توانایی به روز رسانی ویدیوها در لیست پخش مشخص شده پشتیبانی نمی کند. برای مثال، نمی‌توانید ویدیویی را در لیست پخش ویدیوهای آپلود شده خود به‌روزرسانی کنید.

آن را امتحان کنید!

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