Introduction

این سند شباهت‌ها و تفاوت‌ها را در روش‌هایی توضیح می‌دهد که YouTube Analytics API و YouTube Reporting API دسترسی به داده‌های YouTube Analytics را فراهم می‌کنند. هدف سند کمک به شما برای انتخاب API مناسب برای برنامه است.

هر دو API به توسعه دهندگان امکان می دهند داده های YouTube Analytics را بازیابی کنند. علاوه بر این، هر دو API از دارندگان کانال YouTube و صاحبان محتوای YouTube پشتیبانی می کنند، که هر کدام می توانند به مجموعه خاصی از گزارش ها دسترسی داشته باشند:

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

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

گزارش API همچنین به برخی از صاحبان محتوا اجازه می دهد به گزارش های درآمد تبلیغاتی مدیریت شده توسط سیستم دسترسی داشته باشند. داده های موجود در گزارش های مدیریت شده توسط سیستم را فقط می توان با گزارش API بازیابی کرد.

همه درخواست‌های YouTube Analytics و YouTube Reporting API باید توسط کانال یا مالک محتوایی که داده‌های درخواستی را در اختیار دارد، مجاز باشد.

گزارش مطالب

گزارش هایی که API ها بازیابی می کنند شامل دو نوع داده است:

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

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

• معیارها اندازه گیری های فردی فعالیت کاربر، عملکرد تبلیغات یا درآمد تخمینی هستند. معیارهای فعالیت کاربر شامل مواردی مانند تعداد بازدید و رتبه بندی ویدیو (پسندیدن و نپسندیدن) است.

API مناسب برای برنامه خود انتخاب کنید

YouTube Analytics API

YouTube Analytics API از پرس و جوهای هدفمند بلادرنگ برای تولید گزارش های YouTube Analytics سفارشی پشتیبانی می کند. API پارامترهای فیلتر و مرتب سازی را فراهم می کند، بنابراین برنامه فراخوانی نیازی به پشتیبانی بومی از این توابع ندارد.

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

YouTube Reporting API

YouTube Reporting API گزارش‌های انبوه حاوی داده‌های YouTube Analytics را برای یک کانال یا مالک محتوا بازیابی می‌کند. برای برنامه‌هایی طراحی شده است که می‌توانند مجموعه‌های داده بزرگ را وارد کنند و ابزارهایی برای فیلتر کردن، مرتب‌سازی و استخراج آن داده‌ها فراهم می‌کنند.

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

علاوه بر این، YouTube به‌طور خودکار مجموعه‌ای از گزارش‌های مدیریت‌شده توسط سیستم را برای صاحبان محتوا تولید می‌کند که به گزارش‌های مربوطه در YouTube Creator Studio دسترسی دارند. این گزارش‌ها دسترسی برنامه‌ریزی شده به داده‌های درآمد تبلیغات را فراهم می‌کنند.

گزارش های پشتیبانی شده

جدول زیر انواع مختلف گزارش هایی را که می توانید با استفاده از API ها بازیابی کنید، مشخص می کند. جستارهای هدفمند از طریق YouTube Analytics API و گزارش‌های انبوه از طریق YouTube Reporting API در دسترس هستند.

داده هایی که در یک API موجود است ممکن است در دیگری در دسترس نباشد. به عنوان مثال، YouTube Analytics API به شما امکان می دهد معیارهای فعالیت کاربر را به صورت هفتگی یا ماهانه بازیابی کنید، اما YouTube Reporting API از شما می خواهد که خودتان این داده ها را جمع آوری کنید. از سوی دیگر، YouTube Reporting API از گزارش‌های دارایی برای صاحبان محتوا پشتیبانی می‌کند، اما این داده‌ها از API YouTube Analytics در دسترس نیستند.

انواع گزارش
گزارش های تصویری	برای کانال ها ( پرس و جو یا انبوه ) و صاحبان محتوا ( پرس و جو یا انبوه ) پشتیبانی می شود. گزارش‌های ویدیویی آماری را برای تمام فعالیت‌های کاربر مربوط به ویدیوهای کانال یا ویدیوهای مالک محتوا ارائه می‌کنند. برای مثال، این گزارش‌ها شامل تعداد بازدیدهایی است که ویدیوهای شما دریافت کرده‌اند. در YouTube Analytics API، برخی از گزارش‌های ویدیویی مالک محتوا همچنین شامل معیارهای درآمد تخمینی و عملکرد تبلیغات می‌شوند.
گزارش لیست پخش	برای کانال ها ( پرس و جو یا انبوه ) و صاحبان محتوا ( پرس و جو یا انبوه ) پشتیبانی می شود. گزارش‌های فهرست پخش آماری را ارائه می‌کنند که به طور خاص به بازدیدهای ویدیویی مربوط می‌شود که در زمینه یک لیست پخش رخ می‌دهد. YouTube Reporting API از گزارش‌های حفظ مخاطب برای لیست‌های پخش پشتیبانی می‌کند، اما YouTube Analytics API از گزارش مشابهی پشتیبانی نمی‌کند.
گزارش عملکرد تبلیغات	برای صاحبان محتوا ( پرس و جو یا انبوه ) پشتیبانی می شود. گزارش‌های عملکرد آگهی، معیارهای مبتنی بر نمایش را برای تبلیغاتی که در حین پخش ویدیو اجرا می‌شوند، ارائه می‌کنند. این معیارها برای هر نمایش تبلیغاتی حساب می‌شوند و هر بازپخش ویدیو می‌تواند چندین بار نمایش را به همراه داشته باشد.
گزارش درآمد تخمینی	برای صاحبان محتوا ( انبوه ) پشتیبانی می شود. گزارش‌های درآمد تخمینی کل درآمد تخمینی ویدیوها را از منابع تبلیغاتی فروخته شده توسط Google و از منابع غیر تبلیغاتی ارائه می‌کند. این گزارش ها همچنین حاوی برخی از معیارهای عملکرد تبلیغات هستند. توجه داشته باشید که گزارش های مدیریت شده توسط سیستم حاوی درآمد واقعی هستند.
گزارش های دارایی	برای صاحبان محتوا ( انبوه ) پشتیبانی می شود. گزارش‌های دارایی معیارهای فعالیت کاربر مربوط به ویدیوهایی را ارائه می‌کند که به دارایی‌های مالک محتوا پیوند دارند. اگر مالک محتوا آن ویدیو را مطابق با یکی از دارایی‌های مالک محتوا ادعا کرده باشد، ویدیویی در گزارش مالک محتوا گنجانده می‌شود. این ویدیو ممکن است توسط مالک محتوا یا کاربر دیگری از YouTube آپلود شده باشد.
گزارش های مدیریت شده توسط سیستم	برای دارندگان محتوا که به گزارش‌های مربوطه در منوی گزارش‌های استودیوی سازندگان YouTube دسترسی دارند، پشتیبانی می‌شود. گزارش‌های مدیریت‌شده توسط سیستم، داده‌های درآمد واقعی کسب‌شده توسط دارایی‌ها و ویدیوها را ارائه می‌کنند. یک گزارش اضافی، ویدیوهای ادعا شده و دارایی‌هایی را که این ویدیوها مطابقت دارند فهرست می‌کند. توجه داشته باشید که در حال حاضر همه گزارش‌های Creator Studio در API موجود نیستند. توجه: YouTube به‌طور خودکار گزارش‌های مدیریت‌شده توسط سیستم را برای صاحبان محتوا تولید می‌کند که به گزارش‌های مربوطه در Creator Studio دسترسی دارند. در نتیجه، روند بازیابی این گزارش‌ها با انواع دیگر گزارش‌های این فهرست متفاوت است. برای اطلاعات بیشتر به مستندات گزارش های مدیریت شده توسط سیستم مراجعه کنید.

تفاوت های کلیدی

جدول زیر تفاوت های مهم بین APIهای YouTube Analytics و Reporting را نشان می دهد.

ویژگی	YouTube Analytics API	YouTube Reporting API
فرآیند بازیابی داده ها	هر درخواست API ابعاد و معیارهایی را که باید بازگردانده شوند و همچنین دوره زمانی که داده‌ها برای آن بازگردانده می‌شوند را مشخص می‌کند.	برنامه های کاربردی گزارش مشاغل. برای هر شغل، یوتیوب گزارش‌های روزانه تولید می‌کند که می‌توانند به صورت ناهمزمان دانلود شوند.
محدوده تاریخ	برخی از گزارش‌های API تاریخ وقوع فعالیت کاربر را مشخص می‌کنند. برخی از این گزارش‌ها از ابعادی برای جمع‌آوری معیارهای فعالیت کاربر بر اساس ماه پشتیبانی می‌کنند.	همه گزارش‌های API روزی را مشخص می‌کنند که فعالیت کاربر رخ داده است. برنامه‌های کاربردی با استفاده از API می‌توانند ویژگی‌هایی را برای جمع‌آوری داده‌ها برای فواصل دوره‌ای پیاده‌سازی کنند.
فیلتر کردن داده ها	می‌توانید گزارش‌ها را فیلتر کنید تا فقط ردیف‌هایی را شامل شود که یک بعد برای آن‌ها مقدار خاصی دارد. API همچنین از برخی ابعاد مانند قاره و زیر قاره پشتیبانی می کند که فقط به عنوان فیلتر استفاده می شوند.	API از دانلود انبوه مجموعه داده های کامل پشتیبانی می کند. از فیلتر کردن یا برگرداندن داده‌ها برای ابعاد فقط فیلتر پشتیبانی نمی‌کند. برنامه مشتری داده های دانلود شده را ذخیره می کند و ویژگی های خود را برای فیلتر کردن داده ها پیاده سازی می کند.
مرتب سازی	گزارش ها را می توان بر اساس مقادیر متریک برگشتی مرتب کرد. برخی از گزارش ها تنها تعداد محدودی از نتایج را پشتیبانی می کنند. برای مثال، گزارشی که بیشترین بازدیدکننده ویدیوهای یک کانال را فهرست می‌کند، حداکثر 200 ردیف را برمی‌گرداند.	این API از دانلود انبوه مجموعه داده های کامل پشتیبانی می کند. برنامه های کاربردی مشتری می توانند ویژگی های خود را برای مرتب سازی داده های دانلود شده پیاده سازی کنند.
شمارش ها	گزارش‌های API حاوی مقادیر متنی مانند «ANDROID» یا «CHANNEL» هستند تا مقادیر ابعاد شمارش شده را شناسایی کنند.	گزارش‌های API حاوی اعداد صحیحی هستند که می‌توانند با مقادیر متنی نگاشت شوند.
سهمیه، سهم	سرور API هر پرس و جو را برای تعیین هزینه سهمیه آن ارزیابی می کند. بخش استفاده از سهمیه روش شناسی را با جزئیات بیشتری توضیح می دهد.	استفاده از سهمیه مشکلی نیست زیرا داده ها یک بار بازیابی می شوند و سپس در برنامه فیلتر، مرتب شده و جستجو می شوند.
گزارش های منحصر به فرد		فعالیت کاربر مربوط به زیرنویس داده های حفظ مخاطب برای لیست های پخش گزارش درآمد تخمینی برای صاحبان محتوا (2 گزارش مختلف موجود است) گزارش دارایی برای صاحبان محتوا (11 گزارش مختلف موجود است)
ابعاد منحصر به فرد	گروه (بعد فقط فیلتر) قاره (فقط بعد فیلتر) زیر قاره (بعد فقط فیلتر) ماه isCurated ==1 (بعد فقط فیلتر) viewsPerPlaylistStart averageTimeInPlaylist	annotation_id annotation_type دارایی_id card_id نوع کارت زنده_یا_طبق_تقاضا subscribed_status زیرنویس_زبان
معیارهای منحصر به فرد	منحصر به فرد نسبیRetentionPerformance viewsPerPlaylistStart averageTimeInPlaylist	نرخ_کارت_کلیک کارت_کلیک card_impressions کارت_تیزر_میزان_کلیک کارت_تیزر_کلیک card_teaser_impressions برآورد_شریک_adsense_revenue برآورد_شریک_دوبار_کلیک_درآمد playlist_saves_added playlist_saves_removed

تفاوت نامگذاری بین APIها

دو API در حال حاضر از قراردادهای نامگذاری متفاوتی برای شناسایی ابعاد و معیارها استفاده می کنند. در حال حاضر، نام‌های API YouTube Analytics از camelCase استفاده می‌کنند، در حالی که نام‌های API گزارش YouTube از نام‌های محدود شده با زیرخط استفاده می‌کنند.

جداول زیر نام های مختلفی را مشخص می کند که دو API برای شناسایی معیارها و ابعاد یکسان استفاده می کنند. در برخی موارد، تفاوت بین این دو نام بیشتر از چیزی است که پس از تبدیل نام از camelCase به underscore بدست می آورید. برای مثال، بعد video در YouTube Analytics API در YouTube Reporting API video_id نام دارد.

ابعاد

نام API YouTube Analytics	نام API گزارش YouTube
نوع آگهی	ad_type
گروه سنی	گروه سنی
دارایی	دارایی_id
نوع مخاطب	مخاطب_حفظ_نوع
کانال	channel_id
وضعیت ادعا شده	ادعای_وضعیت
صاحب محتوا	content_owner_id
کشور	کد کشور
روز	تاریخ
نوع وسیله	نوع وسیله
سپری شدهVideoTimeRatio	سپری شده_ویدئو_زمان_درصد
جنسیت	جنسیت
insightPlaybackLocationDetail	playback_location_detail
insightPlaybackLocationType	پخش_موقعیت_نوع
insightTrafficSourceDetail	ترافیک_منبع_جزئیات
insightTrafficSourceType	traffic_source_type
liveOrOnDemand	زنده_یا_طبق_تقاضا
سیستم عامل	سیستم عامل
لیست پخش	playlist_id
استان	استان_کد
سرویس اشتراک گذاری	اشتراک_سرویس
وضعیت مشترک	subscribed_status
زبان زیرنویس	زیرنویس_زبان
UploaderType	uploader_type
ویدئو	video_id

معیارهای

نام API YouTube Analytics	نام API گزارش YouTube
درآمدهای تبلیغاتی	برآورد شده_شریک_آگهی
annotationImpressions	annotation_impressions
annotationClickableImpressions	annotation_clickable_impressions
حاشیه نویسی کلیک ها	annotation_clicks
annotationClickThroughRate	annotation_click_through_rate
annotationClosableImpressions	annotation_closable_impressions
حاشیه نویسی بسته می شود	annotation_closes
annotationCloseRate	annotation_close_rate
نسبت تماشای مخاطب	مخاطب_حفظ_درصد
averageViewDuration	average_view_duration_seconds
averageViewPercentage	میانگین_نمایش_دوره_درصد
cardClickRate	نرخ_کارت_کلیک
cardClicks	کارت_کلیک
CarImpressions	card_impressions
cardTeaserClickRate	کارت_تیزر_میزان_کلیک
cardTeaserClicks	کارت_تیزر_کلیک
cardTeaserImpressions	card_teaser_impressions
نظرات	نظرات
دوست ندارد	دوست ندارد
درآمد	برآورد_درآمد_شریک
تخمین زده شده Minutes Watched	ساعت_دقیقه
برآورد درآمد PartnerAdSense	برآورد_شریک_adsense_revenue
برآورد شدهPartnerDoubleClickRevenue	برآورد_شریک_دوبار_کلیک_درآمد
درآمد ناخالص	برآورد شده_youtube_ad_revenue
impressionBasedCpm	برآورد_cpm
برداشت ها	ad_impressions
دوست دارد	دوست دارد
پخش های پولی	تخمین زده_پول_بازپخش
playbackBasedCpm	تخمین زده شده_بازپخش_بر اساس_cpm
لیست پخش شروع می شود	playlist_starts
ذخیره اضافه شد	playlist_saves_added
ذخیره حذف شد	playlist_saves_removed
سهام	سهام
مشترکین به دست آمده	subscribers_gained
مشترکین گم شده	subscribers_lost
videosAddedToPlaylists	videos_added_to_playlists
videosRemovedFromPlaylists	videos_removed_from_playlist
بیننده درصد	views_percentage
دیدگاه ها	دیدگاه ها