Channels: update

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

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

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

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

درخواست

درخواست HTTP

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

مجوز

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

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

مولفه های

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

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

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

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

درخواست بدن

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

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

    • 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

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

واکنش

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

خطاها

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

نوع خطا جزئیات خطا شرح
badRequest (400) brandingValidationError یکی از مقادیر موجود در شیء brandingSettings اعتبارسنجی ناموفق بود. از روش channels.list برای بازیابی تنظیمات موجود برای کانال استفاده کنید و مقادیر ویژگی ها را طبق دستورالعمل های موجود در مستندات منبع channels به روز کنید.
badRequest (400) channelTitleUpdateForbidden هنگام به‌روزرسانی brandingSettings part یک کانال، باید مقدار ویژگی brandingSettings.channel.title را روی عنوان فعلی کانال تنظیم کنید یا ویژگی را حذف کنید. اگر مقدار ویژگی را تغییر دهید، API یک خطا برمی‌گرداند.
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 شناسه کانال اخیراً آپلود شده توسط مشخص شده یافت نشد.
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 استفاده کنید.

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

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

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

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

درخواست

درخواست HTTP

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

مجوز

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

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

مولفه های

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

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

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

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

درخواست بدن

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

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

    • 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

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

واکنش

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

خطاها

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

نوع خطا جزئیات خطا شرح
badRequest (400) brandingValidationError یکی از مقادیر موجود در شیء brandingSettings اعتبارسنجی ناموفق بود. از روش channels.list برای بازیابی تنظیمات موجود برای کانال استفاده کنید و مقادیر ویژگی ها را طبق دستورالعمل های موجود در مستندات منبع channels به روز کنید.
badRequest (400) channelTitleUpdateForbidden هنگام به‌روزرسانی brandingSettings part یک کانال، باید مقدار ویژگی brandingSettings.channel.title را روی عنوان فعلی کانال تنظیم کنید یا ویژگی را حذف کنید. اگر مقدار ویژگی را تغییر دهید، API یک خطا برمی‌گرداند.
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 شناسه کانال اخیراً آپلود شده توسط مشخص شده یافت نشد.
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 استفاده کنید.