یوتیوب بهطور خودکار مجموعهای از گزارشهای درآمد تبلیغاتی مدیریتشده توسط سیستم را برای مالکان محتوا که به گزارشهای مربوطه در Creator Studio دسترسی دارند، ایجاد میکند. این گزارشها به گونهای طراحی شدهاند که دسترسی برنامهریزیشده به دادههایی را فراهم کنند که در گزارشهای قابل دانلود دستی که در منوی Reports در YouTube Creator Studio قابل دسترسی هستند نیز موجود است.
توجه: این API دسترسی به مجموعهای متفاوت از گزارشها را نسبت به Creator Studio فراهم میکند، هرچند گزارشها حاوی دادههای مشابهی هستند. گزارشهای API ممکن است فیلدهای متفاوتی داشته باشند و همچنین از نامهای فیلد متفاوتی نسبت به گزارشهای Creator Studio استفاده کنند.
از آنجایی که یوتیوب بهطور خودکار گزارشهای مدیریتشده توسط سیستم را تولید میکند، فرآیند بازیابی این گزارشها با گزارشهای دادههای انبوه YouTube Analytics که از طریق API در دسترس هستند، متفاوت است.
بازیابی گزارشها
مراحل زیر نحوه بازیابی گزارشهای مدیریتشده توسط سیستم را از طریق API توضیح میدهد.
مرحله 1: بازیابی اعتبارنامههای مجوز
تمام درخواستهای API گزارش یوتیوب باید تأیید شوند. راهنمای تأیید، نحوه استفاده از پروتکل OAuth 2.0 برای بازیابی توکنهای تأیید را توضیح میدهد.
درخواستهای API گزارش یوتیوب از حوزههای مجوز زیر استفاده میکنند:
| دامنه | توضیحات |
|---|---|
| https://www.googleapis.com/auth/yt-analytics.readonly | گزارشهای YouTube Analytics را برای محتوای YouTube خود مشاهده کنید. این دامنه دسترسی به معیارهای فعالیت کاربر، مانند تعداد بازدیدها و تعداد رتبهبندیها را فراهم میکند. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | گزارشهای مالی YouTube Analytics را برای محتوای YouTube خود مشاهده کنید. این بخش دسترسی به معیارهای فعالیت کاربر و معیارهای تخمینی درآمد و عملکرد تبلیغات را فراهم میکند. |
مرحله ۲: شناسه کار را برای گزارش مورد نظر بازیابی کنید
برای بازیابی لیستی از کارهای مدیریتشده توسط سیستم، متد jobs.list را فراخوانی کنید. پارامتر includeSystemManaged را روی true تنظیم کنید.
ویژگی reportTypeId در هر منبع Job برگردانده شده، نوع گزارش مدیریتشده توسط سیستم مرتبط با آن Job را مشخص میکند. برنامه شما در مرحله بعد به مقدار ویژگی id از همان منبع نیاز دارد.
سند Reports گزارشهای موجود، شناسههای نوع گزارش آنها و فیلدهای موجود در آنها را فهرست میکند. همچنین میتوانید از متد reportTypes.list برای بازیابی لیستی از انواع گزارشهای پشتیبانی شده استفاده کنید.
مرحله ۳: دریافت آدرس دانلود گزارش
برای بازیابی لیستی از گزارشهای ایجاد شده برای این کار، متد jobs.reports.list را فراخوانی کنید. در درخواست، پارامتر jobId را برابر با شناسهی کار گزارشی که میخواهید بازیابی کنید، قرار دهید.
شما میتوانید لیست گزارشها را با استفاده از هر یا همه پارامترهای زیر فیلتر کنید:
از پارامتر
createdAfterبرای مشخص کردن این که API فقط باید گزارشهایی را که پس از زمان مشخصی ایجاد شدهاند، برگرداند، استفاده کنید. این پارامتر میتواند برای اطمینان از این باشد که API فقط گزارشهایی را که قبلاً پردازش نکردهاید، برگرداند.از پارامتر
startTimeBeforeبرای نشان دادن این که پاسخ API فقط باید شامل گزارشهایی باشد که اولین دادههای موجود در گزارش قبل از تاریخ مشخص شده باشند، استفاده کنید. در حالی که پارامترcreatedAfterمربوط به زمان ایجاد گزارش است، این تاریخ مربوط به دادههای موجود در گزارش است.از پارامتر
startTimeAtOrAfterبرای نشان دادن این موضوع استفاده کنید که پاسخ API فقط باید شامل گزارشهایی باشد که اولین دادههای موجود در گزارش مربوط به تاریخ مشخص شده یا بعد از آن باشند. مانند پارامترstartTimeBefore، مقدار این پارامتر مربوط به دادههای موجود در گزارش است و نه زمان ایجاد گزارش.
پاسخ API شامل فهرستی از منابع Report برای آن کار است. هر منبع به گزارشی اشاره دارد که حاوی دادههایی برای یک دوره منحصر به فرد است.
- ویژگیهای
startTimeوendTimeمنبع، دوره زمانی را که دادههای گزارش پوشش میدهند، مشخص میکنند. - ویژگی
downloadUrlمنبع، URL ای را که گزارش میتواند از آن دریافت شود، مشخص میکند. - ویژگی
createTimeمنبع، تاریخ و زمان تولید گزارش را مشخص میکند. برنامه شما باید این مقدار را ذخیره کند و از آن برای تعیین اینکه آیا گزارشهای دانلود شده قبلی تغییر کردهاند یا خیر، استفاده کند.
مرحله ۴: دانلود گزارش
برای بازیابی گزارش، یک درخواست HTTP GET به downloadUrl که در مرحله ۴ به دست آمده است، ارسال کنید.
گزارشهای پردازش
بهترین شیوهها
برنامههایی که از API گزارشدهی یوتیوب استفاده میکنند، باید همیشه از این شیوهها پیروی کنند:
از ردیف سربرگ گزارش برای تعیین ترتیب ستونهای گزارش استفاده کنید. برای مثال، فرض نکنید که نماها (views) اولین معیاری هستند که در گزارش برگردانده میشوند، صرفاً به این دلیل که اولین معیار ذکر شده در توضیحات گزارش هستند. در عوض، از ردیف سربرگ گزارش برای تعیین اینکه کدام ستون حاوی آن دادهها است، استفاده کنید.
برای جلوگیری از پردازش مکرر یک گزارش، گزارشهایی را که دانلود کردهاید، ثبت کنید. لیست زیر چند روش برای انجام این کار ارائه میدهد.
هنگام فراخوانی متد
reports.list، از پارامتر createdAfter برای بازیابی گزارشهای ایجاد شده پس از یک تاریخ خاص استفاده کنید. (پارامترcreatedAfterرا در اولین باری که گزارشها را بازیابی میکنید، حذف کنید.)هر بار که گزارشها را بازیابی و با موفقیت پردازش میکنید، مهر زمانی مربوط به تاریخ و زمان ایجاد جدیدترین آن گزارشها را ذخیره کنید. سپس، مقدار پارامتر
createdAfterرا در هر فراخوانی متوالی به روشreports.listبهروزرسانی کنید تا مطمئن شوید که فقط گزارشهای جدید، از جمله گزارشهای جدید با دادههای پر شده، را هر بار که API را فراخوانی میکنید، بازیابی میکنید.به عنوان یک اقدام احتیاطی، قبل از بازیابی گزارش، بررسی کنید که شناسه گزارش از قبل در پایگاه داده شما ثبت نشده باشد.
شناسه هر گزارشی را که دانلود و پردازش کردهاید، ذخیره کنید. همچنین میتوانید اطلاعات اضافی مانند تاریخ و زمان تولید هر گزارش یا
startTimeوendTimeگزارش را ذخیره کنید که در مجموع دورهای را که گزارش حاوی دادهها است، مشخص میکنند. برای گزارشهایی که دادههای انبوه را برای YouTube Analytics بازیابی میکنند، هر کار احتمالاً گزارشهای زیادی خواهد داشت زیرا هر گزارش حاوی دادههایی برای یک دوره ۲۴ ساعته است. کارهای مدیریتشده توسط سیستم که دورههای زمانی طولانیتری را پوشش میدهند، گزارشهای کمتری خواهند داشت.از شناسه گزارش برای شناسایی گزارشهایی که هنوز نیاز به دانلود و وارد کردن آنها دارید استفاده کنید. با این حال، اگر دو گزارش جدید مقادیر ویژگیهای
startTimeوendTimeیکسانی دارند، فقط گزارشی را وارد کنید که مقدارcreateTimeجدیدتری دارد.
ویژگیهای گزارش
گزارشهای API فایلهای .csv (مقادیر جدا شده با کاما) با نسخههای مختلف هستند که دارای ویژگیهای زیر میباشند:
هر گزارش شامل دادههایی برای یک دوره منحصر به فرد است که از ساعت ۱۲:۰۰ بامداد به وقت اقیانوس آرام در تاریخ شروع گزارش تا ساعت ۱۱:۵۹ شب به وقت اقیانوس آرام در تاریخ پایان گزارش ادامه دارد.
دادههای گزارش مرتب نشدهاند.