YouTube Reporting API - Get Bulk Data Reports
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
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 بعد از ظهر به وقت اقیانوس آرام در تاریخ پایان گزارش به طول می‌انجامد.
داده های گزارش مرتب نشده اند.
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین به‌روزرسانی 2025-08-21 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین به‌روزرسانی 2025-08-21 بهوقت ساعت هماهنگ جهانی."],[[["\u003cp\u003eYouTube's Reporting API provides access to system-managed ad revenue reports, which differ from Creator Studio reports in terms of fields and naming, yet contain similar data.\u003c/p\u003e\n"],["\u003cp\u003eRetrieving these reports involves four steps: getting authorization credentials, retrieving the job ID, getting the report's download URL, and downloading the report.\u003c/p\u003e\n"],["\u003cp\u003eThe API requires specific authorization scopes, either \u003ccode\u003ehttps://www.googleapis.com/auth/yt-analytics.readonly\u003c/code\u003e for general user activity metrics or \u003ccode\u003ehttps://www.googleapis.com/auth/yt-analytics-monetary.readonly\u003c/code\u003e for monetary and ad performance metrics.\u003c/p\u003e\n"],["\u003cp\u003eBest practices for using the API include using the header row to identify column ordering and keeping a record of downloaded reports to avoid reprocessing the same data, while also checking for updated reports.\u003c/p\u003e\n"],["\u003cp\u003eEach report is a \u003ccode\u003e.csv\u003c/code\u003e file containing data for a specific period, from 12:00 a.m. to 11:59 p.m. Pacific Time, and the data within the reports is not sorted.\u003c/p\u003e\n"]]],["YouTube provides system-managed ad revenue reports accessible via the Reporting API. To retrieve these reports, first, obtain authorization credentials using OAuth 2.0. Next, retrieve the job ID for the desired report type by calling `jobs.list` with `includeSystemManaged` set to `true`. Then, call `jobs.reports.list`, providing the job ID, to get the report's download URL, which may be filtered by creation or start times. Finally, use an HTTP GET request to download the report. Remember to store downloaded report details to avoid reprocessing.\n"],null,["# YouTube Reporting API - Get Bulk Data Reports\n\nYouTube automatically generates a set of system-managed ad revenue reports for content owners that have access to the corresponding reports in [Creator Studio](http://studio.youtube.com/). These reports are designed to provide programmatic access to data that is also available in manually downloadable reports accessible in the [Reports menu](https://support.google.com/youtube/answer/7648605) of the YouTube Creator Studio.\n\n**Note:** The API provides access to a different set of reports than Creator Studio, though the reports contain similar data. API reports might have different fields and also use different field names than Creator Studio reports.\n\nSince YouTube automatically generates system-managed reports, the process for retrieving these reports is different than for the YouTube Analytics bulk data reports available via the API.\n\nRetrieving reports\n------------------\n\nThe following steps explain how to retrieve system-managed reports via the API.\n\n### Step 1: Retrieve authorization credentials\n\nAll YouTube Reporting API requests must be authorized. The [Authorization guide](/youtube/reporting/guides/authorization) explains how to use the OAuth 2.0 protocol to retrieve authorization tokens.\n\nYouTube Reporting API requests use the following authorization scopes:\n\n| Scopes ||\n|----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| https://www.googleapis.com/auth/yt-analytics.readonly | View YouTube Analytics reports for your YouTube content. This scope provides access to user activity metrics, like view counts and rating counts. |\n| https://www.googleapis.com/auth/yt-analytics-monetary.readonly | View YouTube Analytics monetary reports for your YouTube content. This scope provides access to user activity metrics and to estimated revenue and ad performance metrics. |\n\n### Step 2: Retrieve the job ID for the desired report\n\nCall the `jobs.list` method to retrieve a list of system-managed jobs. Set the [includeSystemManaged](/youtube/reporting/v1/reference/rest/v1/jobs/list#includeSystemManaged) parameter to `true`.\n\nThe [reportTypeId](/youtube/reporting/v1/reference/rest/v1/jobs#reportTypeId) property in each returned `Job` resource identifies the type of system-managed report associated with that job. Your application needs the [id](/youtube/reporting/v1/reference/rest/v1/jobs#id) property value from the same resource in the following step.\n\nThe [Reports](/youtube/reporting/v1/reports/system_managed/reports) document lists available reports, their report type IDs, and the fields they contain. You can also use the [reportTypes.list](/youtube/reporting/v1/reference/rest/v1/reportTypes/list) method to retrieve a list of supported report types.\n\n### Step 3: Retrieve the report's download URL\n\nCall the `jobs.reports.list` method to retrieve a list of reports created for the job. In the request, set the [jobId](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#jobId) parameter to the job ID of the report that you want to retrieve.\n\nYou can filter the list of reports using any or all of the following parameters:\n\n- Use the [createdAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#createdAfter) parameter to indicate that the API should only return reports created after a specified time. This parameter can be used to ensure that the API only returns reports that you have not already processed.\n\n- Use the [startTimeBefore](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#startTimeBefore) parameter to indicate that the API response should only contain reports if the earliest data in the report is before the specified date. Whereas the `createdAfter` parameter pertains to the time the report was created, this date pertains to the data in the report.\n\n- Use the [startTimeAtOrAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#startTimeAtOrAfter) parameter to indicate that the API response should only contain reports if the earliest data in the report is on or after the specified date. Like the `startTimeBefore` parameter, this parameter value corresponds to the data in the report and not the time the report was created.\n\nThe API response contains a list of `Report` resources for that job. Each resource refers to a report that contains data for a unique period.\n\n- The resource's [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime) properties identify the time period that the report's data covers.\n- The resource's [downloadUrl](/youtube/reporting/v1/reference/rest/v1/jobs.reports#downloadUrl) property identifies the URL from which the report can be fetched.\n- The resource's [createTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) property specifies the date and time when the report was generated. Your application should store this value and use it to determine whether previously downloaded reports have changed.\n\n### Step 4: Download the report\n\nSend an HTTP GET request to the `downloadUrl` obtained in step 4 to retrieve the report.\n\nProcessing reports\n------------------\n\n### Best practices\n\nApplications that use the YouTube Reporting API should *always* follow these practices:\n\n- Use a report's header row to determine the ordering of the report's columns. For example, do not assume that [views](/youtube/reporting/v1/reports/metrics#views) will be the first metric returned in a report just because it is the first metric listed in a report description. Instead, use the report's header row to determine which column contains that data.\n\n- Keep a record of the reports you have downloaded to avoid repeatedly processing the same report. The following list suggests a couple of ways to do that.\n\n - When calling the [reports.list](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method, use the [createdAfter](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list#createdAfter) parameter to only retrieve reports created after a certain date. (Omit the `createdAfter` parameter the first time you retrieve reports.)\n\n Each time you retrieve and successfully process reports, store the timestamp corresponding to the [date and time](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) when the newest of those reports was created. Then, update the `createdAfter` parameter value on each successive call to the [reports.list](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method to ensure that you are only retrieving new reports, including new reports with backfilled data, each time you call the API.\n\n As a safeguard, before retrieving a report, also check to ensure that the report's [ID](/youtube/reporting/v1/reference/rest/v1/jobs.reports#id) is not already listed in your database.\n - Store the [ID](/youtube/reporting/v1/reference/rest/v1/jobs.reports#id) for each report that you have downloaded and processed. You can also store additional information like the [date and time](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) when each report was generated or the report's [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime), which together identify the period for which the report contains data. For reports that retrieve bulk data for YouTube Analytics, each job will likely have many reports since each report contains data for a 24-hour period. System-managed jobs that cover longer time periods will have fewer reports.\n\n Use the report ID to identify reports that you still need to download and import. However, if two new reports have the same [startTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#startTime) and [endTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#endTime) property values, only import the report with the newer [createTime](/youtube/reporting/v1/reference/rest/v1/jobs.reports#createTime) value.\n\n### Report characteristics\n\nAPI reports are versioned `.csv` (comma-separated values) files that have the following characteristics:\n\n- Each report contains data for a unique period lasting from 12:00 a.m. Pacific time on the report's start date through 11:59 p.m. Pacific time on the report's end date.\n\n- Report data is not sorted."]]
