Videos: update

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

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

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

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

درخواست کنید

درخواست 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 همچنان در پاسخ API گنجانده می شود.

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

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

درخواست بدن

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

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

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

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

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

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

پاسخ

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

خطاها

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

نوع خطا جزئیات خطا توضیحات
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 استفاده کنید.