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