این سند شباهتها و تفاوتهای روشهای دسترسی به دادههای YouTube Analytics توسط API یوتیوب آنالیتیکس و API گزارشدهی یوتیوب را توضیح میدهد تا بتوانید API مناسب را برای برنامه خود انتخاب کنید.
هر دو API به شما امکان میدهند دادههای YouTube Analytics را بازیابی کنید. علاوه بر این، هر دو API از مالکان کانالهای YouTube و مالکان محتوای YouTube پشتیبانی میکنند که هر کدام میتوانند به مجموعهای خاص از گزارشها دسترسی داشته باشند:
گزارشهای کانال شامل معیارهای فعالیت کاربر برای یک کانال مشخص شده است.
مالک محتوا، معیارهای کلی را برای تمام کانالهای مرتبط با یک مالک محتوای یوتیوب مشخص گزارش میدهد . به عنوان مثال، یک ناشر موسیقی میتواند گزارشی حاوی آمار ترکیبی برای کانالهای یوتیوب تمام هنرمندان آن ناشر را بازیابی کند. برخی از گزارشهای مالک محتوا حاوی معیارهای فعالیت کاربر هستند، در حالی که برخی دیگر حاوی معیارهای مربوط به درآمد و عملکرد تبلیغات هستند.
API گزارشدهی همچنین به برخی از دارندگان محتوا اجازه میدهد تا به گزارشهای درآمد تبلیغاتی مدیریتشده توسط سیستم دسترسی داشته باشند. دادههای موجود در گزارشهای مدیریتشده توسط سیستم فقط با API گزارشدهی قابل بازیابی هستند.
تمام درخواستهای YouTube Analytics و YouTube Reporting API باید توسط مالک کانال یا محتوایی که دادههای درخواستی را در اختیار دارد، تأیید شود.
گزارش محتویات
گزارشهایی که APIها بازیابی میکنند شامل دو نوع داده هستند:
ابعاد، معیارهای رایجی هستند که برای جمعآوری دادهها استفاده میشوند، مانند تاریخی که فعالیت کاربر رخ داده است یا کشوری که کاربران در آن قرار دارند.
در یک گزارش، هر ردیف از دادهها ترکیبی منحصر به فرد از مقادیر بُعد دارد. به این ترتیب، ترکیب مقادیر بُعد هر ردیف به عنوان کلید اصلی آن ردیف عمل میکند.
معیارها، اندازهگیریهای فردی از فعالیت کاربر، عملکرد تبلیغات یا درآمد تخمینی هستند. معیارهای فعالیت کاربر شامل مواردی مانند تعداد بازدید ویدیو و رتبهبندی (لایک و دیسلایک) میشود.
API مناسب برای برنامه خود را انتخاب کنید
- رابط برنامهنویسی کاربردی یوتیوب آنالیتیکس
- API یوتیوب آنالیتیکس از کوئریهای هدفمند بلادرنگ برای تولید گزارشهای سفارشی یوتیوب آنالیتیکس پشتیبانی میکند. این API پارامترهای فیلتر و مرتبسازی را ارائه میدهد، بنابراین برنامه فراخوانی نیازی به پشتیبانی بومی از این توابع ندارد.
هر درخواست API محدوده تاریخی که دادهها برای آن بازگردانده میشوند را مشخص میکند. API همچنین به شما امکان میدهد مجموعه دادههای هفتگی و ماهانه را بازیابی کنید. به این ترتیب، برنامه فراخوانی نیازی به ذخیره مجموعه دادههای بازیابی شده یا جمعآوری آمار در محدودههای تاریخی ندارد. - API گزارش یوتیوب
- API گزارشدهی یوتیوب، گزارشهای انبوه حاوی دادههای YouTube Analytics را برای مالک کانال یا محتوا بازیابی میکند. این API برای برنامههایی طراحی شده است که میتوانند مجموعه دادههای بزرگی را وارد کنند و ابزارهایی برای فیلتر کردن، مرتبسازی و استخراج این دادهها ارائه میدهند.
هر گزارش شامل مجموعهای از فیلدهای از پیش تعریفشده است. شما از API برای برنامهریزی کارهای گزارشدهی استفاده میکنید که هر کدام گزارشی را که یوتیوب باید تولید کند، مشخص میکنند. سپس یوتیوب یک گزارش روزانه تولید میکند که میتوان آن را به صورت غیرهمزمان دانلود کرد. هر گزارش شامل دادههایی برای یک دوره ۲۴ ساعته منحصر به فرد است.
علاوه بر این، یوتیوب به طور خودکار مجموعهای از گزارشهای مدیریتشده توسط سیستم را برای مالکان محتوا که به گزارشهای مربوطه در YouTube Creator Studio دسترسی دارند، ایجاد میکند. این گزارشها دسترسی برنامهریزیشده به دادههای درآمد حاصل از تبلیغات را فراهم میکنند.
گزارشهای پشتیبانیشده
جدول زیر انواع مختلف گزارشهایی را که میتوانید با استفاده از APIها بازیابی کنید، مشخص میکند. پرسوجوهای هدفمند با استفاده از YouTube Analytics API و گزارشهای انبوه با استفاده از YouTube Reporting API در دسترس هستند.
دادههایی که در یک API موجود است، ممکن است در دیگری موجود نباشد. برای مثال، API YouTube Analytics به شما امکان میدهد معیارهای فعالیت کاربر را به صورت هفتگی یا ماهانه بازیابی کنید، اما API گزارشدهی YouTube شما را ملزم میکند که خودتان آن دادهها را جمعآوری کنید. از سوی دیگر، API گزارشدهی YouTube از گزارشهای دارایی برای مالکان محتوا پشتیبانی میکند، اما آن دادهها از API YouTube Analytics در دسترس نیستند.
| انواع گزارش | |
|---|---|
| گزارشهای ویدیویی | برای کانالها ( پرسوجو یا انبوه ) و مالکان محتوا ( پرسوجو یا انبوه ) پشتیبانی میشود. گزارشهای ویدیویی، آماری از تمام فعالیتهای کاربران مربوط به ویدیوهای یک کانال یا ویدیوهای صاحب محتوا ارائه میدهند. برای مثال، این گزارشها شامل تعداد بازدیدهایی است که ویدیوهای شما دریافت کردهاند. در API تجزیه و تحلیل یوتیوب، برخی از گزارشهای ویدیویی صاحب محتوا شامل درآمد تخمینی و معیارهای عملکرد تبلیغات نیز میشوند. |
| گزارشهای دسترسی | برای کانالها ( به صورت انبوه ) و مالکان محتوا ( به صورت انبوه ) پشتیبانی میشود. معیارهای دسترسی (reach metrics) نیز در گزارشهای ویدیویی برای جستجوهای هدفمند در دسترس هستند. گزارشهای Reach، آماری از تعداد نمایش ویدیوها و نرخ کلیک ارائه میدهند. |
| گزارشهای لیست پخش | برای کانالها ( پرسوجو یا انبوه ) و مالکان محتوا ( پرسوجو یا انبوه ) پشتیبانی میشود. گزارشهای لیست پخش، آماری را ارائه میدهند که بهطور خاص مربوط به بازدیدهای ویدیویی است که در متن یک لیست پخش رخ میدهد. API گزارشدهی یوتیوب از گزارشهای حفظ مخاطب برای لیستهای پخش پشتیبانی میکند، اما API تجزیه و تحلیل یوتیوب از گزارش مشابهی پشتیبانی نمیکند. |
| گزارشهای عملکرد تبلیغات | برای مالکان محتوا ( پرسوجو یا انبوه ) پشتیبانی میشود. گزارشهای عملکرد تبلیغات، معیارهای مبتنی بر تعداد نمایش تبلیغات را برای تبلیغاتی که در حین پخش ویدیو اجرا شدهاند، ارائه میدهند. این معیارها هر نمایش تبلیغ را در نظر میگیرند و هر پخش ویدیو میتواند چندین نمایش داشته باشد. |
| گزارشهای درآمد تخمینی | برای مالکان محتوا ( به صورت عمده ) پشتیبانی میشود. گزارشهای درآمد تخمینی، کل درآمد تخمینی برای ویدیوها از منابع تبلیغاتی فروخته شده توسط گوگل و از منابع غیرتبلیغاتی را ارائه میدهند. این گزارشها همچنین حاوی برخی از معیارهای عملکرد تبلیغات هستند. توجه داشته باشید که گزارشهای مدیریتشده توسط سیستم حاوی درآمد واقعی هستند. |
| گزارشهای دارایی | برای مالکان محتوا ( به صورت عمده ) پشتیبانی میشود. گزارشهای دارایی، معیارهای فعالیت کاربر مربوط به ویدیوهایی را ارائه میدهند که به داراییهای صاحب محتوا پیوند دارند. اگر صاحب محتوا ادعا کند که آن ویدیو با یکی از داراییهای صاحب محتوا مطابقت دارد، آن ویدیو در گزارش صاحب محتوا گنجانده میشود. این ویدیو میتواند توسط صاحب محتوا یا توسط کاربر دیگری در یوتیوب آپلود شده باشد. |
| گزارشهای مدیریتشده توسط سیستم | برای مالکان محتوایی که به گزارشهای مربوطه در منوی گزارشها در استودیوی خالق یوتیوب دسترسی دارند، پشتیبانی میشود. گزارشهای مدیریتشده توسط سیستم، دادههای درآمد واقعی کسبشده توسط داراییها و ویدیوها را ارائه میدهند. یک گزارش اضافی، ویدیوهای ادعا شده و داراییهایی که این ویدیوها با آنها مطابقت دارند را فهرست میکند. همه گزارشهای Creator Studio در API موجود نیست. توجه: یوتیوب بهطور خودکار گزارشهای مدیریتشده توسط سیستم را برای مالکان محتوایی که به گزارشهای مربوطه در Creator Studio دسترسی دارند، تولید میکند. در نتیجه، فرآیند بازیابی این گزارشها با سایر انواع گزارشهای موجود در این لیست متفاوت است. برای اطلاعات بیشتر به مستندات گزارشهای مدیریتشده توسط سیستم مراجعه کنید. |
تفاوتهای کلیدی
جدول زیر تفاوتهای مهم بین APIهای YouTube Analytics و Reporting را برجسته میکند.
| ویژگی | رابط برنامهنویسی کاربردی یوتیوب آنالیتیکس | API گزارش یوتیوب |
|---|---|---|
| فرآیند بازیابی دادهها | هر درخواست API، ابعاد و معیارهایی را که باید بازگردانده شوند و همچنین دوره زمانی که دادهها بازگردانده میشوند، مشخص میکند. | برنامههای کاربردی، گزارشهای کاری را زمانبندی میکنند. برای هر کار، یوتیوب گزارشهای روزانهای تولید میکند که میتوانند به صورت غیرهمزمان دانلود شوند. |
| محدودههای تاریخ | برخی از گزارشهای API تاریخ وقوع فعالیت کاربر را مشخص میکنند. برخی از این گزارشها از ابعاد (dimension) برای جمعآوری معیارهای فعالیت کاربر بر اساس ماه پشتیبانی میکنند. | تمام گزارشهای API، روزی را که فعالیت کاربر رخ داده است، مشخص میکنند. برنامههایی که از API استفاده میکنند میتوانند ویژگیهایی را برای جمعآوری دادهها برای فواصل زمانی دورهای پیادهسازی کنند. |
| فیلتر کردن دادهها | شما میتوانید گزارشها را فیلتر کنید تا فقط ردیفهایی را شامل شوند که یک بُعد برای آنها مقدار خاصی دارد. این API همچنین از برخی بُعدها، مانند continent و subContinent ، که فقط به عنوان فیلتر استفاده میشوند، پشتیبانی میکند. | این API از دانلودهای انبوه مجموعه دادههای کامل پشتیبانی میکند. از فیلتر کردن یا بازگرداندن دادهها برای ابعاد فقط فیلتر پشتیبانی نمیکند. برنامه کلاینت دادههای دانلود شده را ذخیره کرده و ویژگیهای خاص خود را برای فیلتر کردن دادهها پیادهسازی میکند. |
| مرتبسازی | گزارشها را میتوان بر اساس مقادیر معیار بازگشتی مرتب کرد. برخی گزارشها فقط تعداد محدودی از نتایج را پشتیبانی میکنند. برای مثال، گزارشی که پربازدیدترین ویدیوهای یک کانال را فهرست میکند، حداکثر ۲۰۰ ردیف را برمیگرداند. | این API از دانلودهای انبوه مجموعه دادههای کامل پشتیبانی میکند. برنامههای کلاینت میتوانند ویژگیهای خاص خود را برای مرتبسازی دادههای دانلود شده پیادهسازی کنند. |
| شمارشها | گزارشهای API حاوی مقادیر متنی، مانند "ANDROID" یا "CHANNEL" هستند تا مقادیر بُعد شمارششده را شناسایی کنند. | گزارشهای API حاوی اعداد صحیحی هستند که میتوانند به مقادیر متنی نگاشت شوند. |
| سهمیه | سرور API هر پرسوجو را برای تعیین هزینه سهمیه آن ارزیابی میکند. بخش استفاده از سهمیه، روششناسی را با جزئیات بیشتری توضیح میدهد. | استفاده از سهمیه مشکلی ایجاد نمیکند زیرا دادهها یک بار بازیابی میشوند و سپس درون برنامه فیلتر، مرتبسازی و پرسوجو میشوند. |
| گزارشهای منحصر به فرد |
| |
| ابعاد منحصر به فرد | گروه (بعد فقط فیلتر) قاره (بعد فقط فیلتر) شبه قاره (بعد فقط فیلتر) ماه نمایشهادرلیست پخششروع averageTimeInPlaylist | annotation_id نوع_یادداشت شناسه دارایی کارت_آیدی نوع_کارت زنده_یا_بنا_به_تقاضا وضعیت_مشترک زیرنویس_زبان |
| معیارهای منحصر به فرد | منحصر به فرد عملکرد نسبی حفظ نمایشهادرلیست پخششروع averageTimeInPlaylist | نرخ کلیک_کارت کلیکهای_کارت تعداد نمایش کارتها نرخ_کلیک_کارت_تیزر کلیکهای_تیزر_کارت برداشتهای_تیزکننده_کارت درآمد تخمینی شریک ادسنس درآمد تخمینی_شریک_دوبار_کلیک_در_آمد_لیست_ذخیره_اضافه_شده playlist_saves_removed |
تفاوتهای نامگذاری بین APIها
این دو API از قراردادهای نامگذاری متفاوتی برای شناسایی ابعاد و معیارها استفاده میکنند. نامهای API یوتیوب آنالیتیکس مانند adType از camelCase استفاده میکنند. نامهای API یوتیوب ریپورتینگ با حروف کوچک و با خط تیره نوشته میشوند، مانند ad_type .
جداول زیر نامهای مختلفی را که دو API برای شناسایی معیارها و ابعاد یکسان استفاده میکنند، مشخص میکنند. در برخی موارد، تفاوت بین دو نام بیشتر از آن چیزی است که پس از تبدیل نام از camelCase به underscore به دست میآورید. به عنوان مثال، بُعد video در YouTube Analytics API در YouTube Reporting API به video_id نامگذاری شده است.