YouTube Content ID API - Revision History

توجه: YouTube Data API برای استفاده توسط شرکای محتوای YouTube درنظر گرفته شده است و برای همه توسعه‌دهندگان یا همه کاربران YouTube قابل‌دسترسی نیست. دسترسی به حساب «مدیر محتوای YouTube» نیاز دارد. اگر حساب «مدیر محتوای YouTube» دارید اما «میانای برنامه‌سازی کاربردی داده‌های YouTube» را به‌عنوان یکی از سرویس‌های فهرست‌شده در کنسول Google Cloud نمی‌بینید، با مدیر شریک یا پشتیبانی شریک اختصاصی خود تماس بگیرید.

این صفحه تغییرات YouTube Content ID API و به‌روزرسانی‌های اسناد را فهرست می‌کند.

‫۲۷ اوت ۲۰۲۶

‫YouTube شمارش بازدیدهای عمومی را برای همه قالب‌های ویدیو همسو خواهد کرد: ویدیوهای طولانی، «زنده»، و «کوته‌ویدیوها». YouTube بازدیدهای عمومی را از لحظه‌ای که ویدیو شروع به پخش می‌کند محاسبه خواهد کرد.

واجدشرایط بودن برای درآمدزایی و اکثر سنجه‌های عملکرد اصلی تحت تأثیر قرار نمی‌گیرند، زیرا همچنان به سنجه‌های تعامل متصل هستند. درآمد خالص محتواسازان همچنان براساس «بازدیدهای تعاملی کوته‌ویدیوها» و «ساعات تماشای تعاملی» خواهد بود که می‌توانید آن‌ها را در YouTube Analytics > حالت پیشرفته مشاهده کنید.

هیچ تغییری در واجدشرایط بودن «برنامه شریک YouTube» ایجاد نشده است. شرایط ورود به «برنامه شریک YouTube» نیز ازاین‌پس با عنوان «بازدیدهای واجدشرایط کوته‌ویدیوها» و «ساعات تماشای واجدشرایط» (قبلاً «بازدیدهای عمومی معتبر کوته‌ویدیوها» و «ساعات تماشای عمومی معتبر») شناخته خواهد شد.

برای کسب اطلاعات بیشتر، به درک عملکرد محتوای YouTube مراجعه کنید.

متریک وضعیت راه‌انداز استفاده‌شده برای
مشاهده به‌روزرسانی شد ویدیو از اولین قاب پخش می‌شود (شامل پخش خودکار، نگه داشتن اشاره‌گر روی آن، و کلیک/ضربه زدن برای پخش). تعداد بازدید عمومی استاندارد.
بازدید درگیرشده تغییر نکرده است بازپخش پس‌از قاب اول ادامه می‌یابد، یا کاربر برای پخش کلیک/تک‌ضرب می‌زند. درآمدزایی ازطریق «برنامه شریک YouTube»، اکثریت تحلیل‌های اصلی (نرخ کلیک‌گذری، میانگین مدت بازدید)، و گزارش تعامل.
ظهور ریزعکس تغییر نکرده است ریزعکس بدون تعامل یا پخش خودکار نمایش داده می‌شود. قرار گرفتن درمعرض و بسته‌بندی سطح فید را اندازه‌گیری می‌کند.

‫۴ اوت ۲۰۲۶

مستندات «میانای برنامه‌سازی کاربردی Content ID در YouTube» به‌روز شده است تا ترتیب عملیات هنگام به‌روزرسانی دارایی‌هایی که قبلاً متعلق به مالک محتوای دیگری است را روشن کند:

  • اگر دارایی قبلاً متعلق به مالک محتوای دیگری باشد، باید مالکیت خود را بااستفاده از ownership.update یا ownership.patch به دارایی اضافه کنید تا بتوانید فراداده یا خط‌مشی مطابقت آن را تنظیم یا به‌روز کنید.
  • اگر قبل‌از ادعای مالکیت، برای به‌روزرسانی فراداده (assets.update یا assets.patch) یا خط‌مشی مطابقت (assetMatchPolicy.update یا assetMatchPolicy.patch) اقدام کنید، درخواست با خطای PERMISSION_DENIED ناموفق می‌شود.
  • راهنمای به‌روزرسانی برچسب‌های دارایی با دستورالعمل‌های گام‌به‌گام برای افزودن برچسب به دارایی‌های متعلق به مالک محتوای دیگر به‌روز شده است.

‫۲۶ مارس ۲۰۲۵

از ۳۱ مارس ۲۰۲۵، YouTube نحوه شمارش بازدیدهای «کوته‌ویدیوها» را تغییر خواهد داد. در گذشته، برای «کوته‌ویدیوها»، بازدید پس‌از پخش «کوته‌ویدیو» برای تعداد مشخصی از ثانیه‌ها محاسبه می‌شد. اکنون بازدیدها برابر با تعداد دفعاتی خواهد بود که پخش یا بازپخش «کوته‌ویدیو» شما شروع می‌شود و حداقلی برای زمان تماشا وجود نخواهد داشت. بیشتر بدانید

تا ۳۰ ژوئن ۲۰۲۵، «میانای برنامه‌سازی کاربردی Content ID» طبق این تغییر به روش‌های زیر به‌روزرسانی خواهد شد:

  • claimSearch.list.sort ترتیب مرتب‌سازی‌اش به‌روز خواهد شد:
    • DAILY_ENGAGED_VIEWS برای تعداد بازدیدهای روزانه براساس روش قبلی شمارش بازدید اضافه خواهد شد.
    • LIFETIME_ENGAGED_VIEWS براساس روش قبلی شمارش بازدید به تعداد بازدیدهای کل اضافه خواهد شد.
  • ترتیب مرتب‌سازی assetSearch.list.sort به‌روز خواهد شد:
    • DAILY_ENGAGED_VIEWS برای شمارش بازدید روزانه براساس روش قبلی شمارش بازدید اضافه خواهد شد.

تا ۳۰ سپتامبر ۲۰۲۵، «میانای برنامه‌سازی کاربردی Content ID» طبق این تغییر به روش‌های زیر به‌روز خواهد شد:

  • ترتیب assetSearch.list.sort VIEWS منسوخ خواهد شد.
  • ترتیب مرتب‌سازی claimSearch.list.sort VIEW_COUNT منسوخ خواهد شد.
  • claimSearch.claimSnippet.videoViews به‌روزرسانی خواهد شد تا روش به‌روزشده شمارش بازدید برای بازدیدهای «کوته‌ویدیوها» را منعکس کند.
  • claimSearch.claimSnippet.engagedViews برای تعداد بازدیدها براساس روش قبلی شمارش بازدید اضافه خواهد شد

‫۱۴ ژانویه ۲۰۲۵

فیلد autoGeneratedBreaks[] منبع videoAdvertisingOption به‌روز شده است زیرا اکنون اجازه می‌دهیم ad_breaks و autoGeneratedBreaks هم‌زمان ارائه شوند. اگر autoGeneratedBreaks در ویدیویی با adBreaks تعریف‌شده روی درست تنظیم شود، سیستم‌های ما علاوه‌بر جایگاه‌های آگهی دستی‌تان، مکان‌های نمایش آگهی خودکار را تشخیص خواهند داد. برای جزئیات بیشتر، مقاله پشتیبانی را ببینید.

‫۱۰ نوامبر ۲۰۲۳

فیلد adFormats[] منبع videoAdvertisingOption به‌روزرسانی شده است تا third_party تنها مقدار معتبر برای آن فیلد باشد. قالب‌های آگهی زیر دیگر پشتیبانی نمی‌شوند: instream_trueview، instream_standard، display، preroll، postroll. برای جزئیات بیشتر، مقاله پشتیبانی را ببینید.

۱ ژوئن ۲۰۲۳

توجه: این یک اعلان منسوخ شدن است.

این به‌روزرسانی شامل تغییرات زیر است:

‫۲۰ دسامبر ۲۰۲۲

تعریف پارامتر پُرسمان ownershipRestriction روش assetSearch.list به‌روزرسانی شده است تا مشخص شود که اگر مقدار آن پارامتر none باشد، مقدار پارامتر metadataSearchFields نیز باید حداقل از یک فیلتر شناسه استفاده کند. این تغییر در مستندات نشان‌دهنده تغییر در رفتار «میانای برنامه کاربردی» نیست.

۹ نوامبر ۲۰۲۲

مستندات مربوط به روش‌های asset.get و asset.list به‌روز شده است تا نحوه پشتیبانی از مقادیر متعدد برای موارد زیر را روشن کند:

‫۲۸ سپتامبر ۲۰۲۲

اطلاعات قابلیت اخذ پروانه به asset resource اضافه شده است.

۱۸ ژوئیه ۲۰۲۲

مستندات روش claimSearch.list inactiveReasons به‌روز شده است تا بهبودهای مربوط به سازگاری با «استودیوِ YouTube» را منعکس کند:

  • «استودیو» قبلاً پشتیبانی از Audio Swap و Song Erase را برداشته بود. مقادیر API مربوطه، audio_removed و song_erased، بدون اطلاع نادیده گرفته شدند و اکنون غیرمستند شده‌اند.
  • channel_whitelisted با channel_allowlisted جایگزین شده است. مقدار قبلی دیگر مستند نیست اما همچنان پشتیبانی می‌شود.
  • اکنون مقادیر closed_disabled_monetization،‏ closed_manually، closed_no_adsense،‏ closed_own_video_match، reference_removed،‏ replaced، و video_modified پشتیبانی می‌شوند.

۱۴ ژوئن ۲۰۲۲

اسناد منبع assetSearch به‌روزرسانی شده است تا دو دارایی جدید را منعکس کند: isrcs[] و iswcs[]. مقادیر ویژگی جدید isrcs[] و iswcs[] هرکدام حاوی آرایه‌ای از مقادیر رشته‌ای هستند که هر مقدار یک ISRC یا ISWC را مشخص می‌کند، همان‌طور که مناسب است، که به دارایی شناسایی‌شده توسط نتیجه جستجو نگاشت می‌شود.

ویژگی‌های جدید نسبت‌به ویژگی‌های isrc و iswc که ازقبل در منابع assetSearch گنجانده شده‌اند توصیه می‌شوند، زیرا ویژگی‌های جدید داده‌های دقیق‌تری ارائه می‌دهند. درحالی‌که دارایی‌های جدید به‌طور بالقوه آرایه‌ای از مقادیر رشته‌ای را فهرست می‌کنند، دارایی‌های isrc و iswc هرکدام فقط یک کد ISRC یا ISWC مرتبط با نتیجه جستجو را شناسایی می‌کنند.

‫۱۲ مه ۲۰۲۲

پیوندهای کتابخانه‌های کارخواه به‌روزرسانی شدند تا به کتابخانه‌های کارخواه استاندارد Google APIs اشاره کنند. اتصال‌های ازپیش تولیدشده برای PHP به‌روزرسانی شد.

۳ مه ۲۰۲۲

پارامتر status روش claimSearch.list اکنون از فیلترهای بیشتری براساس جزئیات ادعای احتمالی پشتیبانی می‌کند.

‫۲ مه ۲۰۲۲

مستندات assetSearch.list روش پاسخ به‌روز شده است تا بهبودهای مربوط به سازگاری با AIP-158 را منعکس کند:

  • در شرح pageInfo.totalResults صراحتاً ذکر شده است که مقدار تخمینی است و مقدار واقعی نیست
  • فیلدهای pageInfo.resultsPerPage و pageInfo.startIndex برداشته شد

‫۲۵ آوریل ۲۰۲۲

مستندات منبع assetLabels.list به‌روزرسانی شده است تا معنی پارامترهای درخواست labelPrefix و q را روشن کند و مستند کند که درخواست / پاسخ از صفحه‌بندی پشتیبانی می‌کند.

‫۸ دسامبر ۲۰۲۱

اسناد منبع claimSearch.list به‌روز شده است تا دو مورد استفاده‌ای را که این روش پوشش می‌دهد به‌درستی نشان دهد:

  • جستجو براساس شناسه (دارایی، مرجع، یا ویدیو) یا رشته پُرسمان
  • جستجو براساس تاریخ ایجاد ادعا، تاریخ اصلاح، یا وضعیت

هر مورد استفاده از مجموعه متفاوتی از پارامترهای پُرسمان پشتیبانی می‌کند. مستندات روش claimSearch.list به‌روز شده است تا توضیح دهد کدام پارامترها برای هر مورد استفاده پشتیبانی می‌شوند.

‫۱۷ نوامبر ۲۰۲۱

این به‌روزرسانی شامل تغییرات زیر است:

  • روش claims.update اکنون از قابلیت به‌روزرسانی وضعیت ادعای غیرفعال یا بالقوه به active پشتیبانی می‌کند. تعریف دارایی claim در ویژگی status جزئیات بیشتری ارائه می‌دهد.
  • مستندات منابع claim و claimSearch به‌روز شده است تا اضافه شدن شیء جدید studioInfo را منعکس کند. این شیء حاوی پیوندهایی به صفحات «استودیوِ YouTube» مربوط به ادعا است.
  • فهرست مقادیر پشتیبانی‌شده برای پارامتر origin روش claimSearch.list تغییر کرده است. این پارامتر اکنون از چهار مقدار دیگر پشتیبانی می‌کند: batchTool، inProductShorts، melodyMatch، و youTubeAdmin. علاوه‌براین، مقادیر dropboxUpload و webUpload دیگر پشتیبانی نمی‌شوند.

‫۲۶ فوریه ۲۰۲۱

مستندات پارامتر videoId روش claimSearch.list به‌روز شده است تا ذکر شود که مقدار پارامتر اکنون حداکثر ۱۰ شناسه ویدیو جداشده با کاما را می‌پذیرد. اگر مقدار حاوی بیش‌از ۱۰ شناسه ویدیو باشد، میانای برنامه‌سازی کاربردی خطای badRequest — کد پاسخ HTTP 400 — را برمی‌گرداند.

۶ دسامبر ۲۰۱۸

توجه: این یک اعلان منسوخ شدن است.

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

۲۱ مارس ۲۰۱۸

این به‌روزرسانی شامل تغییرات زیر است:

  • اکنون هر زمان که دارایی نماهنگ یا صدای ضبط‌شده‌ای را درج، به‌روزرسانی، یا وصله می‌کنید، باید دارایی metadataMine.artist تنظیم شود. اگر این ویژگی برای آن نوع منابع تنظیم نشده باشد، اکنون میانای برنامه‌سازی کاربردی خطایی برمی‌گرداند. علاوه‌براین، توجه داشته باشید که ویژگی metadataMine.artist فقط برای هنرمندان نماهنگ و صدای ضبط‌شده پشتیبانی می‌شود.

۲۴ ژوئیه ۲۰۱۷

این به‌روزرسانی شامل تغییرات زیر است:

  • منبع جدید package نشان‌دهنده گروهی از فایل‌ها است که ازطریق وب، SFTP، یا سازوکار ارسال دیگری ارسال شده‌اند. این API از دو روش برای این منبع پشتیبانی می‌کند:

    • روش package.insert یک بسته فقط فراداده را که دقیقاً حاوی یک فایل فراداده است، اعتبارسنجی و بارگذاری می‌کند.
    • روش package.get اطلاعات مربوط به بسته‌ای را که قبلاً بارگذاری شده است بازیابی می‌کند.

  • برای روش validator.validate، تعریف دارایی uploaderName به‌روز شده است تا مشخص شود که مقدار، شریک محتوایی را که داده‌ها را بارگذاری می‌کند شناسایی نمی‌کند، بلکه مقداری مانند web-google یا yt-google را شناسایی می‌کند که حساب بارگذارنده خاصی را که مالک محتوا استفاده می‌کند مشخص می‌کند.

  • دارایی status reference دیگر از مقدار duplicate_on_hold برای نشان دادن اینکه مرجع تکراری مرجع دیگری است استفاده نمی‌کند. درعوض، اگر مرجعی تکراری باشد، مقدار دارایی status اکنون روی inactive تنظیم می‌شود و مقدار دارایی statusReason برابر با REASON_DUPLICATE_FOR_OWNERS است.

    بااین‌حال، مانند قبل، دارایی duplicateLeader منبع فقط درصورتی تکمیل می‌شود که مرجع تکراری باشد. اگر تنظیم شده باشد، مقدار آن ویژگیْ مرجع تکراری را شناسایی می‌کند.

‫۱۷ آوریل ۲۰۱۷

این به‌روزرسانی شامل تغییرات زیر است:

  • منبع جدید assetShare که فقط به دارایی‌های آهنگ‌سازی مربوط است، رابطه‌ای را بین دو نمایش از منبع دارایی شناسایی می‌کند. این نمایش‌ها منعکس‌کننده مدل داده انتشار جدیدی هستند که برای ارائه شفافیت بیشتر و کنترل بیشتر بر نحوه ارتباط حقوق شما با دارایی‌های صدای ضبط‌شده طراحی شده است.

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

    علاوه‌براین، هر مالک قطعه موسیقی دارایی سهم قطعه موسیقی خودش را دارد. سهم آهنگ‌سازی نشان‌دهنده اطلاعاتی است که یک ناشر خاص برای یک دارایی آهنگ‌سازی ارائه کرده است. دارایی سهم آهنگ‌سازی می‌تواند با بسیاری از صداهای ضبط‌شده مرتبط باشد.

    منبع assetShare رابطه‌ای را بین نمای ترکیب‌بندی و سهم ترکیب‌بندی شناسایی می‌کند. روش جدید assetShares.list به شما امکان می‌دهد یکی از کارهای زیر را انجام دهید:

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

  • راهنمای جدید مدیریت دارایی‌های قطعه موسیقی توضیح می‌دهد که چگونه روش‌های مختلف API درخواست‌ها را بسته به اینکه شناسه‌های دارایی ارسال‌شده به آن روش‌ها نماهای قطعه موسیقی یا سهام قطعه موسیقی را شناسایی می‌کنند، مدیریت می‌کنند.

  • دارایی جدید claimedVideoOptions.autoGeneratedBreaks منبع contentOwnerAdvertisingOptions نشان می‌دهد که آیا YouTube باید به‌طور خودکار وقفه آگهی در ویدیوهای ادعاشده که بیش از ۱۰ دقیقه طول دارند ایجاد کند یا نه. اگرچه این دارایی بر تمام ویدیوهای مالک محتوا که بیش از ۱۰ دقیقه طول دارند تأثیر می‌گذارد، اما اگر یک ویدیو دارای چندین ادعا باشد، اولین شریکی که ادعای مالکیت ویدیو را مطرح می‌کند، رفتار پیش‌فرض این دارایی را در رابطه با آن ویدیو تعیین می‌کند.

۱۱ اوت ۲۰۱۶

این به‌روزرسانی شامل تغییرات زیر است:

  • «شرایط خدمات خدمات API YouTube» که به‌تازگی منتشر شده است («شرایط به‌روزشده») و در وبلاگ مهندسی و توسعه‌دهندگان YouTube به‌طور مفصل درباره آن بحث شده است، مجموعه کاملی از به‌روزرسانی‌ها را برای «شرایط خدمات» فعلی ارائه می‌دهد. علاوه‌بر شرایط به‌روزشده که از تاریخ ۱۰ فوریه ۲۰۱۷ اجرایی خواهد شد، این به‌روزرسانی شامل چندین سند پشتیبان است که به توضیح خط‌مشی‌هایی که توسعه‌دهندگان باید از آن‌ها پیروی کنند کمک می‌کند.

    مجموعه کامل اسناد جدید در سابقه بازبینی «شرایط به‌روزشده» شرح داده شده است. علاوه‌براین، تغییرات آتی در «شرایط به‌روزشده» یا اسناد پشتیبان نیز در آن سابقه بازبینی توضیح داده خواهد شد. می‌توانید ازطریق پیوندی در آن سند، در فید RSS که تغییرات آن سابقه ویرایش را فهرست می‌کند مشترک شوید.

May 31, 2016

این به‌روزرسانی شامل تغییرات زیر است:

  • منابع و روش‌های جدید

    • روش جدید validator.validate به شما امکان می‌دهد تعیین کنید که آیا یک فایل فراداده حاوی خطاهای اعتبارسنجی است که مانع از پردازش موفقیت‌آمیز آن توسط YouTube می‌شود یا خیر. اگر فایل حاوی خطا باشد، دارایی errors در پاسخ API حاوی فهرستی از خطاهای اعتبارسنجی است که شدت، علت، و مکان هر خطا را مشخص می‌کند.

  • خطاهای جدید و به‌روزشده

    • روش‌های assets.patch و assets.update اکنون از خطای زیر پشتیبانی می‌کنند. به‌عنوان یادآوری، یک روش می‌تواند از چندین خطا با نوع خطای یکسان پشتیبانی کند. برای فهرست کامل خطاهای احتمالی، لطفاً به اسناد خطا برای هر روش یا به صفحه خطاها مراجعه کنید.

      خطاها
      invalidValue (400) parameters.assetId
      درخواست ناموفق بود زیرا دارایی‌ای که درحال به‌روزرسانی است با دارایی دیگری ادغام شده است. درخواست را بااستفاده از شناسه آن دارایی که در پیام خطا برگردانده شده است به‌عنوان مقدار پارامتر assetId دوباره ارسال کنید.

‫۲۸ مارس ۲۰۱۶

این به‌روزرسانی شامل تغییرات زیر است:

  • به‌روزرسانی منابع و روش‌های موجود

    • ویژگی جدید matchInfo.matchSegments[] منبع claim حاوی فهرستی است که در آن هر مورد بخشی از ویدیو ادعاشده را توصیف می‌کند که با قسمتی از ویدیو مرجع مطابقت دارد. یک ادعا می‌تواند چندین بخش منطبق داشته باشد. برای مثال، اگر محتوای صوتی و ویدیویی یک ویدیو بارگذاری‌شده با یک ویدیو مرجع مطابقت داشته باشد، دو بخش مطابقت وجود خواهد داشت. یک بخش تطابق صوتی را توصیف می‌کند و بخش دیگر تطابق ویدیویی را توصیف می‌کند.

      برای هر بخش مطابقت، API مدت زمان و نوع (صوتی یا ویدیویی) محتوای مطابقت‌داده‌شده را برمی‌گرداند. این API همچنین زمان‌های شروع و پایان هر بخش تطبیق در ویدیو ادعاشده و ویدیو مرجع را شناسایی می‌کند.

    • اکنون می‌توانید مقدار دارایی claimedVideoOptions.newVideoDefaults[] منبع contentOwnerAdvertisingOptions را هنگام فراخوانی روش‌های contentOwnerAdvertisingOptions.patch یا contentOwnerAdvertisingOptions.update به‌روز کنید.

    • دارایی contentOwnerAdvertisingOptions فقط خواندنی allowedOptions.autoGeneratedBreaks منسوخ شده است.

  • خطاهای جدید و به‌روزشده

    • روش claims.update در «میانای برنامه‌سازی کاربردی» اکنون از خطای زیر پشتیبانی می‌کند. به‌عنوان یادآوری، یک روش می‌تواند از چندین خطا با نوع خطای یکسان پشتیبانی کند. برای فهرست کامل خطاهای احتمالی، لطفاً به اسناد خطا برای هر روش یا به صفحه خطاها مراجعه کنید.

      خطاها
      badRequest (400) alreadyClaimed
      این ادعای مالکیت تکراری از ادعای مالکیت موجود دیگری است و نمی‌تواند به‌روز شود.

    • روش assets.list گاهی‌اوقات مهلتش تمام می‌شود و کد پاسخ‌های HTTP 500 (Internal Server Error) را برمی‌گرداند، به‌ویژه زمانی که درخواست داده‌ها را برای دارایی‌های زیادی بازیابی می‌کند و مقدار پارامتر fetchMatchPolicy effective است. اگر درخواست assets.list شما چندین شناسه دارایی را مشخص می‌کند و خطای 500 را برمی‌گرداند، سعی کنید درخواست را برای یک دارایی یا تعداد کمتری از دارایی‌ها دوباره ارسال کنید.

    • سند خطای references.insert به‌روزرسانی شده است تا اشاره کند که اگر درخواست، فایل مرجع خرابی را بارگذاری کند، این مشکل تا زمانی که خود مرجع پردازش نشود شناسایی نمی‌شود. بنابراین، حتی اگر درخواست references.insert پاسخ موفقی را برگرداند، ممکن است مرجع باموفقیت پردازش نشود. توصیه می‌کنیم که پس‌از درج مرجع، بااستفاده از روش references.list نظرسنجی کنید تا مطمئن شوید که مرجع طبق انتظار فعال شده است.

‫۳ فوریه ۲۰۱۶

این به‌روزرسانی شامل تغییرات زیر است:

  • به‌روزرسانی منابع و روش‌های موجود

    • این API اکنون از آگهی‌های فهرستگان محصولات پشتیبانی می‌کند. آگهی‌های فهرستگان محصولات، محصولاتی را که با محتوای ویدیو مرتبط هستند یا در آن نمایش داده می‌شوند برجسته می‌کنند. این آگهی‌ها کارت‌های دارای حامی مالی هستند که درطول ویدیو نمایش داده می‌شوند. کارت‌ها به‌طور خودکار توسط سیستم آگهی اضافه می‌شوند. بینندگان برای چند ثانیه یک برچسب تبلیغ برای کارت می‌بینند و همچنین می‌توانند روی نماد در گوشه بالا سمت راست ویدیو کلیک کنند تا کارت‌های ویدیو را مرور کنند.

      درنتیجه این تغییر، اکنون می‌توان product_listing را در مقادیر ویژگی‌های زیر گنجاند:

      روش منبع/میانای برنامه‌سازی کاربردی دارایی
      contentOwnerAdvertisingOptions allowedOptions.licAdFormats[]
      contentOwnerAdvertisingOptions allowedOptions.ugcAdFormats[]
      contentOwnerAdvertisingOptions claimedVideoOptions.newVideoDefaults[]
      videoAdvertisingOptions adFormats[]
      videoAdvertisingOptions.getEnabledAds countriesRestriction[].adFormats[]

    • createdBefore و createdAfter جدید روش assetSearch.list به API دستور می‌دهند که فقط دارایی‌های ایجادشده قبل و/یا بعداز تاریخ خاصی را برگرداند.

    • در پاسخ میانای برنامه‌سازی کاربردی به درخواست assetSearch.list، ویژگی type اکنون از مقدار art_track_video پشتیبانی می‌کند. مرکز راهنمایی YouTube اطلاعات بیشتری درباره ویدیوهای نماهنگ هنری ارائه می‌دهد.

    • روش claimSearch.list از پارامترهای جدید زیر پشتیبانی می‌کند:

      پارامترها
      referenceId این پارامتر فیلتر شناسه مرجع YouTube مرجعی را که برای آن ادعاها را بازیابی می‌کنید، مشخص می‌کند.
      inactiveReasons این پارامتر اختیاری به شما امکان می‌دهد پاسخ میانای برنامه‌سازی کاربردی را محدود کنید تا فقط شامل ادعاهای غیرفعال براساس دلایل مشخصی باشد که ادعاها غیرفعال شده‌اند. تعریف پارامتر انواع ادعاهای غیرفعالی را که می‌توانید جستجو کنید فهرست می‌کند.
      partnerUploaded این پارامتر اختیاری بولی به شما امکان می‌دهد مشخص کنید که پاسخ API باید فقط شامل ادعاهای بارگذاری‌شده توسط شریک یا ادعاهای بارگذاری‌شده توسط غیرشریک باشد.

    • شیء references#origination جدید منبع reference حاوی اطلاعاتی است که منبع مرجع را توصیف می‌کند.

    • روش references.insert اکنون از قابلیت بارگذاری مرجع‌های تولیدشده بااستفاده از نرم‌افزار gfp_gen متعلق به YouTube پشتیبانی می‌کند. اگر اثر انگشت ازپیش تولیدشده ارائه می‌دهید، مقدار ویژگی fpDirect را در منبع reference بارگذاری‌شده روی true تنظیم کنید.

      توجه داشته باشید که با این تغییر، اگر هنگام بارگذاری مرجع سعی کنید ویژگی fpDirect را تنظیم کنید، API دیگر خطا برنمی‌گرداند.

  • خطاهای جدید و به‌روزشده

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

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

    خطاها
    badRequest (400) inappropriateCampaignTarget
    اگر پویشی تلاش کند ویدیویی را که ممکن است برای برخی‌از کاربران نامناسب باشد نمایش دهد، روش‌های campaigns.insert و campaigns.update این خطا را برمی‌گردانند. برای رفع این خطا، لطفاً محتوای دیگری را برای نمایش ویژه انتخاب کنید.
    badRequest (400) canNotCreatePartnerUploadedClaimOnCompositionOrSoundRecordingAssets
    اگر بخواهید با دارایی قطعه هنری یا صدای ضبط‌شده ادعای بارگذاری‌شده شریک ایجاد کنید، روش claims.insert این خطا را برمی‌گرداند.
    badRequest (400) existingSoundRecordingOrMusicVideoClaim
    اگر ادعایی ازقبل برای موسیقی ضبط‌شده در ویدیو مشخص‌شده وجود داشته باشد، روش claims.insert این خطا را برمی‌گرداند. ادعاهای ترکیب‌بندی مستقیم را نمی‌توان ازطریق میانای برنامه‌سازی کاربردی اضافه کرد.
    badRequest (400) asset_id
    اگر درخواست تلاش کند مرجعی را ازطریق فایل ایجاد کند اما درخواست assetId را مشخص نکند، روش references.insert این خطا را برمی‌گرداند.
    badRequest (400) canNotBeActivated
    اگر مرجع فعال نشود، احتمالاً به‌دلیل وضعیت مرجع یا شرایط مالکیت، روش references.update این خطا را برمی‌گرداند.
    badRequest (400) videoNotClaimed
    اگر ادعای مالکیت ویدیویی را که می‌خواهید گزینه‌های تبلیغاتی آن را بازیابی کنید نکرده باشید، روش videoAdvertisingOptions.get این خطا را برمی‌گرداند و درنتیجه اطلاعات درخواستی برای شما دردسترس نخواهد بود.

‫۱۸ دسامبر ۲۰۱۵

طبق قوانین اتحادیه اروپا (EU)، باید شفاف‌سازی‌های خاصی به کاربران نهایی در اتحادیه اروپا ارائه شود و موافقت آن‌ها کسب شود. بنابراین، برای کاربران نهایی در اتحادیه اروپا، باید از خط‌مشی رضایت کاربر اتحادیه اروپا پیروی کنید. اعلان این الزام را به شرایط خدمات YouTube API اضافه کرده‌ایم.

۲۱ آوریل ۲۰۱۵

این به‌روزرسانی شامل تغییرات زیر است:

  • منبع جدید campaign نشان‌دهنده یک پویش مالک محتوا خاص است که به مالک محتوا اجازه می‌دهد از گل‌نویسی‌ها برای تبلیغ محتوا در ویدیوهای ادعاشده و بارگذاری‌شده توسط کاربر استفاده کند. برای مثال، مالک محتوا می‌تواند پویشی ایجاد کند که پیوندهایی به صفحه تماشای فیلم برای هر ویدیو بارگذاری‌شده توسط کاربر که ادعای مالکیت شده و حاوی صحنه‌هایی از آن فیلم است اضافه کند.

    این میانای برنامه‌سازی کاربردی از روش‌های get، list، insert، update، patch، و delete منابع campaign پشتیبانی می‌کند.

  • این «میانای برنامه‌سازی کاربردی» از چندین خطای جدید برای روش‌های جدید campaigns.get، campaigns.insert، campaigns.update، و campaigns.delete پشتیبانی می‌کند.

‫۳۰ مارس ۲۰۱۵

این به‌روزرسانی شامل تغییرات زیر است:

  • به‌روزرسانی منابع و روش‌های موجود

    • پارامتر جدید isrcs روش assetSearch.list به شما امکان می‌دهد فهرستی از حداکثر ۵۰ کد ISRC را مشخص کنید. پاسخ میانای برنامه‌سازی کاربردی شامل دارایی‌های مرتبط با آن ISRCها خواهد بود.

    • دارایی claimHistory در منبع event[].reason از مقادیر جدید زیر پشتیبانی می‌کند. هر دلیل توضیح می‌دهد که چرا رویداد خاصی دررابطه‌با ادعا رخ داده است:

      • closed_audio_claim_on_visual_reference
      • closed_partner_exclusion
      • closed_reference_conflict

    • پارامتر جدید sort در روش claimSearch.list روشی را مشخص می‌کند که برای سفارش منابع در پاسخ میانای برنامه‌سازی کاربردی استفاده خواهد شد. به‌طور پیش‌فرض، منابع براساس تاریخ ایجادشان به‌ترتیب زمانی معکوس (از جدیدترین به قدیمی‌ترین) مرتب می‌شوند. همچنین می‌توانید منابع را براساس بیشترین تا کمترین تعداد بازدید برای محتوای ادعاشده مرتب کنید.

      توجه داشته باشید که اگر درخواست claimSearch.list مقدار پارامتر status را نیز روی appealed، disputed، pending، potential، یا routedForReview تنظیم کند، نتایج براساس زمان انقضای دوره بازبینی دعوی مرتب می‌شوند.

    • روش‌های ownership.update و ownership.patch اکنون همه دارایی‌هایی را که می‌توانند هنگام فراخوانی این روش‌ها به‌روز شوند به‌درستی فهرست می‌کنند. این تغییر نشان‌دهنده اصلاح اسناد میانای برنامه‌سازی کاربردی است و تغییر در عملکرد میانای برنامه‌سازی کاربردی را نشان نمی‌دهد.

    • پارامترهای fetchMatchPolicy برای روش‌های assets.get و assets.list اکنون effective را به‌عنوان مقدار پشتیبانی‌شده فهرست می‌کنند. این مقدار به سرور API دستور می‌دهد تا خط‌مشی تطبیقی را که YouTube برای دارایی اعمال می‌کند، بازیابی کند.

    • اکنون در پارامترهای id برای روش‌های assets.list، claims.list، contentOwners.list، policies.list، publishers.list، و references.list ذکر شده است که مقادیر پارامتر آن‌ها می‌تواند حداکثر حاوی ۵۰ شناسه جداشده با کاما باشد.

  • خطاهای جدید و به‌روزشده

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

    برای اطلاعات بیشتر، لطفاً به مستندات خطا برای هر روش یا به صفحه خطاها مراجعه کنید.

    نوع خطا جزئیات خطا شرح
    badRequest (400) tooManyIsrcs اگر پارامتر isrcs بیش‌از ۵۰ شناسه ISRC را مشخص کند، روش assetSearch.list این خطا را برمی‌گرداند.
    badRequest (400) videoIsPrivate اگر بخواهید برای ویدیویی خصوصی ادعای مالکیت کنید، روش claims.insert این خطا را برمی‌گرداند. فقط درصورتی می‌توانید برای ویدیو ادعای مالکیت کنید که وضعیت حریم خصوصی آن public یا unlisted باشد.
    notModified (304) blockOutsideOwnershipUnchanged اگر پرچم blockOutsideOwnership در دعوی باموفقیت اصلاح نشده باشد، روش claims.update این خطا را برمی‌گرداند. دلایل متعددی وجود دارد که ممکن است این خطا رخ دهد. یک مثال رایج این است که اصلاح مشخص‌شده هیچ تأثیری بر ویدیو مورد ادعا ندارد.

۷ نوامبر ۲۰۱۴

این به‌روزرسانی شامل تغییرات زیر است:

  • به‌روزرسانی منابع و روش‌های موجود

    • پارامتر status روش claimSearch.list اکنون از مقدار routedForReview پشتیبانی می‌کند. این مقدار نتایج را به ادعاهایی محدود می‌کند که براساس قانونی در خط‌مشی انطباق دارایی به بازبینی دستی نیاز دارند.

    • ویژگی event[].reason منبع claimHistory از مقادیر جدید زیر پشتیبانی می‌کند. هر دلیل توضیح می‌دهد که چرا رویداد خاصی دررابطه‌با ادعا رخ داده است:

      • closed_invalid_reference_segment
      • closed_noadsense
      • suspended_monetization_on_channel
      • video_content_modified

    • دارایی origin.source منبع claim که منبع یک ادعا را مشخص می‌کند، اکنون از مقدار melodyMatch پشتیبانی می‌کند. ادعای مالکیت مطابقت ملودی نشان می‌دهد که ویدیو ادعاشده دارای قطعه موسیقی مشترک با مرجع است.

    • مستندات روش references.insert به‌روز شده است تا به‌درستی نشان دهد که این API از دو نقطه پایانی متفاوت برای آن روش استفاده می‌کند. این تغییر نشان‌دهنده تغییر در عملکرد API نیست، بلکه اصلاحیه‌ای برای اسناد موجود است.

      • اگر درخواست بارگذاری فایل مرجع جدیدی است، نقطه پایانی صحیح عبارت است از:

        POST https://www.googleapis.com/upload/youtube/partner/v1/references

      • اگر درخواست درحال ایجاد مرجعی بااستفاده از ویدیو ادعاشده به‌عنوان محتوای مرجع باشد، نقطه پایانی صحیح عبارت است از:

        POST https://www.googleapis.com/youtube/partner/v1/references

  • خطاهای جدید و به‌روزشده

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

    برای اطلاعات بیشتر، لطفاً به اسناد خطا برای هر روش یا به صفحه خطاها مراجعه کنید.

    نوع خطا جزئیات خطا شرح
    badRequest (400) invalidLabelName اگر نام برچسب دارایی نامعتبر باشد، روش‌های assets.insert، assets.update، و assetLabels.insert این خطا را برمی‌گردانند. نام برچسب‌ها باید بین دو تا ۳۰ نویسه باشد. نام‌های برچسب نباید شامل براکت‌های زاویه‌دار، ویرگول، دونقطه، علامت «&»، یا کاراکتر پایپ عمودی (|) باشند.
    badRequest (400) ownerHaveMaximumNumberOfLabels اگر مالک محتوا قبلاً ۲۵۰۰ برچسب دارایی منحصربه‌فرد تعریف کرده باشد، که حداکثر تعداد مجاز فعلی است، روش‌های assets.insert، assets.update، و assetLabels.insert این خطا را برمی‌گردانند.
    badRequest (400) tooManyLabelsOnOneAsset اگر دارایی ازقبل با ۳۰ برچسب دارایی مرتبط باشد، روش‌های assets.insert و assets.update این خطا را برمی‌گردانند. این تعداد حداکثر تعداد مجاز فعلی است.
    badRequest (400) channelMonetizationSuspended اگر کانال ویدیو به‌دلیل ادعاهای شریک تعلیق شده باشد، روش‌های claims.insert و claims.update این خطا را برمی‌گردانند.
    badRequest (400) channelNotActive اگر کانال ویدیو فعال نباشد، روش claims.update این خطا را برمی‌گرداند.

  • اگر منبع در بدنه درخواست حاوی دارایی metadataMine.contentType نباشد، روش‌های assets.insert و assets.update دیگر خطای badRequest را برای برخی‌از دارایی‌ها برنمی‌گردانند.

۲۳ سپتامبر ۲۰۱۴

این به‌روزرسانی شامل تغییرات زیر است:

  • تغییرات شناسه مالک محتوا

    تغییرات شناسه مالک محتوا که در تاریخ ۹ ژوئیه ۲۰۱۴ در سابقه ویرایش اعلام شده بود، اجرایی شده است. در نتیجه این تغییر، اکنون API یک شناسه یکتای تولیدشده را برای شناسایی مالک محتوای مرتبط با کاربر اصیل‌سازی‌شده یا منبع مدیریت‌شده ازطریق API برمی‌گرداند. قبلاً، این API نامی قابل‌خواندن توسط انسان را به‌عنوان شناسه برمی‌گرداند، مثل «qrs_network».

    این تغییر بر عملکرد API زیر تأثیر می‌گذارد و احتمالاً بر شرکایی که «کدهای شریک» را در برنامه‌هایشان کدبندی سخت کرده‌اند تأثیر خواهد گذاشت.

    • اکنون API شناسه جدید را به‌عنوان مقدار دارایی‌های منبعی که قبلاً «کد شریک» را برمی‌گرداندند، مثل دارایی id منبع contentOwner، برمی‌گرداند.
    • همه روش‌های میانای برنامه‌سازی کاربردی از پارامتر onBehalfOfContentOwner پشتیبانی می‌کنند که مالک محتوایی را که درخواست میانای برنامه‌سازی کاربردی ازطرف او انجام می‌شود شناسایی می‌کند. پس‌از این تغییر، پارامتر باید به‌جای «کد شریک» روی شناسه جدید تنظیم شود. برای جلوگیری از خرابی کد، پارامتر درطول دوره انتقال هر دو مقدار را می‌پذیرد.
    • پس‌از این تغییر، پارامتر contentOwnerId روش contentOwners.list باید شناسه جدید را به‌جای «کد شریک» مشخص کند.

  • به‌روزرسانی‌های منابع و روش‌های موجود

    • پارامتر جدید metadataSearchFields روش assetSearch.list به شما امکان می‌دهد فیلدهای فراداده دارایی را که می‌خواهید جستجو کنید و همچنین مقادیری را که می‌خواهید در آن فیلدها جستجو کنید مشخص کنید. مقدار پارامتر فهرستی از جفت‌های فیلد و مقدار است که با کاما از هم جدا شده‌اند؛ در هر جفت، فیلد و مقدار با دونقطه از هم جدا شده‌اند.

    • شیء appliedPolicy جدید منبع claim خط‌مشی‌ای را که YouTube واقعاً برای ادعا اعمال می‌کند مشخص می‌کند. مقدار شیء یک منبع policy است. آن منبع حاوی اطلاعات خط‌مشی برای کشورهایی است که مالک محتوایی که درخواست را ارسال کرده است، مالک دارایی ادعاشده است.

      خط‌مشی اعمال‌شده می‌تواند از خط‌مشی‌ای که مالک محتوا تعریف کرده است به دو روش متفاوت باشد:

      1. این خط‌مشی‌ها توسط مالکان دیگری تنظیم شده‌اند که مالکیت جزئی دارایی ادعاشده را در برخی‌از قلمروهای مشابه با مالک محتوایی که درخواست API را ارسال کرده است، دارند.

      2. این موضوع خط‌مشی‌های اداری YouTube را که در قلمروهایی که مالک محتوا مالک دارایی ادعاشده است اعمال می‌شود، درنظر می‌گیرد.

    • ویژگی جدید uploaderChannelId منبع claimHistory شناسه کانال کانالی را که ویدیو ادعاشده در آن بارگذاری شده است شناسایی می‌کند.

۸ سپتامبر ۲۰۱۴

این به‌روزرسانی شامل تغییرات زیر است:

  • منابع و روش‌های جدید

    • منبع جدید assetLabel برچسب نوشتاری را شناسایی می‌کند که می‌تواند به دارایی اختصاص داده شود. برچسب‌های دارایی به شما امکان می‌دهند دارایی‌ها را در دسته‌بندی‌های سفارشی قرار دهید و کتابخانه دارایی‌های خود را آسان‌تر سازمان‌دهی کنید. می‌توانید دارایی‌ها را براساس برچسب‌هایشان جستجو کنید، که این کار می‌تواند موارد استفاده‌ای را که نیاز به به‌روزرسانی گروه‌های خاصی از دارایی‌ها دارند نیز ساده‌تر کند.

      • روش assetLabels.list به شما امکان می‌دهد فهرستی از برچسب‌های مالک محتوا را بازیابی کنید.
      • روش assetLabels.insert به شما امکان می‌دهد برچسب دارایی جدیدی ایجاد کنید. همچنین می‌توانید با فراخوانی روش assets.update و به‌روزرسانی برچسب‌های دارایی، برچسب‌های جدیدی ایجاد کنید. سرور میانای برنامه‌سازی کاربردی به‌طور خودکار منبع assetLabel جدیدی برای هر برچسبی که قبلاً تعریف نشده است ایجاد می‌کند.

  • به‌روزرسانی‌های منابع و روش‌های موجود

    • دارایی asset منبع label[] به‌روزرسانی شده است تا توجه داشته باشید که می‌توانید روش assets.update را برای به‌روزرسانی برچسب‌های دارایی فراخوانی کنید. اما هنگام فراخوانی روش assets.insert نمی‌توانید برچسب‌های دارایی را تنظیم کنید.

      راهنمای جدید استفاده از برچسب‌های دارایی نحوه ایجاد و بازیابی برچسب‌های دارایی و همچنین نحوه به‌روزرسانی برچسب‌های دارایی یا جستجوی دارایی‌های مرتبط با برچسب‌های خاص را توضیح می‌دهد.

  • خطاهای جدید و به‌روزشده

    این «میانای برنامه‌سازی کاربردی» از چندین خطای جدید برای روش‌های جدید assetLabels.list و assetLabels.insert پشتیبانی می‌کند.

۹ ژوئیه ۲۰۱۴

این به‌روزرسانی شامل تغییرات زیر است:

  • تغییرات شناسه مالک محتوا

    ازنظر تاریخی، «میانای برنامه‌سازی کاربردی» از «کد شریک» قابل‌خواندن توسط انسان، مانند «qrs_network»، برای شناسایی منحصربه‌فرد مالک محتوای مرتبط با کاربر اصالت‌سنجی‌شده یا منبع مدیریت‌شده ازطریق «میانای برنامه‌سازی کاربردی» استفاده کرده است. در سه‌ماهه سوم سال ۲۰۱۴، API به‌جای آن از یک شناسه ۲۲ کاراکتری منحصربه‌فرد برای شناسایی مالکان محتوا استفاده خواهد کرد. این تغییر بر عملکرد API زیر تأثیر می‌گذارد و احتمالاً بر شرکایی که «کدهای شریک» را در برنامه‌هایشان کدبندی سخت کرده‌اند تأثیر خواهد گذاشت.

    • این API شناسه ۲۲ کاراکتری را به‌عنوان مقدار دارایی‌های منبعی که قبلاً «کد شریک» را برمی‌گرداندند، مثل دارایی id منبع contentOwner برمی‌گرداند.
    • همه روش‌های میانای برنامه‌سازی کاربردی از پارامتر onBehalfOfContentOwner پشتیبانی می‌کنند که مالک محتوایی را که درخواست میانای برنامه‌سازی کاربردی ازطرف او انجام می‌شود شناسایی می‌کند. پس‌از تغییر، پارامتر باید روی شناسه ۲۲ نویسه‌ای به‌جای «کد شریک» تنظیم شود. برای جلوگیری از خرابی کد، پارامتر درطول دوره انتقال هر دو مقدار را می‌پذیرد.
    • پس‌از این تغییر، پارامتر contentOwnerId روش contentOwners.list باید شناسه ۲۲ نویسه‌ای را به‌جای «کد شریک» مشخص کند.

  • به‌روزرسانی‌های منابع و روش‌های موجود

    • منبع asset اکنون از ویژگی label پشتیبانی می‌کند که فهرستی از برچسب‌های دارایی مرتبط با دارایی را مشخص می‌کند. می‌توانید برچسبی را به چندین دارایی اعمال کنید تا آن‌ها را گروه‌بندی کنید. می‌توانید از برچسب‌ها به‌عنوان فیلترهای جستجو برای انجام به‌روزرسانی‌های انبوه، بارگیری گزارش‌ها، یا فیلتر کردن YouTube Analytics استفاده کنید.

    • روش assetSearch.list اکنون از پارامترهای اختیاری زیر پشتیبانی می‌کند:

      • labels: نتایج را محدود می‌کند تا فقط شامل دارایی‌هایی باشد که با برچسب‌های مشخص‌شده مرتبط هستند. به‌طور پیش‌فرض، «میانای برنامه‌سازی کاربردی» دارایی‌هایی را برمی‌گرداند که با همه برچسب‌های مشخص‌شده مطابقت داشته باشند. بااین‌حال، می‌توانید از پارامتر includeAnyProvidedLabel استفاده کنید تا به API دستور دهید دارایی‌هایی را برگرداند که با هریک از برچسب‌های مشخص‌شده مطابقت دارند.
      • includeAnyProvidedLabel: این پارامتر که همراه با پارامتر labels استفاده می‌شود، به «میانای برنامه‌سازی کاربردی» دستور می‌دهد دارایی‌هایی را برگرداند که با هریک از برچسب‌های مشخص‌شده در مقدار پارامتر labels مرتبط هستند.

    • منبع claimHistory اکنون حاوی ویژگی‌های جدید زیر است:

      • مشخصه event[].source.userEmail نشانی ایمیل کاربری را که رویداد را آغاز کرده است ارائه می‌دهد.
      • دارایی event[].typeDetails.disputeNotes حاوی یادداشت‌های اختلاف برای رویداد dispute_create است.

    • روش claimSearch.list اکنون از پارامترهای اختیاری زیر پشتیبانی می‌کند:

      • createdAfter: نتایج را محدود می‌کند تا فقط شامل ادعاهای ایجادشده پس‌از تاریخ مشخص‌شده باشد.
      • ‫createdBefore: نتایج را محدود می‌کند تا فقط شامل ادعاهایی باشد که قبل‌از تاریخ مشخص‌شده ایجاد شده‌اند.
      • includeThirdPartyClaims: این پارامتر که همراه با پارامتر videoId استفاده می‌شود، نشان می‌دهد که آیا ادعاهای طرف سوم در نتایج API گنجانده شود یا نه.

  • اطلاعات دقیق‌تر درباره خطا

    اکنون مستندات خطا کد پاسخ HTTP را برای هر نوع خطا مشخص می‌کند.

  • خطاهای جدید و به‌روزشده

    جدول زیر خطاهای جدیدی را که API پشتیبانی می‌کند و روش‌هایی را که می‌تواند هر خطا را برگرداند مشخص می‌کند. توجه داشته باشید که یک روش ممکن است چندین خطا با نوع خطای یکسان برگرداند. برای مثال، اگر سعی کنید منبع asset را که فیلد فراداده الزامی ندارد درج کنید، خطای required برگردانده می‌شود. درواقع، ممکن است بیش‌از یک فیلد فراداده الزامی وجود داشته باشد که هرکدام خطایی با پیامی کمی متفاوت برمی‌گردانند.

    برای اطلاعات بیشتر، لطفاً به مستندات خطا برای هر روش یا به صفحه خطاها مراجعه کنید.

    روش خطاها
    assetSearch.list
    • invalidValue – API از قابلیت جستجوی دارایی‌های نمایش یا فصل پشتیبانی نمی‌کند. مقدار پارامتر type را به مقدار پشتیبانی‌شده‌ای تغییر دهید.
    assets.insert
    • conflict – دارایی‌های زیادی با شناسه یکسان (مثلاً شناسه سفارشی، ISRC، و غیره) ازقبل وجود دارد.
    • conflict – تعداد زیادی نسخه از دارایی مشخص‌شده ازقبل وجود دارد.
    • invalidValue – کاربری که API را فراخوانی می‌کند، اجازه ایجاد دارایی‌های نوع مشخص‌شده را ندارد.
    assets.patch
    assets.update
    • ‫badRequest – «میانای برنامه‌سازی کاربردی» از تبدیل نوع دارایی که تلاش کرده‌اید پشتیبانی نمی‌کند.
    claimSearch.list
    ownership.patch
    ownership.update
    • badRequest – نمی‌توانید مالکیت دارایی نماهنگ هنری را به‌روز کنید.
    references.patch
    references.update
    • badRequest – مرجع در وضعیت نامعتبری برای عملیاتی که می‌خواهید انجام دهید قرار دارد.

‫۳ فوریه ۲۰۱۴ (۱۴ بهمن ۱۳۹۲)

این به‌روزرسانی شامل تغییرات زیر است:

  • به‌روزرسانی منابع و روش‌های موجود

    • اکنون منبع asset می‌تواند مقدار type art_track_video داشته باشد.

    • منبع claimSearch اکنون شامل ویژگی‌های جدید زیر است:

      • شیء origin حاوی اطلاعاتی است که نحوه ایجاد ادعا را توصیف می‌کند.
      • ویژگی thirdPartyClaim حاوی مقدار بولی است که نشان می‌دهد آیا ادعای مالکیت توسط مالک محتوایی غیراز مالک محتوای مرتبط با کاربر انجام‌دهنده جستجو مطرح شده است یا نه.

    • روش claimSearch.list اکنون از پارامترهای اختیاری زیر پشتیبانی می‌کند:

      • contentType: نتایج را محدود می‌کند تا فقط شامل ادعاهای فقط صوتی، ادعاهای فقط ویدیویی یا ادعاهای صوتی-تصویری باشد.
      • origin: یک یا چند منشأ ادعا را مشخص می‌کند، مانند descriptiveSearch یا videoMatch، که می‌خواهید ادعاهای مربوط به آن‌ها را پیدا کنید.
      • status: نتایج را محدود می‌کند تا فقط شامل ادعاهایی باشد که وضعیت مشخص‌شده را دارند.

    • ویژگی status منبع claim اکنون از این مقادیر اضافی پشتیبانی می‌کند: appealed، disputed، potential، takedown، و unknown.

    • ویژگی جدید blockOutsideOwnership منبع claim نشان می‌دهد که آیا ویدیو مورد ادعا باید در قلمروهایی که به‌طور صریح تحت مالکیت نیستند مسدود شود یا نه. به‌طور پیش‌فرض، ویدیو ادعاشده همچنان در کشورهایی که داده‌های مالکیت برای دارایی مرتبط با ادعا تعریف نشده است، قابل‌مشاهده خواهد بود.

    • ویژگی جدید allowedOptions.autoGeneratedBreaks منبع contentOwnerAdvertisingOption نشان می‌دهد که آیا شریک می‌تواند انتخاب کند که آگهی‌های میان‌پخش و درون جاری‌سازی در زمان‌های وقفه که به‌طور خودکار توسط YouTube تعیین شده‌اند، نمایش داده شوند یا نه.

    • اکنون می‌توان روش contentOwners.list را با یک کد مجوز که حوزه https://www.googleapis.com/auth/youtubepartner-content-owner-readonly را مشخص می‌کند فراخوانی کرد.

    • ویژگی جدید timeUpdated منبع policy زمانی را مشخص می‌کند که خط‌مشی آخرین‌بار به‌روزرسانی شده است.

    • روش policies.list اکنون از پارامتر اختیاری sort پشتیبانی می‌کند که می‌توان از آن برای مشخص کردن اینکه نتایج باید به‌ترتیب صعودی یا نزولی زمان آخرین به‌روزرسانی مرتب شوند استفاده کرد.

    • ویژگی جدید expiryTime منبع referenceConflict زمانی را مشخص می‌کند که دوره بازبینی برای تعارض مرجع به پایان می‌رسد و باعث منقضی شدن تعارض می‌شود.

    • ویژگی جدید autoGeneratedBreaks منبع videoAdvertisingOption نشان می‌دهد که آیا ویدیو باید آگهی‌های میان‌پخش و درون جاری‌سازی را در زمان‌های وقفه که به‌طور خودکار توسط YouTube تعیین شده‌اند نشان دهد یا نه.

  • خطاهای جدید و به‌روزشده

    جدول زیر خطاهای جدیدی را که API پشتیبانی می‌کند و روش‌هایی را که می‌تواند هر خطا را برگرداند نشان می‌دهد. توجه داشته باشید که یک روش ممکن است چندین خطا با نوع خطای یکسان برگرداند. برای مثال، اگر سعی کنید منبع asset را که فیلد فراداده الزامی ندارد درج کنید، خطای required برگردانده می‌شود. درواقع، ممکن است بیش از یک فیلد فراداده الزامی وجود داشته باشد که هرکدام از آن‌ها خطایی با پیامی کمی متفاوت برمی‌گرداند.

    برای اطلاعات بیشتر، لطفاً به اسناد خطا برای هر روش یا به صفحه خطاها مراجعه کنید.

    روش خطاها
    assets.insert
    assets.update
    • badRequest – میانای برنامه‌سازی کاربردی از عملیات نوشتن روی دارایی‌های نماهنگ هنری پشتیبانی نمی‌کند.
    claimSearch.list
    • invalidValue – پارامتر pageToken در درخواست، یک کد صفحه نامعتبر را مشخص می‌کند.
    claims.insert
    • badRequest – ادعایی که می‌خواهید ایجاد کنید نامعتبر است زیرا کانال ویدیو فعال نیست.
    • badRequest – ویدیویی که می‌خواهید برای آن ادعای مالکیت کنید از خط‌مشی حذف معاف است. اگر سؤالی دارید، لطفاً با copyright@youtube.com تماس بگیرید
    • badRequest – درخواست شما نمی‌تواند پردازش شود زیرا نمی‌توانید ادعای طرف سوم را روی ویدیو مشخص‌شده ایجاد کنید.
    • conflict – YouTube نمی‌تواند ادعای درخواست‌شده را ایجاد کند زیرا ویدیو با اخطار حذف محتوا مقابله کرده است.
    • conflict – YouTube نمی‌تواند ادعای درخواست‌شده را ایجاد کند زیرا ویدیو دارای ادعای حذف فعال است.
    references.insert
    • badRequest – ویدیو ادعاشده‌ای که می‌خواهید استفاده کنید حذف یا رد شده است، یا پردازش آن ناموفق بوده است.

  • خطاهای contentOwnerNotProvided و internalError که مختص روش میانای برنامه‌سازی کاربردی خاصی نیستند، دیگر در هر صفحه روش فهرست نمی‌شوند. شرح آن‌ها را همچنان می‌توانید در بخش خطاهای عمومی در اسناد خطای API پیدا کنید.

‫۱۲ سپتامبر ۲۰۱۳

این به‌روزرسانی شامل تغییرات زیر است:

  • منابع و روش‌های جدید

    • منبع جدید referenceConflict تداخلی را بین دو فایل مرجع شناسایی می‌کند و مطابقت‌هایی را که هنگام شناسایی تداخل بین آن فایل‌ها وجود داشته است فهرست می‌کند. روش referenceConflicts.list به شما امکان می‌دهد فهرستی از تعارض‌های مرجع حل‌نشده مرتبط با مالک محتوای مجاز را بازیابی کنید. روش referenceConflicts.get به شما امکان می‌دهد با مشخص کردن شناسه تعارض مرجع یکتا، تعارض مرجع را بازیابی کنید.

    به‌روزرسانی منابع و روش‌های موجود

    • این API اکنون از قابلیت بازیابی خط‌مشی مطابقت مؤثر برای یک دارایی پشتیبانی می‌کند. این تغییر موازی با تغییراتی است که در تاریخ ۱۶ ژوئیه ۲۰۱۳ منتشر شد و شامل پشتیبانی از بازیابی مجموعه متعارف فراداده و داده‌های مالکیت برای یک دارایی بود.

      برای بازیابی خط‌مشی انطباق مؤثر برای یک دارایی، مقدار پارامتر fetchMatchPolicy را هنگام فراخوانی روش‌های assets.get یا assets.list روی effective تنظیم کنید. در پاسخ API، شیء matchPolicyEffective در هر منبع asset برگشتی حاوی خط‌مشی مطابقت مؤثر برای آن دارایی است.

    • شیء جدید ownershipConflicts منبع asset حاوی اطلاعاتی درباره تعارض‌های مالکیت دارایی است. ساختار شیء شبیه به ساختار منبع ownership است که هر نوع مختلف از حقوقی را که مالک دارایی می‌تواند داشته باشد شناسایی می‌کند. (برای اکثر انواع دارایی، مالکان می‌توانند فقط مالکیت کلی دارایی را داشته باشند، اما برای دارایی‌های قطعه موسیقی، مالکان می‌توانند مالکیت خود را بر حقوق اجرا، حقوق همگام‌سازی، یا حقوق مکانیکی به‌صورت تفکیک‌شده مشخص کنند.)

      به‌همین ترتیب، شیء ownershipConflicts شامل فهرست‌های جداگانه‌ای است که تعارضات مربوط به حقوق مالکیت عمومی، حقوق اجرا، حقوق همگام‌سازی، و حقوق مکانیکی را شناسایی می‌کنند. برای هر تعارض، داده‌ها قلمروهایی را که تعارض در آن‌ها رخ می‌دهد، مالکانی که داده‌های مالکیت متعارض ارائه کرده‌اند، و درصد دارایی‌ای را که هر مالک متعارض ادعای مالکیت آن را دارد، شناسایی می‌کنند.

    • روش‌های assets.get و assets.get اکنون از پارامتر جدید fetchOwnershipConflicts پشتیبانی می‌کنند. این پارامتر دارای مقدار بولی است که نشان می‌دهد آیا درخواست میانای برنامه‌سازی کاربردی باید تعارضات مالکیت را برای دارایی‌ها در پاسخ میانای برنامه‌سازی کاربردی بازیابی کند یا نه. مقدار پیش‌فرض false است، یعنی تعارض‌های مالکیت برگردانده نمی‌شوند.

    • تعریف پارامتر q روش assetSearch.list به‌روز شده است تا فیلدهای فراداده‌ای را که YouTube جستجو می‌کند شناسایی کند.

    • مستندات بدنه درخواست برای روش references.insert اکنون نشان می‌دهد که باید مقدار ویژگی contentType را تنظیم کنید. این تغییر، مستندات را به‌روز می‌کند تا عملکرد واقعی میانای برنامه‌سازی کاربردی را به‌درستی منعکس کند، اما نشان‌دهنده تغییری در عملکرد میانای برنامه‌سازی کاربردی نیست.

  • خطاهای جدید و به‌روزشده

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

    • روش assets.insert اکنون خطاهای فراداده را به‌عنوان خطاهایی که در ویژگی‌های شیء metadataMine رخ می‌دهند شناسایی می‌کند، نه در شیء metadata که از زمان به‌روزرسانی API در ۱۶ ژوئیه ۲۰۱۳ منسوخ شده است.

    • صفحه خطاها به‌روز شده است تا برای هر منبعی که از روش‌های update و patch پشتیبانی می‌کند، صفحه حاوی جدولی باشد که خطاهای برگشتی توسط آن دو روش را فهرست می‌کند. قبلاً، این صفحه خطاهای هر روش را به‌طور جداگانه فهرست می‌کرد، اگرچه فهرست‌ها همیشه یکسان بودند.

۱۶ ژوئیه ۲۰۱۳

این به‌روزرسانی شامل تغییرات زیر است:

  • منابع و روش‌های جدید

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

    • روش جدید claimSearch.list به شما امکان می‌دهد ادعاهایی را جستجو کنید که با هریک یا همه معیارهای زیر مطابقت دارند:

      • ادعاهای مالکیت با یک دارایی خاص مرتبط هستند.
      • ادعاها با یک ویدیو خاص مرتبط هستند.
      • ادعاها با رشته پُرسمان ارائه‌شده در درخواست مطابقت دارد.

      هر claimSnippet منبع در پاسخ API شامل جزئیاتی درباره یک ادعا است، ازجمله شناسه ادعای منحصربه‌فرد آن، وضعیت آن، نوع آن (audio، video، یا audiovisual)، و دارایی و ویدیو مرتبط با ادعا. این منبع همچنین تعداد بازدیدهای ویدیو ادعاشده و عنوان ویدیو ادعاشده را مشخص می‌کند.

  • به‌روزرسانی‌های منابع و روش‌های موجود

    • اکنون در اسناد، مقادیر پشتیبانی‌شده برای ویژگی‌هایی که مجموعه‌ای از مقادیر شمارشی دارند فهرست شده است. این ویژگی‌ها شامل ویژگی type منبع asset و ویژگی status منبع claim است.

    • برای روش‌های assets.get و assets.list، اکنون API از مقادیر جداشده با کاما برای پارامترهای درخواست fetchMetadata و fetchOwnership پشتیبانی می‌کند، که به شما امکان می‌دهد چندین مجموعه از فراداده یا داده‌های مالکیت را بازیابی کنید.

      فهرست زیر تغییرات مربوط به ساختار منبع asset و همچنین تأثیرات این تغییرات بر روش‌های میانای برنامه‌سازی کاربردی را که منابع asset را get، list، insert، update، یا patch می‌کنند توضیح می‌دهد.

      • شیء metadata منسوخ شده است و با اشیای metadataMine و metadataEffective جایگزین شده است. اشیاء جدید به منبع asset اجازه می‌دهند تا هم مجموعه فراداده ارائه‌شده توسط مالک محتوا که درخواست API را ایجاد می‌کند و هم مجموعه متعارف فراداده‌ای را که YouTube تعیین کرده است، دقیق‌ترین و کامل‌ترین مجموعه فراداده برای دارایی است، شامل شود.

      • به‌همین ترتیب، شیء ownership با شیءهای ownershipMine و ownershipEffective جایگزین شده است.

      • شیء matchPolicy با شیء matchPolicyMine جایگزین شد. (میانای برنامه‌سازی کاربردی درحال‌حاضر از قابلیت بازیابی خط‌مشی انطباق مؤثر برای دارایی پشتیبانی نمی‌کند.)

      توجه: برای اطمینان از سازگاری با نسخه‌های قبلی، اگر فقط یک نسخه فراداده، یک مجموعه داده مالکیت، یا یک خط‌مشی تطبیق برای یک دارایی درخواست شود، پاسخ API شامل شیء منسوخ‌شده و همچنین شیء جدید پشتیبانی‌شده خواهد بود. برای مثال، اگر درخواستی پارامتر fetchMetadata را روی mine تنظیم کند، پاسخ میانای برنامه‌سازی کاربردی حاوی یک شیء metadata و یک شیء metadataMine خواهد بود که هر دو حاوی داده‌های یکسانی خواهند بود. (امکان تنظیم fetchMetadata=mine پیش‌از به‌روزرسانی ویژگی که به شما امکان می‌دهد چندین نسخه فراداده را بازیابی کنید پشتیبانی می‌شد.)

      بااین‌حال، اگر پارامتر fetchMetadata روی mine,effective تنظیم شده باشد، پاسخ میانای برنامه‌سازی کاربردی حاوی اشیاء metadataMine و metadataEffective خواهد بود، اما حاوی شیء metadata نخواهد بود. (امکان تنظیم fetchMetadata=mine,effective قبل‌از این به‌روزرسانی ویژگی پشتیبانی نمی‌شد، بنابراین نیازی به برگرداندن شیء metadata برای سازگاری با نسخه قدیمی نیست.) همین اصل برای پارامترهای fetchOwnership و fetchMatchPolicy نیز اعمال می‌شود.

      به‌طور مشابه، برای سازگاری با نسخه قدیمی، درخواست برای insert، update، یا patch منبع asset می‌تواند شامل شیء metadataMine یا شیء metadata باشد. همین اصل برای تنظیم داده‌های مالکیت یا خط‌مشی مطابقت منبع asset نیز اعمال می‌شود.

    • پارامترهای assetId، q، و videoId روش claims.list منسوخ شده‌اند. برای جستجوی ادعاها بااستفاده از هریک از این معیارها، از روش claimSearch.list استفاده کنید که از همه این پارامترها پشتیبانی می‌کند.

    • در منبع ownership، مقادیر ویژگی‌های general[].ratio،‏ performance[].ratio،‏ synchronization[].ratio، و mechanical[].ratio اکنون همگی قالب محتوای double را به‌جای integer دارند.

    • تعریف ویژگی rules[].action منبع policy اکنون مقادیر معتبر برای آن ویژگی را فهرست می‌کند: block، monetize، takedown، و track. اما توجه داشته باشید که نمی‌توانید از API برای اعمال خط‌مشی حذف به ادعا استفاده کنید.

    • اگر مرجع با مرتبط کردن یک دارایی با یک ویدیو YouTube موجود که در کانال YouTube پیوندشده به حساب «سیستم مدیریت محتوا» شما بارگذاری شده است ایجاد شده باشد، ویژگی جدید claimId منبع reference وجود دارد. در این صورت، این فیلد حاوی شناسه ادعایی است که نشان‌دهنده ارتباط حاصل بین دارایی و ویدیو است.

    • دارایی reference جدید excludedIntervals[] فهرستی از بازه‌های زمانی را در مرجع مشخص می‌کند که YouTube باید هنگام تلاش برای مطابقت مرجع آن‌ها را نادیده بگیرد. هر بازه زمانی، زمان شروع و پایان را که برحسب ثانیه از ابتدای ویدیو اندازه‌گیری می‌شود، مشخص می‌کند.

    • میانای برنامه‌سازی کاربردی دیگر نیازی ندارد که دارایی status در منبع reference که در بدنه درخواست references.update یا references.patch ارسال می‌شود تنظیم شود.

    • مستندات اصلاح شده است تا قالب پاسخ میانای برنامه‌سازی کاربردی برای روش videoAdvertisingOptions.getEnabledAds به‌درستی شرح داده شود. پاسخ، که یک منبع youtubePartner#videoAdvertisingOptionGetEnabledAds است، حاوی اطلاعات زیر است:

      • id – شناسه‌ای که YouTube برای شناسایی منحصربه‌فرد ویدیو ادعاشده مرتبط با تنظیمات استفاده می‌کند.

      • adBreaks – فهرستی از اشیاء که هرکدام حاوی اطلاعاتی درباره نقطه‌ای قبل، درطول، یا بعداز بازپخش ویدیو است که آگهی‌ها اجازه اجرا دارند. هر شیء همچنین می‌تواند مشخصه‌های دیگری از وقفه آگهی را مشخص کند، مانند جایگاه‌های آگهی که درطول وقفه رخ می‌دهند و انواع آگهی‌هایی که اجازه دارند درطول هر جایگاه اجرا شوند.

      • adsOnEmbeds – یک فیلد بولی که نشان می‌دهد آیا YouTube می‌تواند هنگام پخش ویدیو در یک پخش‌کننده جاسازی‌شده آگهی نمایش دهد یا خیر.

      • countriesRestriction – فهرستی از اشیاء که در آن هر شیء فهرستی از قلمروها و قالب‌های آگهی را که درطول بازپخش ویدیو در آن قلمروها استفاده می‌شود شناسایی می‌کند.

  • خطاهای جدید و به‌روزشده

    • جدول زیر خطاهای جدیدی را که API پشتیبانی می‌کند و روش‌هایی را که می‌تواند هر خطا را برگرداند نشان می‌دهد. همچنین خطاهایی را که تغییر کرده‌اند شناسایی می‌کند. توجه داشته باشید که یک روش ممکن است چندین خطا را که نوع خطای یکسانی دارند برگرداند. برای مثال، اگر سعی کنید منبع asset را که فاقد فیلد فراداده الزامی است درج کنید، خطای required برگردانده می‌شود. درواقع، ممکن است بیش از یک فیلد فراداده الزامی وجود داشته باشد که هرکدام از آن‌ها خطایی با پیامی کمی متفاوت برمی‌گرداند.

      برای اطلاعات بیشتر، لطفاً به اسناد خطا برای هر روش یا به صفحه خطاها مراجعه کنید.

      روش خطاها
      assets.insert
      assets.update
      assets.patch
      • خطاهای invalidValue و required که قبلاً با دارایی‌های فرزند شیء metadata مرتبط بودند، اکنون با همان دارایی‌های فرزند در شیء metadataMine مرتبط هستند.
      claimHistory.get
      • notFound – ادعایی که می‌خواهید سابقه آن را بازیابی کنید پیدا نشد.
      • required – درخواست مقداری برای پارامتر claimId مشخص نمی‌کند.
      claimSearch.list
      claims.list
      • badRequest – درخواست معیارهای نامعتبر را مشخص می‌کند. حداکثر یکی از پارامترهای فیلتر زیر را می‌توان مشخص کرد: q،‏ assetId،‏ videoId.
      claims.insert
      • badRequest – ادعایی که می‌خواهید ایجاد کنید نامعتبر است زیرا مالک محتوای درخواست‌شده مالک دارایی مرتبط با ادعا نیست.
      • badRequest – مالک محتوایی که ازطرف او اقدام می‌کنید اجازه ندارد خط‌مشی‌هایی با کنش مشخص‌شده ایجاد کند.
      • invalidValue – مالک محتوایی که از طرف او اقدام می‌کنید، اجازه ندارد ویدیوهای بارگذاری‌شده توسط کاربر را ازطریق API ادعا کند.
      contentOwners.list
      • badRequest – درخواست معیارهای نامعتبر را مشخص می‌کند. دقیقاً یکی از پارامترهای فیلتر زیر باید مشخص شود: fetchMine، id. (قبلاً، این خطا مجموعه متفاوتی از پارامترهای فیلتر را فهرست می‌کرد – has_conflicts_with، restrict_to_user، name_prefix، و id.)
      ownership.update
      ownership.patch
      • badRequest – درخواستی که داده‌های مالکیت دارایی ترکیب‌بندی را به‌روز می‌کند باید داده‌های مالکیت جزئی را مشخص کند &ndahs; حقوق mechanical، performance، synchronization، و/یا lyric – به‌جای حقوق مالکیت general. نوع حقوق lyric به‌تازگی پشتیبانی می‌شود.
      policies.insert
      policies.update
      policies.patch
      • invalidValue – درخواست حاوی یک قانون خط‌مشی نامعتبر است زیرا API از ایجاد یا اصلاح خط‌مشی‌هایی که یک کنش takedown را مشخص می‌کنند، پشتیبانی نمی‌کند. این خطا که دلیل invalidPolicyTakedownAction را گزارش می‌کند، جایگزین خطای منسوخ‌شده invalidPolicyConditionalTakedown می‌شود.
      references.insert
      • badRequest – درخواست باید یا فایل رسانه‌ای ارسال کند یا مقداری برای پارامتر درخواست claimId مشخص کند. بااین‌حال، یک درخواست نمی‌تواند فایل رسانه‌ای ارسال کند و مقدار پارامتر درخواست claimId را مشخص کند.
      • badRequest – مرجعی برای همان محتوا قبلاً از ادعای مالکیت دیگری در همان ویدیو YouTube ایجاد شده است.
      • ‫badRequest – این API از امکان تنظیم مقدار برای دارایی fpDirect هنگام ایجاد مرجع پشتیبانی نمی‌کند.
      • internalError – مشکلی در فایل رسانه بارگذاری‌شده وجود دارد.
      • invalidValue – مقدار پارامتر درخواست contentType، assetId، یا claimId نامعتبر است. خطا مقدار نامعتبر را شناسایی می‌کند.
      • notFound – دارایی یا ادعایی که مشخص کرده‌اید پیدا نشد. لطفاً مقادیر پارامتر assetId و claimId را در درخواستتان بررسی کنید.
      • required – درخواست باید مقداری برای پارامتر contentType مشخص کند.
      references.insert
      references.update
      references.patch
      • invalidValue – excludedIntervals مشخص‌شده برای مرجع معتبر نیست. توجه داشته باشید که هنگام غیرفعال کردن مرجع نمی‌توانید بازه‌های استثنا را مشخص کنید.

۱۰ مه ۲۰۱۳

این به‌روزرسانی شامل تغییرات زیر است:

۸ آوریل ۲۰۱۳

این به‌روزرسانی شامل تغییرات زیر است:

  • نام این میانای برنامه‌سازی کاربردی به «میانای برنامه‌سازی کاربردی Content ID در YouTube» تغییر کرده است.

  • چندین ویژگی در منبع assetMatchPolicy تغییر کرده است:

    • مقدار خصوصیت kind از youtubePartner#policy به youtubePartner#assetMatchPolicy تغییر کرده است.
    • دارایی جدید policyId حاوی مقداری است که به‌طور منحصربه‌فرد منبع خط‌مشی ذخیره‌شده را شناسایی می‌کند.
    • مقدار ویژگی rules[].subaction اکنون به‌جای رشته، فهرستی از رشته‌ها است.
    • مقدار ویژگی rules[].conditions.contentMatchType اکنون به‌جای رشته، فهرستی از رشته‌ها است.
    • خصوصیت‌های id،‏ name، و description برداشته شده‌اند.

  • مستندات روش assetMatchPolicy.update به‌روز شده است تا این واقعیت را منعکس کند که هنگام فراخوانی روش می‌توانید مقادیر را برای دارایی policyId یا شیء rules[] تنظیم کنید.

  • منبع claims اکنون از چندین ویژگی جدید پشتیبانی می‌کند:

    نام دارایی مقدار شرح
    timeCreated datetime تاریخ و زمان ایجاد ادعا.
    matchInfo object شیء matchInfo حاوی اطلاعاتی درباره محتوای منطبقی است که ادعا را ایجاد کرده است. این اطلاعات فقط درصورتی در منبع claim گنجانده می‌شود که ادعا به‌طور خودکار ایجاد شده باشد، زیرا ویدیو بارگذاری‌شده با فایل مرجع موجود مطابقت داشته است.
    matchInfo.referenceId string شناسه یکتایی که YouTube برای شناسایی مرجع reference که مطابقت را ایجاد کرده است استفاده می‌کند.
    matchInfo.longestMatch object شیء longestMatch حاوی اطلاعاتی درباره طولانی‌ترین مطابقت بین مرجع و ویدیو بارگذاری‌شده است.
    matchInfo.longestMatch.durationSecs unsigned long مدت تطابق، برحسب ثانیه.
    matchInfo.longestMatch.userVideoOffset unsigned long زمان شروع مسابقه، که برحسب ثانیه از ابتدای ویدیو بارگذاری‌شده اندازه‌گیری می‌شود.
    matchInfo.longestMatch.referenceOffset unsigned long انحراف زمانی هنگام شروع مسابقه، که برحسب ثانیه از ابتدای مرجع اندازه‌گیری می‌شود.
    matchInfo.totalMatch object شیء totalMatch حاوی اطلاعاتی درباره مقدار کل ویدیو بارگذاری‌شده است که با مرجع مطابقت دارد و درباره مقدار کل مرجع است که با ویدیو بارگذاری‌شده مطابقت دارد. اگر محتوای منطبق در ویدیو بارگذاری‌شده یا مرجع به‌صورت حلقه اجرا شود، ممکن است این مقادیر متفاوت باشند. برای مثال، اگر یک ویدیو بارگذاری‌شده شامل یک کلیپ ۱۰ ثانیه‌ای از یک مرجع باشد، اما این کلیپ شش بار تکرار شود، کل محتوای منطبق در ویدیو بارگذاری‌شده ۶۰ ثانیه است، اما کل محتوای منطبق در مرجع تنها ۱۰ ثانیه است.
    matchInfo.totalMatch.userVideoDurationSecs unsigned long طول کل محتوای ویدیو بارگذاری‌شده که با مرجع مطابقت دارد، برحسب ثانیه.
    matchInfo.totalMatch.referenceDurationSecs unsigned long طول کل محتوای مرجع که با ویدیو بارگذاری‌شده مطابقت دارد، برحسب ثانیه.
    origin object شیء origin حاوی اطلاعاتی است که منبع ادعا را توصیف می‌کند.
    origin.source string منبع ادعا.

  • ویژگی policy در منبع claims به‌روزرسانی شده است تا نشان دهد که مقدار برای ادعای AudioSwap قابل به‌روزرسانی نیست.

  • نام ویژگی timeProvidedMs منبع metadataHistory به timeProvided تغییر کرده است.

  • نام ویژگی timeProvidedMs منبع ownershipHistory به timeProvided تغییر کرده است.

  • تعریف روش ownershipHistory.list به‌روز شده است تا یادآوری شود که این روش فقط جدیدترین داده‌های مالکیت را برای هر مالک محتوا بازیابی می‌کند. بااین‌حال، اگر مالک محتوا داده‌های مالکیت را ازطریق چندین منبع داده (میانای برنامه‌سازی کاربردی، فیدهای محتوا، و غیره) ارسال کرده باشد، فهرست حاوی جدیدترین داده‌ها برای هر مالک محتوا و منبع داده خواهد بود.

  • چندین ویژگی در منبع policy تغییر کرده است:

    • نام خصوصیت rule به rules تغییر کرده است.
    • مقدار دارایی rules[].subaction اکنون به‌جای رشته، فهرستی از رشته‌ها است.
    • مقدار ویژگی rules[].conditions.contentMatchType اکنون به‌جای رشته، فهرستی از رشته‌ها است.

  • مستندات روش‌های policies.insert و policies.update به‌روز شده است تا این واقعیت را منعکس کند که هنگام فراخوانی این روش‌ها می‌توانید مقادیر را برای شیء rules[] تنظیم کنید.

  • چندین روش API از انواع خطای جدید پشتیبانی می‌کنند. جدول زیر روش را مشخص می‌کند و به‌طور خلاصه انواع خطاهای جدیدی را که پشتیبانی می‌شود شناسایی می‌کند. در بسیاری از موارد، ممکن است چند خطا برای یک نوع خاص وجود داشته باشد. برای مثال، اگر سعی کنید منبع asset را که فاقد فیلد فراداده الزامی است درج کنید، خطای required برگردانده می‌شود. درواقع، ممکن است بیش‌از یک فیلد فراداده الزامی وجود داشته باشد که هرکدام خطایی با پیام کمی متفاوت برمی‌گرداند.

    برای اطلاعات بیشتر، لطفاً به اسناد خطا برای هر روش یا به صفحه خطاها مراجعه کنید.

    روش خطاها
    assets.insert
    • invalidValue – فیلد فراداده دارایی حاوی مقدار نامعتبر است.
    • required – فیلد فراداده دارایی الزامی وجود ندارد.
    assets.update
    assets.patch
    • forbidden – دارایی‌ای که درحال به‌روزرسانی است متعلق به شریکی نیست که می‌خواهد به‌روزرسانی را تکمیل کند.
    • invalidValue – فیلد فراداده دارایی حاوی مقدار نامعتبر است.
    • notFound – دارایی با دارایی فصل یا دارایی نمایشی که پیدا نمی‌شود مرتبط می‌شود.
    • required – فیلد فراداده دارایی الزامی وجود ندارد.
    claims.insert
    • badRequest – درخواست تلاش می‌کند تا ادعای مالکیت ویدیو را مطرح کند، اما این ادعا مجاز نیست.
    ownership.update
    ownership.patch
    • badRequest – درخواست مالکیت کل را بیشتر از ۱۰۰ درصد در یک قلمرو تعریف می‌کند.
    policies.insert
    policies.patch
    policies.update
    • conflictingPolicyRules – خط‌مشی حاوی قوانین خط‌مشی متناقض است.

  • صفحه جدید خطاها خطاهایی را که میانای برنامه‌سازی کاربردی می‌تواند برگرداند فهرست می‌کند. این صفحه شامل خطاهای عمومی است که ممکن است برای چندین روش مختلف API رخ دهد، و همچنین خطاهای مختص روش.

۱۸ ژانویه ۲۰۱۳

این به‌روزرسانی شامل تغییرات زیر است:

  • روش جدید مستندشده videoAdvertisingOptions.getEnabledAds به شما امکان می‌دهد جزئیات مربوط به انواع آگهی‌هایی را که برای یک ویدیو مشخص بارگذاری‌شده توسط شریک یا کاربر مجاز هستند، بازیابی کنید.

  • تعریف پارامتر ownershipRestriction روش assetSearch.list به‌روز شده است تا نشان دهد که مقدار پارامتر پیش‌فرض mine است، که نشان می‌دهد API باید فقط دارایی‌های متعلق به کاربر فعلی را بازیابی کند.

  • سند روش assets.list تغییرات زیر را منعکس می‌کند:

    • پارامتر id اکنون الزامی است.

    • پارامتر fetchMatchPolicy که به‌تازگی پشتیبانی می‌شود به شما امکان می‌دهد مشخص کنید که آیا درخواست API باید خط‌مشی مطابقت را که برای دارایی تنظیم کرده‌اید نیز بازیابی کند یا نه.

    • پارامتر fetchOwnership که به‌تازگی پشتیبانی می‌شود به شما امکان می‌دهد مشخص کنید که آیا درخواست API باید داده‌های مالکیت دارایی را نیز بازیابی کند یا نه.

    • فهرست دارایی‌هایی که «میانای برنامه‌سازی کاربردی» برمی‌گرداند دیگر حاوی داده‌های صفحه‌بندی نیست. درنتیجه، هم ویژگی nextPageToken و هم شیء pageInfo از پاسخ میانای برنامه‌سازی کاربردی برداشته شده‌اند. شیء pageInfo حاوی خصوصیت‌های totalResults، resultsPerPage، و startIndex بود.

  • اسناد منبع claims به‌روزرسانی شده است تا یادآوری کند که هنگام ایجاد ادعا باید خط‌مشی را مشخص کنید. (درحال‌حاضر اگر ادعای درج‌شده خط‌مشی‌ای را مشخص نکند، YouTube خط‌مشی استفاده پیش‌فرض شما را اعمال نمی‌کند، هرچند در اسناد قبلاً اشاره شده بود که این اتفاق می‌افتد.)

  • خصوصیت hasUnpublishedDraft منبع policy منسوخ شده است.

  • پارامتر id که به‌تازگی در روش policies.list پشتیبانی می‌شود به شما امکان می‌دهد خط‌مشی‌های ذخیره‌شده‌ای را که درخواست API باید بازیابی کند شناسایی کنید. فقط خط‌مشی‌های متعلق به مالک محتوای اصالت‌سنجی‌شده فعلی قابل‌بازیابی هستند.

  • تعریف پارامتر releaseClaims برای هر دو روش references.patch و references.update به‌روزرسانی شده است تا مشخص شود که این پارامتر فقط زمانی کار می‌کند که وضعیت ادعا به inactive به‌روزرسانی شود. در این صورت، می‌توانید مقدار پارامتر releaseClaims را روی true تنظیم کنید تا همه ادعاهای مطابقت تولیدشده توسط مرجع واگذار شوند.

  • روش‌های references.patch و references.update هر دو به‌روزرسانی شده‌اند تا توجه داشته باشید که هنگام انجام هریک از این عملیات‌ها باید وضعیت مرجع را مشخص کنید.

  • چند روش API از انواع خطای جدید پشتیبانی می‌کنند. جدول زیر روش و خطاهای جدید پشتیبانی‌شده را مشخص می‌کند:

    روش نوع خطا جزئیات خطا شرح
    guideCategories.list notFound Unavailable دارایی‌ای که می‌خواهید خط‌مشی تطابق آن را بازیابی کنید پیدا نشد.
    claims.get notFound Unavailable ادعایی که می‌خواهید بازیابی کنید پیدا نشد.
    ownership.patch invalidValue Unavailable داده‌های مالکیت که ارائه کرده‌اید مقدار نامعتبر دارد.
    ownership.update invalidValue Unavailable داده‌های مالکیت که ارائه کرده‌اید مقدار نامعتبر دارد.