Channels: update

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

فراداده کانال را به‌روزرسانی می‌کند. توجه داشته باشید که این روش فقط از به‌روزرسانی‌های اشیای brandingSettings، invideoPromotion، و localizations منبع channel و ویژگی‌های فرزند آن‌ها پشتیبانی می‌کند.

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

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

درخواست

درخواست HTTP

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

صدور مجوز

این درخواست به مجوز با حداقل یکی از دامنه‌های زیر نیاز دارد. برای کسب اطلاعات بیشتر درباره اصالت‌سنجی و صدور مجوز، به پیاده‌سازی مجوز OAuth 2.0 مراجعه کنید.

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

پارامترها

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

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

میانای برنامه‌سازی کاربردی فقط اجازه می‌دهد مقدار پارامتر روی brandingSettings، invideoPromotion، یا localizations تنظیم شود. (فقط می‌توانید یکی از این بخش‌ها را با یک درخواست به‌روز کنید.)

توجه داشته باشید که این روش مقادیر موجود را برای همه ویژگی‌های قابل تغییر که در بخشی که مقدار پارامتر مشخص می‌کند، لغو می‌کند.
پارامترهای اختیاری
onBehalfOfContentOwner string
از این پارامتر فقط می‌توان در درخواست مجاز مناسب استفاده کرد.

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

اگر درخواست با اطلاعات کاربری کاربر مالک محتوای CMS که در کانال مدیریت‌شده‌ای فعالیت می‌کند اصالت‌سنجی شده باشد، این پارامتر باید ارائه شود. اگر حذف شود، درخواست تحت زمینه مستقیم کاربر اصالت‌سنجی‌شده اجرا می‌شود و خطای HTTP 403 Forbidden را برمی‌گرداند.

متن درخواست

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

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

    • id

  • می‌توانید برای این مشخصات مقدار تنظیم کنید:

    • brandingSettings.channel.country
    • brandingSettings.channel.description
    • brandingSettings.channel.defaultLanguage
    • brandingSettings.channel.keywords
    • brandingSettings.channel.trackingAnalyticsAccountId
    • brandingSettings.channel.unsubscribedTrailer
    • localizations.(key)
    • localizations.(key).title
    • localizations.(key).description
    • status.selfDeclaredMadeForKids

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

پاسخ

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

خطاها

جدول زیر پیام‌های خطایی را که ممکن است API در پاسخ به فراخوانی این روش برگرداند، مشخص می‌کند. برای جزئیات بیشتر، YouTube Data API - Errors را ببینید.

نوع خطا جزئیات خطا شرح
badRequest (400) brandingValidationError یکی از مقادیر در شیء brandingSettings درستی‌سنجی نشد. از روش channels.list برای بازیابی تنظیمات موجود کانال استفاده کنید و مقادیر دارایی را طبق رهنمودهای مستندات منبع channels به‌روز کنید.
badRequest (400) channelTitleUpdateForbidden هنگام به‌روزرسانی brandingSettings part کانال، باید مقدار دارایی brandingSettings.channel.title را روی عنوان فعلی کانال تنظیم کنید یا دارایی را حذف کنید. اگر مقدار دارایی را تغییر دهید، «میانای برنامه‌سازی کاربردی» خطا برمی‌گرداند.
badRequest (400) defaultLanguageNotSetError ‫defaultLanguage باید روی به‌روزرسانی localizations تنظیم شود.
badRequest (400) invalidBrandingOption یکی از تنظیمات نمانام‌سازی که مشخص کرده‌اید وجود ندارد. از روش channels.list برای بازیابی مقادیر معتبر استفاده کنید و حتماً آن‌ها را طبق دستورالعمل‌های موجود در سند منبع channels به‌روز کنید.
badRequest (400) invalidCustomMessage فراداده درخواست پیام سفارشی نامعتبری را مشخص می‌کند. مقدار دارایی invideoPromotion.items[].customMessage را در منبعی که درخواست ارسال کرده است بررسی کنید.
badRequest (400) invalidDuration فراداده درخواست مدت نامعتبری را در بخش invideoPromotion مشخص می‌کند.
badRequest (400) invalidDuration فراداده درخواست نوع موقعیت نامعتبری را برای تعیین نحوه قرارگیری مورد تبلیغ‌شده در پخش‌کننده ویدیو مشخص می‌کند. مقدار دارایی invideoPromotion.position.type را در منبعی که درخواست ارسال کرده است بررسی کنید.
badRequest (400) invalidRecentlyUploadedBy فراداده درخواست شناسه کانال نامعتبری را مشخص می‌کند. مقدار ویژگی invideoPromotion.items[].id.recentlyUploadedBy را در منبعی که درخواست ارسال کرده است بررسی کنید.
badRequest (400) invalidTimingOffset فراداده درخواست، یک انحراف زمان‌بندی نامعتبر را در بخش invideoPromotion مشخص می‌کند.
badRequest (400) invalidTimingOffset فراداده درخواست، انحراف زمان‌بندی نامعتبری را برای تعیین زمان نمایش مورد تبلیغ‌شده در پخش‌کننده ویدیو مشخص می‌کند. مقدار ویژگی invideoPromotion.timing.offsetMs را در منبعی که درخواست ارسال کرده است بررسی کنید.
badRequest (400) invalidTimingType فراداده درخواست، روش زمان‌بندی نامعتبری را برای تعیین زمان نمایش مورد تبلیغ‌شده در پخش‌کننده ویدیو مشخص می‌کند. مقدار دارایی invideoPromotion.timing.type را در منبعی که درخواست ارسال کرده است بررسی کنید.
badRequest (400) localizationValidationError یکی از مقادیر موجود در شیء بومی‌سازی‌ها اعتبارسنجی نشد. از روش channels.list برای بازیابی مقادیر معتبر استفاده کنید و مطمئن شوید که آن‌ها را طبق دستورالعمل‌های موجود در مستندات منبع کانال‌ها به‌روزرسانی کنید.
badRequest (400) tooManyPromotedItems تعداد عناصر تبلیغ‌شده مجاز در بخش invideoPromotion از حد مجاز فراتر رفته است.
forbidden (403) channelForbidden کانال مشخص‌شده در پارامتر id از درخواست پشتیبانی نمی‌کند یا درخواست به‌درستی مجاز نشده است.
forbidden (403) promotedVideoNotAllowed کانالی که درخواست API در تلاش برای به‌روزرسانی آن است، پیدا نشد. مقدار ویژگی id را در منبع channel که درخواست به آن ارسال شده است بررسی کنید تا مطمئن شوید شناسه کانال صحیح است.
forbidden (403) websiteLinkNotAllowed نشانی وب‌سایت مشخص‌شده مجاز نیست.
notFound (404) channelNotFound کانال مشخص‌شده در پارامتر id پیدا نشد.
notFound (404) channelNotFound کانال مشخص‌شده با پارامتر id پیدا نشد یا گزینه‌های نمانام‌سازی ندارد.
notFound (404) unknownChannelId شناسه کانال مشخص‌شده پیدا نشد.
notFound (404) unknownChannelId شناسه کانال recentlyUploadedBy مشخص‌شده پیدا نشد.
notFound (404) unknownVideoId شناسه ویدیو مشخص‌شده به‌عنوان عنصر تبلیغ‌شده پیدا نشد.
required (400) requiredItemIdType فراداده درخواست باید نوع مورد را در بخش invideoPromotion مشخص کند.
required (400) requiredItemId فراداده درخواست باید شناسه موردی را در بخش invideoPromotion مشخص کند.
required (400) requiredTimingOffset فراداده درخواست باید یک افست زمان‌بندی پیش‌فرض را مشخص کند تا YouTube بتواند تعیین کند که چه زمانی مورد تبلیغ‌شده را نمایش دهد. مقدار ویژگی invideoPromotion.defaultTiming.offsetMs را در منبعی که درخواست ارسال می‌کند تنظیم کنید.
required (400) requiredTimingOffset فراداده درخواست باید یک زمان‌بندی افست را مشخص کند تا YouTube بتواند تعیین کند که چه زمانی مورد تبلیغ‌شده را نمایش دهد. مقدار دارایی invideoPromotion.timing.offsetMs را در منبعی که درخواست ارسال می‌کند تنظیم کنید.
required (400) requiredTimingType فراداده درخواست باید یک روش زمان‌بندی را مشخص کند تا YouTube بتواند تعیین کند که مورد تبلیغ‌شده را چه زمانی نمایش دهد. مقدار ویژگی invideoPromotion.defaultTiming.type را در منبعی که درخواست ارسال می‌کند تنظیم کنید.
required (400) requiredTimingType فراداده درخواست باید روش زمان‌بندی را مشخص کند تا YouTube بتواند تعیین کند چه زمانی مورد تبلیغ‌شده را نمایش دهد. مقدار دارایی invideoPromotion.timing.type را در منبعی که درخواست ارسال می‌کند تنظیم کنید.
required (400) requiredTiming فراداده درخواست باید زمان‌بندی هر مورد در بخش invideoPromotion را مشخص کند.
required (400) requiredVideoId فراداده درخواست باید شناسه ویدیو را برای شناسایی مورد تبلیغ‌شده مشخص کند.
required (400) requiredWebsiteUrl فراداده درخواست باید نشانی وب‌سایت را در بخش invideoPromotion مشخص کند. مقدار ویژگی invideoPromotion.items[].id.websiteUrl را در منبعی که درخواست ارسال می‌کند تنظیم کنید.

امتحان کنید!

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