PlaylistItems: insert

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

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

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

درخواست

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

متن درخواست

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

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

    • snippet.playlistId
    • snippet.resourceId

  • می‌توانید مقادیر این دارایی‌ها را تنظیم کنید:

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

پاسخ

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

خطاها

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

نوع خطا جزئیات خطا شرح
forbidden (403) playlistContainsMaximumNumberOfVideos فهرست پخش ازقبل حاوی حداکثر تعداد مجاز موارد است.
forbidden (403) playlistItemsNotAccessible درخواست برای درج مورد فهرست پخش مشخص‌شده به‌درستی مجاز نیست.
invalidValue (400) invalidContentDetails خصوصیت contentDetails در درخواست معتبر نیست. دلیل احتمالی این است که فیلد contentDetails.note طولانی‌تر از ۲۸۰ نویسه است.
invalidValue (400) invalidPlaylistItemPosition درخواست تلاش می‌کند موقعیت عنصر فهرست پخش را روی مقدار نامعتبر یا پشتیبانی‌نشده تنظیم کند. مقدار ویژگی position را در snippet منبع بررسی کنید.
invalidValue (400) invalidResourceType type مشخص‌شده برای شناسه منبع برای این عملیات پشتیبانی نمی‌شود. شناسه منبع، موردی را که به فهرست پخش اضافه می‌شود شناسایی می‌کند – مثلاً youtube#video.
invalidValue (400) manualSortRequired درخواست تلاش می‌کند جایگاه مورد فهرست پخش را تنظیم کند، اما فهرست پخش از مرتب‌سازی دستی استفاده نمی‌کند. (برای مثال، موارد فهرست پخش ممکن است براساس تاریخ یا محبوبیت مرتب شوند.) می‌توانید با برداشتن عنصر snippet.position از منبعی که درخواست در آن درج می‌شود، خطا را برطرف کنید. اگر می‌خواهید مورد فهرست پخش جایگاه خاصی در فهرست داشته باشد، ابتدا باید گزینه ترتیب فهرست پخش را در تنظیمات فهرست پخش به دستی به‌روز کنید. این تنظیمات را می‌توان در مدیر ویدیو 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 میانای برنامه‌سازی کاربردی از قابلیت درج ویدیو در فهرست پخش مشخص‌شده پشتیبانی نمی‌کند. برای مثال، نمی‌توانید ویدیویی را در فهرست پخش ویدیوهای بارگذاری‌شده خود درج کنید.

امتحان کنید!

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