YouTube Analytics API به شما امکان می‌دهد گزارش‌های سفارشی حاوی داده‌های YouTube Analytics تولید کنید. این میانای برنامه‌سازی کاربردی از گزارش‌های کانال‌ها و مالکان محتوا پشتیبانی می‌کند. فیلدهای گزارش به‌عنوان بُعد یا سنجه مشخص می‌شوند:
ابعاد معیارهای رایجی هستند که برای تجمیع داده‌ها استفاده می‌شوند، مانند تاریخی که کنش در آن رخ داده است یا کشوری که کاربران در آن مستقر بوده‌اند.
در گزارش، هر ردیف داده ترکیب منحصربه‌فردی از مقادیر بُعد دارد. بنابراین، ابعادی که برای گزارش انتخاب می‌کنید تعیین می‌کند که YouTube چگونه مقادیر سنجه‌ها را در آن گزارش محاسبه کند.
سنجه‌ها اندازه‌گیری‌های فردی مربوط به فعالیت کاربر، عملکرد آگهی، یا درآمد تخمینی هستند. سنجه‌های فعالیت کاربر شامل مواردی مانند تعداد بازدیدهای ویدیو و رتبه‌بندی‌ها (پسندیدن‌ها و نپسندیدن‌ها) است.
Analytics API پارامترهای فیلتر کردن و مرتب‌سازی را ارائه می‌دهد، بنابراین برنامه فراخواننده نیازی به پشتیبانی بومی از این توابع ندارد. این API همچنین به شما امکان می‌دهد داده‌های گروه‌های YouTube Analytics را بازیابی کنید، که در آن گروه مجموعهای سفارشی از حداکثر ۵۰۰ ویدیو، فهرست پخش، کانال، یا دارایی است.
انتخاب پارامترهای گزارش
وقتی بااستفاده از روش reports.query میانای برنامه‌سازی کاربردی گزارشی درخواست می‌کنید، درخواست میانای برنامه‌سازی کاربردی حاوی پنج پارامتر است که نحوه محاسبه مقادیر گزارش را تعیین می‌کند:
پارامترهای
startDateوendDateدوره زمانی‌ای را که گزارش حاوی داده خواهد بود مشخص می‌کنند. پاسخ میانای برنامه‌سازی کاربردی درواقع حاوی داده‌ها تا آخرین روز مشخص‌شده‌ای است که همه سنجه‌های در پرسمان در زمان پرسمان دردسترس هستند.پارامتر
metricsاندازه‌گیری‌هایی را که در گزارش گنجانده خواهد شد مشخص می‌کند. در گزارش‌های کانال، سنجه‌ها فعالیت کاربر را اندازه‌گیری می‌کنند و شامل مقادیری مانند بازدیدها و پسندیدن‌ها هستند. برخی‌از سنجه‌ها عملکرد آگهی یا درآمد تخمینی را نیز اندازه‌گیری می‌کنند.پارامتر
dimensionsتوضیح می‌دهد که سنجه‌ها چگونه گروه‌بندی خواهند شد.پارامتر
filtersتوضیح می‌دهد که داده‌های گزارش چگونه فیلتر خواهند شد. بنابراین، برای مثال، به‌جای برگرداندن همه داده‌های یک کانال، می‌توان گزارش را فیلتر کرد تا فقط شامل سنجه‌های مربوط به یک کشور، ویدیو، یا گروهی از ویدیوها باشد.توجه: API به شما امکان می‌دهد چندین مقدار برای فیلترهای ویدیو، فهرست پخش، و کانال مشخص کنید. اگر این کار را انجام دهید، می‌توانید آن فیلتر را در فهرست ابعاد نیز بگنجانید تا سنجه‌های برگردانده‌شده براساس ویدیو، فهرست پخش، یا کانال نیز گروه‌بندی شوند.
گزینه‌های گزارش‌دهی نمونه
به‌عنوان مثال، فرض کنید مالک کانال می‌خواهد گزارش نوع دستگاه ویدیو را بازیابی کند تا تعیین کند چند بازدید از ویدیوهای کانال در دستگاه‌های همراه، کنسول‌های بازی، تلویزیون‌ها و غیره رخ داده است.
مالک کانال پارامتر
startDateرا روی2015-06-01و پارامترendDateرا روی2015-07-31تنظیم می‌کند. براساس این مقادیر، گزارش حاوی داده‌های مربوط به دوره دوماهه خواهد بود.گزارش نوع دستگاه از سنجه‌های views و estimatedMinutesWatched پشتیبانی می‌کند، بنابراین مالک کانال پارامتر
metricsرا رویviews,estimatedMinutesWatchedتنظیم می‌کند.برای پارامتر
dimensions، مالک کانال چند گزینه دارد. دو مورد از آن‌ها در فهرست زیر نشان داده شده است و مورد سوم در توضیح مقدار پارامترfiltersدر ادامه این بخش مورد بحث قرار می‌گیرد.تنظیم مقدار پارامتر روی
deviceTypeبه این معنی است که تعداد بازدیدها و تعداد زمان تماشا براساس نوع دستگاه برای کل دوره‌ای که گزارش پوشش می‌دهد گروه‌بندی خواهد شد. بنابراین، با این مقدار، داده‌های گزارش به سؤالاتی مانند زیر پاسخ خواهند داد:ویدیوهای کانال چند بار در دستگاه‌های همراه بین ۱ ژوئن ۲۰۱۵ و ۳۱ ژوئیه ۲۰۱۵ بازدید شده‌اند؟
ویدیوهای کانال چند بار در کنسول‌های بازی بین ۱ ژوئن ۲۰۱۵ و ۳۱ ژوئیه ۲۰۱۵ مشاهده شده‌اند؟
گزارش درواقع شامل تعداد کل بازدید و زمان تماشا برای هر نوع دستگاه خواهد بود.
تنظیم مقدار پارامتر روی
day,deviceTypeبه این معنی است که تعداد بازدیدها و تعداد زمان تماشا براساس نوع دستگاه برای هر روز درطول دوره گزارش‌دهی محاسبه خواهد شد. بنابراین، با این مقدار، داده‌های گزارش به سؤالاتی مانند زیر پاسخ خواهند داد:ویدیوهای کانال چند بار در تاریخ ۱ ژوئن ۲۰۱۵ در دستگاه‌های همراه مشاهده شده‌اند؟
ویدیوهای کانال چند بار در ۱۴ ژوئیه ۲۰۱۵ در تلویزیون‌ها بازدید شدند؟
درنهایت، پارامتر
filtersبه مالک کانال اجازه می‌دهد گزارش را محدود کند تا فقط شامل داده‌های منطبق با مقادیر فیلتر خاص باشد. این گزارش از گزینه‌های فیلتر کردن بسیار زیادی پشتیبانی می‌کند که نمی‌توان همه آن‌ها را توضیح داد، بنابراین این نمونه‌ها فقط بخشی از گزارش‌هایی را نشان می‌دهند که می‌توانید تولید کنید.مالک کانال می‌تواند درخواست را فیلتر کند تا مقادیر را فقط برای سیستم‌عامل Android برگرداند. (چند بازدید در دستگاه‌های همراه Android درطول دوره گزارش‌دهی رخ داده است؟)
مالک کانال می‌تواند درخواست را فیلتر کند تا مقادیر را فقط برای یک کشور خاص برگرداند. (ویدیوها چند بار در کانادا در هر روز از دوره گزارش‌دهی بازدید شده‌اند؟)
مالک کانال می‌تواند درخواست را فیلتر کند تا مقادیر را فقط برای ویدیوهای خاصی برگرداند. اما فیلتر ویدیو از فهرستی از مقادیر جداشده با کاما پشتیبانی می‌کند، بنابراین گزارش می‌تواند درواقع حاوی داده‌های مربوط به ویدیوهای زیادی باشد.
علاوه‌براین، اگر فیلتر ویدیو چندین مقدار را مشخص کند، ویدیو نیز می‌تواند به‌عنوان یک بعد مشخص شود. یعنی پارامتر
dimensionsاز مقادیرdeviceType,videoوday,deviceType,videoنیز پشتیبانی می‌کند.- اگر مالک کانال ویدیو را در فهرست ابعاد قرار دهد، سنجه‌ها مقادیر جداگانه‌ای را برای هر ویدیو مشخص می‌کنند. (ویدیو XYZ چند بار در تاریخ ۱ ژوئن ۲۰۱۵ در کنسول بازی مشاهده شده است؟)
- اگر مالک کانال ویدیو را در فهرست ابعاد قرار ندهد، سنجه‌ها مقادیر کل را برای همه ویدیوهای مشخص‌شده تعیین می‌کنند. (ویدیوهای ABC، DEF، و XYZ چند بار در تاریخ ۱ ژوئن ۲۰۱۵ در کنسول بازی مشاهده شده‌اند؟)
به‌روز بودن و تأخیر داده‌ها
YouTube Analytics API از پُرسمان‌های هدف‌گیری‌شده پشتیبانی می‌کند، اما داده‌های تجزیه‌وتحلیل زیربنایی هم‌زمان نیستند. پردازش داده معمولاً تأخیری
۴۸ تا ۷۲ ساعته ایجاد می‌کند. بنابراین، پاسخ‌های API حاوی داده‌های مربوط به چند روز اخیر نیستند و endDate گزارش شما فقط شامل داده‌های مربوط به آخرین روزی است که همه سنجه‌های درخواستی به‌طور کامل پردازش شده‌اند.
باتوجه‌به تأخیر داده‌ها، ممکن است بین داده‌های برگردانده‌شده توسط API و سنجه‌های هم‌زمان قابل‌مشاهده در «استودیوِ YouTube» مغایرت‌هایی مشاهده کنید. اگر برنامه شما به آمار هم‌زمان برای ویدیوهای تکی نیاز دارد، مانند تعداد بازدید، پسندیدن، یا نظر فعلی، به‌جای YouTube Analytics API از روش YouTube Data APIvideos.list استفاده کنید.
درحال بازیابی گزارش‌ها
برای بازیابی گزارش، درخواست GET مجاز به روش
reports.query میانای برنامه‌سازی کاربردی ارسال کنید،
پارامترهایی را که گزارش موردنظرتان برای بازیابی را تعریف می‌کند مشخص کنید.
برای مشاهده فهرست گزارش‌هایی که این میانای برنامه‌سازی کاربردی پشتیبانی می‌کند، به اسناد گزارش‌های کانال و گزارش‌های مالک محتوا مراجعه کنید. هر تعریف گزارش مقادیری را که گزارش برای پارامترهای metrics، dimensions، و filters مجاز می‌داند شناسایی می‌کند.
روال‌های مطلوب
برنامه‌هایی که از YouTube Analytics API استفاده می‌کنند باید همیشه این شیوه‌ها را دنبال کنند:
- از ردیف سرصفحه پاسخ برای تعیین ترتیب ستون‌های گزارش استفاده کنید. برای مثال، فرض نکنید که بازدیدها اولین سنجه‌ای خواهد بود که در پاسخ برگردانده می‌شود، فقط به این دلیل که اولین سنجه فهرست‌شده در شرح گزارش است. درعوض، از ردیف سرصفحه پاسخ برای تعیین اینکه کدام ستون حاوی آن داده است استفاده کنید.
- از YouTube Data API برای بازیابی فراداده‌های اضافی برای منابع شناسایی‌شده در پاسخ‌های YouTube Analytics API استفاده کنید. همان‌طور که در خط‌مشی‌های توسعه‌دهنده سرویس‌های YouTube API (بخش‌های III.E.4.b تا III.E.4.d) ذکر شده است، کارخواه‌های API باید فراداده منبع ذخیره‌شده از آن API را پس‌از ۳۰ روز حذف یا بازآوری کنند.
سنجه‌های انبوهشی و موارد حذف‌شده
پاسخ‌های YouTube Analytics API شامل تفکیک سنجه برای موارد حذف‌شده نیست. برای مثال، اگر مالک کانال ویدیویی را حذف کند، آن ویدیو دیگر در پاسخ میانای برنامه‌سازی کاربردی که سنجه‌ها را به‌صورت ویدیو به ویدیو برمی‌گرداند فهرست نخواهد شد. بااین‌حال، گزارش‌هایی که سنجه‌ها را برای مجموعهای از منابع تجمیع می‌کنند همچنان شامل سنجه‌های مرتبط با موارد حذف‌شده هستند.
برای مثال، فرض کنید مالک کانال دو گزارش را بازیابی می‌کند. گزارش اول مجموع بازدیدهای روزانه را برای همه ویدیوهای کانال در یک دوره زمانی خاص فهرست می‌کند. گزارش دوم مجموع بازدیدهای روزانه را به‌صورت ویدیو به ویدیو در همان دوره زمانی فهرست می‌کند.
در این حالت، اعداد گزارش اول شامل بازدیدهای ویدیوهایی خواهد بود که بعداً حذف شده‌اند، زیرا گزارش اول حاوی مجموعهای روزانه است. بااین‌حال، گزارش دوم شامل بازدیدهای مرتبط با موارد حذف‌شده نخواهد بود زیرا گزارش دوم بازدیدها را به‌صورت ویدیو به ویدیو فهرست می‌کند. درنتیجه، اگر کانال درطول دوره زمانی تحت پوشش گزارش ویدیوها را حذف کرده باشد، مجموع تعداد بازدیدهای روزانه گزارش‌شده در گزارش اول ممکن است بیشتر از مجموع تعداد بازدیدهای روزانه مختص ویدیو در گزارش دوم باشد.
ناشناس‌سازی داده‌ها
وقتی سنجه‌ها به آستانه خاصی نرسد، برخی داده‌های YouTube Analytics محدود می‌شود. این مسئله ممکن است در گزارش‌های مختلفی رخ دهد. در عمل، این یعنی ممکن است گزارش حاوی همه (یا هیچ‌کدام از) داده‌های شما نباشد اگر:
یک ویدیو یا کانال در یک دوره زمانی مشخص ترافیک محدودی داشته باشد،
یا
فیلتر یا بعدی را انتخاب کرده باشید، مثلاً منبع ترافیک یا کشور، که مقادیر به‌ازای آن‌ها به آستانه معین نرسیده است.
در مواردی که داده‌ها محدود است، بسته به تجمیع داده در آن گزارش‌ها، ممکن است بین گزارش‌های کلی که در هر گزارش ارائه شده تفاوتی وجود داشته باشد.
برای مثال، فرض کنید مالک کانال دو گزارش را بازیابی می‌کند. گزارش اول کل بازدیدهای یک ویدیو خاص را فهرست می‌کند و گزارش دوم کل بازدیدهای آن ویدیو را به‌تفکیک کشور فهرست می‌کند. در دوره زمانی معین، فرض کنید که ویدیو ۱۰۰۰ بار مشاهده شده و ۵۰۰ بازدید در ایالات متحده، ۴۹۸ بازدید در کانادا و دو بازدید در فرانسه رخ داده است.
در این مثال، گزارش اول نشان می‌دهد که ویدیو 1000 بار مشاهده شده است. گزارش دوم فقط نشان می‌دهد که ویدیو 500 بار در ایالات متحده و 498 بار در کانادا مشاهده شده است. به این ترتیب، بین تعداد بازدیدهای کل در دو گزارش تفاوت بوجود می‌آید. توجه داشته باشید که گزارش دوم هیچ نشانه‌ای از اینکه دو بازدید دیگر هم رخ داده است (یا اینکه بازدیدی در فرانسه رخ داده است) نخواهد داشت.
انواع داده‌های محدود
داده‌های زیر ممکن است در گزارش‌های YouTube Analytics محدود شود:
- داده‌های جمعیتی مثل سن و جنسیت.
- داده‌های جغرافیایی، ازجمله سنجه‌ها یا ابعاد مربوط به کشورها یا مناطقی که بینندگان در آنجا ساکن هستند، مانند کشورها یا مناطق آن‌ها. بااین‌حال، توجه داشته باشید که گزارش‌ها آستانه‌های جغرافیایی را برای سنجه‌های درآمد اعمال نمی‌کنند.
- سنجه‌های مربوط به منابع ترافیک خاص، مانند عبارت‌های جستجو یا نشانی‌های وب خارجی که منجر به بازدید از ویدیوهای شما شده‌اند. برای مثال، عبارات جستجو و نشانی‌های وب که تعداد بسیار کمی بازدید ایجاد می‌کنند در گزارش‌ها نشان داده نمی‌شوند، اما همچنان عبارات و نشانی‌های وب که بینندگان زیادی را به محتوای شما هدایت می‌کنند خواهید دید.
برای اطلاعات بیشتر درباره داده‌های محدود در گزارش‌های YouTube Analytics، به مرکز راهنمایی YouTube مراجعه کنید.
مصرف سهمیه
هر درخواست API که ارائه می‌دهید به‌عنوان یک واحد از سهمیه استفاده از API شما محسوب می‌شود. محدودیت‌های سهمیه در پانل سهمیه‌ها در کنسول Google Cloud قابل‌مشاهده است.