PlaylistItems: insert

منبعی را به لیست پخش اضافه می کند.

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

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

درخواست

درخواست HTTP

POST 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
  • id
  • snippet
  • status
پارامترهای اختیاری
onBehalfOfContentOwner string
این پارامتر فقط در یک درخواست مجاز به درستی قابل استفاده است. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube در نظر گرفته شده است.

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

درخواست بدن

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

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

    • snippet.playlistId
    • snippet.resourceId

  • شما می توانید مقادیری را برای این ویژگی ها تنظیم کنید:

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

واکنش

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

خطاها

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

نوع خطا جزئیات خطا شرح
forbidden (403) playlistContainsMaximumNumberOfVideos لیست پخش از قبل دارای حداکثر تعداد مجاز موارد است.
forbidden (403) playlistItemsNotAccessible درخواست به درستی برای درج مورد لیست پخش مشخص شده مجاز نیست.
invalidValue (400) invalidContentDetails ویژگی contentDetails در درخواست معتبر نیست. یک دلیل احتمالی این است که فیلد contentDetails.note بیشتر از 280 کاراکتر است.
invalidValue (400) invalidPlaylistItemPosition این درخواست تلاش می‌کند موقعیت مورد لیست پخش را روی یک مقدار نامعتبر یا پشتیبانی‌نشده تنظیم کند. مقدار ویژگی position را در snippet منبع بررسی کنید.
invalidValue (400) invalidResourceType type مشخص شده برای شناسه منبع برای این عملیات پشتیبانی نمی شود. شناسه منبع موردی را که به لیست پخش اضافه می شود مشخص می کند - به عنوان مثال youtube#video .
invalidValue (400) manualSortRequired درخواست سعی می‌کند موقعیت آیتم فهرست پخش را تنظیم کند، اما فهرست پخش از مرتب‌سازی دستی استفاده نمی‌کند. (به عنوان مثال، آیتم های لیست پخش ممکن است بر اساس تاریخ یا محبوبیت مرتب شوند.) می توانید با حذف عنصر snippet.position از منبعی که درخواست درج می کند، خطا را برطرف کنید. اگر می‌خواهید مورد لیست پخش موقعیت خاصی در لیست داشته باشد، ابتدا باید در تنظیمات لیست پخش، گزینه Ordering لیست پخش را به Manual به‌روزرسانی کنید. این تنظیمات را می توان در مدیر ویدیوی YouTube تنظیم کرد.
invalidValue (400) videoAlreadyInAnotherSeriesPlaylist ویدیویی که می‌خواهید به لیست پخش اضافه کنید در حال حاضر در لیست پخش مجموعه دیگری است.
notFound (404) playlistNotFound لیست پخش شناسایی شده با پارامتر playlistId درخواست یافت نمی شود.
notFound (404) videoNotFound ویدیویی که می‌خواهید به لیست پخش اضافه کنید پیدا نمی‌شود. مقدار ویژگی videoId را بررسی کنید تا مطمئن شوید که درست است.
required (400) channelIdRequired درخواست مقداری برای ویژگی channelId مورد نیاز مشخص نمی کند.
required (400) playlistIdRequired درخواست مقداری برای ویژگی playlistId مورد نیاز مشخص نمی کند.
required (400) resourceIdRequired درخواست باید حاوی منبعی باشد که در آن شی snippet یک resourceId را مشخص کند.
invalidValue (400) playlistOperationUnsupported API از قابلیت درج ویدیوها در لیست پخش مشخص شده پشتیبانی نمی کند. برای مثال، نمی‌توانید ویدیویی را در لیست پخش ویدیوهای آپلود شده خود وارد کنید.

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

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