Videos: update

اکنون API از قابلیت علامت‌گذاری کانال یا ویدیوها به‌عنوان «ساخته‌شده برای کودکان» پشتیبانی می‌کند. علاوه‌براین، منابع channel و video اکنون حاوی ویژگی‌ای هستند که وضعیت «ساخته‌شده برای کودکان» آن کانال یا ویدیو را مشخص می‌کند. «شرایط خدمات خدمات YouTube API» و «خط‌مشی‌های توسعه‌دهندگان» نیز در تاریخ ۱۰ ژانویه ۲۰۲۰ به‌روزرسانی شدند. برای اطلاعات بیشتر، سوابق بازبینی خدمات YouTube Data API و شرایط خدمات YouTube API Services را ببینید.

فراداده ویدیو را به‌روزرسانی می‌کند.

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

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

درخواست

درخواست HTTP

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

صدور مجوز

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

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

پارامترها

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

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

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

علاوه‌براین، همه بخش‌ها حاوی دارایی‌هایی نیستند که هنگام درج یا به‌روزرسانی ویدیو قابل تنظیم باشند. برای مثال، شیء statistics آماری را که YouTube برای یک ویدیو محاسبه می‌کند، کپسوله‌سازی می‌کند و حاوی مقادیری نیست که بتوانید تنظیم یا اصلاح کنید. اگر مقدار پارامتر part را مشخص کند که حاوی مقادیر قابل‌تغییر نباشد، آن part همچنان در پاسخ میانای برنامه‌سازی کاربردی گنجانده خواهد شد.

فهرست زیر حاوی نام‌های part است که می‌توانید در مقدار پارامتر بگنجانید:
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
پارامترهای اختیاری
onBehalfOfContentOwner string
از این پارامتر فقط می‌توان در درخواست مجاز مناسب استفاده کرد. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube درنظر گرفته شده است.

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

متن درخواست

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

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

    • id
    • snippet.title – این ویژگی فقط درصورتی لازم است که درخواست، snippet منبع video را به‌روز کند.
    • snippet.categoryId – این دارایی فقط درصورتی الزامی است که درخواست منبع video را به‌روزرسانی کندsnippet.

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

    • snippet.categoryId
    • snippet.defaultLanguage
    • snippet.description
    • snippet.tags[]
    • snippet.title
    • status.embeddable
    • status.license
    • status.privacyStatus
    • status.publicStatsViewable
    • status.publishAt – اگر مقداری برای این دارایی تنظیم می‌کنید، باید دارایی status.privacyStatus را نیز روی private تنظیم کنید. این دارایی فقط درصورتی می‌تواند تنظیم شود که وضعیت حریم خصوصی ویدیو private باشد و ویدیو هرگز منتشر نشده باشد.
    • status.selfDeclaredMadeForKids
    • status.containsSyntheticMedia
    • recordingDetails.recordingDate
    • localizations.(key)
    • localizations.(key).title
    • localizations.(key).description

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

پاسخ

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

خطاها

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

نوع خطا جزئیات خطا شرح
badRequest (400) defaultLanguageNotSet درخواست API سعی دارد جزئیات ویدیو بومی‌سازی‌شده را بدون مشخص کردن زبان پیش‌فرض جزئیات ویدیو اضافه کند.
badRequest (400) invalidCategoryId ویژگی snippet.categoryId شناسه دسته نامعتبری را مشخص می‌کند. از روش videoCategories.list برای بازیابی دسته‌های پشتیبانی‌شده استفاده کنید.
badRequest (400) invalidDefaultBroadcastPrivacySetting درخواست تلاش می‌کند تنظیم حریم خصوصی نامعتبری را برای همه‌فرستی پیش‌فرض تنظیم کند.
badRequest (400) invalidDescription فراداده درخواست شرح ویدیو نامعتبری را مشخص می‌کند.
badRequest (400) invalidPublishAt فراداده درخواست، زمان انتشار برنامه‌ریزی‌شده نامعتبری را مشخص می‌کند.
badRequest (400) invalidRecordingDetails شیء recordingDetails در فراداده درخواست جزئیات ضبط نامعتبر را مشخص می‌کند.
badRequest (400) invalidTags فراداده درخواست، کلیدواژه‌های ویدیو نامعتبر را مشخص می‌کند.
badRequest (400) invalidTitle فراداده درخواست عنوان ویدیو نامعتبر یا خالی را مشخص می‌کند.
badRequest (400) invalidVideoMetadata فراداده درخواست نامعتبر است.
forbidden (403) forbidden
forbidden (403) forbiddenEmbedSetting درخواست تلاش می‌کند تنظیم جاسازی نامعتبری برای ویدیو تنظیم کند. توجه داشته باشید که برخی کانال‌ها ممکن است اجازه ارائه پخش‌کننده‌های جاسازی‌شده برای جاری‌سازی‌های زنده را نداشته باشند. برای اطلاعات بیشتر، به مرکز راهنمایی YouTube مراجعه کنید.
forbidden (403) forbiddenLicenseSetting درخواست تلاش می‌کند پروانه نامعتبری برای ویدیو تنظیم کند.
forbidden (403) forbiddenPrivacySetting درخواست تلاش می‌کند تنظیمات حریم خصوصی نامعتبری را برای ویدیو تنظیم کند.
notFound (404) videoNotFound ویدیویی که تلاش می‌کنید به‌روزرسانی کنید پیدا نشد. مقدار فیلد id را در بدنه درخواست بررسی کنید تا مطمئن شوید درست است.

امتحان کنید!

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