YouTube Analytics API به شما امکان می‌دهد گزارش‌های سفارشی حاوی داده‌های YouTube Analytics تولید کنید. API از گزارش‌ها برای کانال‌ها و صاحبان محتوا پشتیبانی می‌کند. فیلدهای گزارش به عنوان ابعاد یا معیارها مشخص می شوند:
ابعاد معیارهای رایجی هستند که برای جمع‌آوری داده‌ها استفاده می‌شوند، مانند تاریخی که یک اقدام در آن رخ داده یا کشوری که کاربران در آن قرار داشتند.
در یک گزارش، هر ردیف از داده ها دارای ترکیبی منحصر به فرد از مقادیر ابعاد است. به این ترتیب، ابعادی که برای یک گزارش انتخاب می‌کنید تعیین می‌کند که YouTube چگونه مقادیر معیارهای آن گزارش را محاسبه می‌کند.
- معیارها اندازه گیری های فردی مربوط به فعالیت کاربر، عملکرد تبلیغات یا درآمد تخمینی هستند. معیارهای فعالیت کاربر شامل مواردی مانند تعداد بازدید و رتبه بندی ویدیو (پسندیدن و نپسندیدن) است.
Analytics API پارامترهای فیلتر و مرتب‌سازی را فراهم می‌کند، بنابراین برنامه فراخوانی نیازی به پشتیبانی بومی از آن توابع ندارد. API همچنین به شما امکان می دهد داده ها را برای گروه های YouTube Analytics بازیابی کنید، جایی که یک گروه مجموعه ای سفارشی از حداکثر 500 ویدیو، لیست پخش، کانال یا دارایی است.
انتخاب پارامترهای گزارش
وقتی گزارشی را درخواست می‌کنید، با استفاده از روش API's reports.query ، درخواست API حاوی پنج پارامتر است که تعیین می‌کنند مقادیر گزارش چگونه محاسبه می‌شوند:
پارامترهای
startDateوendDateدوره زمانی را که گزارش حاوی داده است مشخص می کند. پاسخ API در واقع تا آخرین روز مشخص شده حاوی داده هایی است که تمام معیارهای پرس و جو در زمان پرس و جو در دسترس هستند.پارامتر
metricsاندازه گیری هایی را که در گزارش گنجانده می شود را مشخص می کند. در گزارش‌های کانال، معیارها فعالیت کاربر را اندازه‌گیری می‌کنند و مقادیری مانند بازدیدها و پسندیدن‌ها را شامل می‌شوند. برخی از معیارها عملکرد تبلیغات یا درآمد تخمینی را نیز اندازه گیری می کنند.پارامتر
dimensionsنحوه گروه بندی معیارها را توضیح می دهد.پارامتر
filtersنحوه فیلتر شدن داده های گزارش را توضیح می دهد. بنابراین، به‌عنوان مثال، به‌جای بازگرداندن همه داده‌های یک کانال، یک گزارش می‌تواند تنها حاوی معیارهای یک کشور، ویدیو یا گروهی از ویدیوها باشد.توجه: API به شما امکان می دهد چندین مقدار را برای فیلترهای ویدیو ، لیست پخش و کانال تعیین کنید. اگر این کار را انجام دهید، می‌توانید آن فیلتر را نیز در فهرست ابعاد قرار دهید تا معیارهای بازگشتی نیز بر اساس ویدیو، فهرست پخش یا کانال گروه‌بندی شوند.
گزینه های گزارش نمونه
به عنوان مثال، فرض کنید یک مالک کانال می‌خواهد گزارش نوع دستگاه ویدیویی را بازیابی کند تا مشخص کند چند بازدید از ویدیوهای کانال در دستگاه‌های تلفن همراه، کنسول‌های بازی، تلویزیون‌ها و غیره رخ داده است.
مالک کانال پارامتر
startDateرا روی2015-06-01و پارامترendDateرا روی2015-07-31تنظیم می کند. بر اساس این مقادیر، گزارش حاوی داده هایی برای یک دوره دو ماهه خواهد بود.گزارش نوع دستگاه از بازدیدها و معیارهای برآورد شده دقیقه‌های مشاهده شده پشتیبانی می‌کند، بنابراین مالک کانال پارامتر
metricsرا رویviews,estimatedMinutesWatchedتنظیم می‌کند.برای پارامتر
dimensions، مالک کانال تعدادی گزینه دارد. دو مورد از آنها در لیست زیر نشان داده شده است، و سومی در توضیح مقدار پارامترfiltersبعدا در این بخش مورد بحث قرار گرفته است.تنظیم مقدار پارامتر روی
deviceTypeبه این معنی است که تعداد بازدیدها و تعداد زمان تماشا بر اساس نوع دستگاه برای کل دوره ای که گزارش پوشش می دهد گروه بندی می شود. بنابراین، با این مقدار، داده های گزارش به سوالاتی مانند:- ویدیوهای کانال از 1 ژوئن 2015 تا 31 ژوئیه 2015 چند بار در دستگاه های تلفن همراه مشاهده شده است؟
- ویدیوهای این کانال بین 1 ژوئن 2015 تا 31 ژوئیه 2015 چند بار در کنسول های بازی مشاهده شده است؟
این گزارش در واقع شامل تعداد کل بازدید و زمان تماشا برای هر نوع دستگاه خواهد بود.
تنظیم مقدار پارامتر روی
day,deviceTypeبه این معنی است که تعداد بازدیدها و تعداد زمان تماشا بر اساس نوع دستگاه برای هر روز در طول دوره گزارش محاسبه می شود. بنابراین، با این مقدار، داده های گزارش به سوالاتی مانند:- ویدیوهای کانال در 1 ژوئن 2015 چند بار در دستگاه های تلفن همراه مشاهده شده است؟
- ویدیوهای این کانال در تاریخ 14 جولای 2015 چند بار در تلویزیون ها مشاهده شده است؟
در نهایت، پارامتر
filtersبه مالک کانال اجازه می‌دهد تا گزارش را محدود کند تا فقط داده‌های منطبق با مقادیر فیلتر خاص را شامل شود. این گزارش از گزینه‌های فیلتر بسیار زیادی برای توضیح همه آنها پشتیبانی می‌کند، بنابراین این نمونه‌ها تنها بخشی از گزارش‌هایی را نشان می‌دهند که می‌توانید ایجاد کنید.مالک کانال می‌تواند درخواست بازگشت مقادیر را فقط برای سیستم عامل Android فیلتر کند. (در طول دوره گزارش چند بازدید در دستگاه های تلفن همراه Android رخ داده است؟)
مالک کانال می‌تواند درخواست بازگشت مقادیر را فقط برای یک کشور خاص فیلتر کند. (در هر روز از دوره گزارش چند بار ویدیوها در کانادا مشاهده شده است؟)
مالک کانال می‌تواند درخواست بازگشت مقادیر را فقط برای ویدیوهای خاص فیلتر کند. با این حال، فیلتر ویدیو از یک لیست مقادیر جدا شده با کاما پشتیبانی می کند، بنابراین گزارش در واقع می تواند حاوی داده هایی برای بسیاری از ویدیوها باشد.
علاوه بر این، اگر فیلتر ویدئو مقادیر متعددی را مشخص کند، ویدئو را می توان به عنوان یک بعد نیز مشخص کرد. این بدان معناست که پارامتر
dimensionsاز مقادیرdeviceType,videoوday,deviceType,videoنیز پشتیبانی می کند.- اگر مالک کانال ویدیو را در فهرست ابعاد قرار دهد، معیارها مقادیر فردی را برای هر ویدیو مشخص می‌کنند. (ویدئو XYZ در 1 ژوئن 2015 چند بار روی یک کنسول بازی مشاهده شد؟)
- اگر مالک کانال ویدیو را در فهرست ابعاد قرار ندهد، معیارها مجموع مقادیری را که همه ویدیوهای مشخص شده را پوشش می‌دهند مشخص می‌کند. (ویدئوهای ABC، DEF، و XYZ در ۱ ژوئن ۲۰۱۵ چند بار روی یک کنسول بازی مشاهده شده‌اند؟)
بازیابی گزارش ها
برای بازیابی یک گزارش، یک درخواست GET مجاز را به متد reports.query API ارسال کنید، با مشخص کردن پارامترهایی که گزارشی را که می‌خواهید بازیابی کنید، تعریف می‌کند.
برای فهرستی از گزارش‌هایی که API پشتیبانی می‌کند، به گزارش‌های کانال و مستندات گزارش مالک محتوا مراجعه کنید. هر تعریف گزارش مقادیری را که گزارش برای پارامترهای metrics ، dimensions و filters مجاز می‌سازد، مشخص می‌کند.
بهترین شیوه ها
برنامه‌هایی که از YouTube Analytics API استفاده می‌کنند باید همیشه از این روش‌ها پیروی کنند:
- از ردیف سرصفحه پاسخ برای تعیین ترتیب ستون های گزارش استفاده کنید. به عنوان مثال، تصور نکنید که بازدیدها اولین معیاری هستند که در یک پاسخ بازگردانده می‌شوند، فقط به این دلیل که اولین معیار ذکر شده در توضیحات گزارش است. در عوض، از ردیف سرصفحه پاسخ برای تعیین اینکه کدام ستون حاوی آن داده است استفاده کنید.
- از YouTube Data API برای بازیابی فراداده های اضافی برای منابع شناسایی شده در پاسخ های YouTube Analytics API استفاده کنید. همانطور که در خط‌مشی‌های توسعه‌دهنده سرویس‌های YouTube API (بخش‌های III.E.4.b تا III.E.4.d) ذکر شده است، مشتریان API باید پس از 30 روز ابرداده‌های منبع ذخیره‌شده را از آن API حذف یا تازه‌سازی کنند.
متریک ها و موارد حذف شده را جمع آوری کنید
پاسخ‌های YouTube Analytics API شامل تفکیک‌های متریک برای موارد حذف شده نیست. برای مثال، اگر مالک کانال یک ویدیو را حذف کند، آن ویدیو دیگر در یک پاسخ API که معیارها را بر اساس ویدیو به ویدیو برمی‌گرداند، فهرست نمی‌شود. با این حال، گزارش‌هایی مبنی بر اینکه معیارهای مجموع برای مجموعهای از منابع هنوز هم معیارهای مرتبط با موارد حذف شده را شامل می‌شوند.
به عنوان مثال، فرض کنید مالک کانال دو گزارش را بازیابی می کند. اولین گزارش کل بازدیدهای روزانه همه ویدیوهای کانال را در یک بازه زمانی خاص فهرست می کند. گزارش دوم مجموع بازدیدهای روزانه را بر اساس ویدیو به ویدیو در بازه زمانی مشابه فهرست می کند.
در این حالت، اعداد در گزارش اول شامل بازدیدهای ویدیویی می‌شوند که بعداً حذف شده‌اند، زیرا گزارش اول حاوی مجموعهای روزانه است. با این حال، گزارش دوم شامل بازدیدهای مرتبط با موارد حذف شده نمی شود زیرا گزارش دوم بازدیدها را بر اساس ویدیو به ویدیو فهرست می کند. در نتیجه، اگر کانال در طول دوره زمانی که گزارش پوشش می‌دهد، ویدیوها را حذف کرده باشد، ممکن است تعداد کل بازدیدهای روزانه گزارش‌شده در گزارش اول بیشتر از مجموع تعداد بازدیدهای روزانه ویژه ویدیو در گزارش دوم باشد.
ناشناس سازی داده ها
برخی از داده‌های YouTube Analytics زمانی محدود می‌شوند که معیارها به آستانه خاصی نرسند. این می تواند در انواع گزارش ها اتفاق بیفتد. در عمل، به این معنی است که یک گزارش ممکن است شامل تمام (یا هیچ کدام) از داده های شما نباشد اگر:
یک ویدیو یا کانال در یک بازه زمانی مشخص ترافیک محدودی دارد،
یا
شما یک فیلتر یا بعد انتخاب کرده اید، مانند منبع ترافیک یا کشور، که مقادیر برای آن آستانه مشخصی را برآورده نمی کنند.
در مواردی که داده ها محدود است، ممکن است بین مجموع های گزارش شده در گزارش های مختلف بسته به نحوه جمع آوری داده ها در آن گزارش ها تفاوت وجود داشته باشد.
به عنوان مثال، فرض کنید مالک کانال دو گزارش را بازیابی می کند. گزارش اول کل بازدیدهای یک ویدیوی خاص را فهرست می‌کند و گزارش دوم کل بازدیدهای آن ویدیو را بر اساس کشور به کشور فهرست می‌کند. در طول مدت زمان مشخص شده، فرض کنید که ویدیو 1000 بار مشاهده شده است، که در آن 500 بازدید در ایالات متحده، 498 در کانادا و دو بار در فرانسه مشاهده شده است.
در این مثال، اولین گزارش نشان می دهد که ویدیو 1000 بار دیده شده است. گزارش دوم فقط نشان می‌دهد که این ویدیو 500 بار در ایالات متحده و 498 بار در کانادا مشاهده شده است. به این ترتیب، بین تعداد کل بازدیدها در دو گزارش تفاوت وجود دارد. توجه داشته باشید که گزارش دوم حاوی هیچ نشانه ای نیست که دو دیدگاه دیگر نیز وجود داشته است (یا اینکه هر دیدگاهی در فرانسه رخ داده است).
آستانه‌های واقعی که در آن داده‌ها محدود است، منتشر نمی‌شوند و بنا به صلاحدید YouTube قابل تغییر هستند.
انواع داده های محدود
ممکن است داده‌های زیر در گزارش‌های YouTube Analytics محدود باشد:
- داده های دموگرافیک، مانند سن و جنسیت.
- داده‌های جغرافیایی، از جمله معیارها یا ابعاد مربوط به کشورها یا مناطقی که بینندگان در آنجا قرار داشتند، مانند کشورها یا مناطق آنها. با این حال، توجه داشته باشید که گزارش‌ها آستانه‌های جغرافیایی را برای معیارهای درآمد اعمال نمی‌کنند.
- معیارهای مربوط به منابع ترافیکی خاص، مانند عبارات جستجو یا نشانی‌های اینترنتی خارجی که منجر به بازدید ویدیوهای شما می‌شود. به عنوان مثال، عبارات جستجو و URL هایی که تعداد بسیار کمی بازدید دارند، در گزارش ها ظاهر نمی شوند، اگرچه همچنان عبارات و URL هایی را مشاهده خواهید کرد که بینندگان زیادی را به سمت محتوای شما سوق می دهند.
برای اطلاعات بیشتر درباره داده‌های محدود در گزارش‌های YouTube Analytics، به مرکز راهنمایی YouTube مراجعه کنید.
استفاده از سهمیه
هر درخواست API که می کنید به عنوان یک واحد از سهمیه استفاده از API شما به حساب می آید. محدودیت‌های سهمیه در پانل Quotas در Google API Console قابل مشاهده است.