YouTube Reporting API - Get Bulk Data Reports
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
ينشئ YouTube تلقائيًا مجموعة من تقارير أرباح الإعلانات التي يديرها النظام لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير المقابلة في استوديو YouTube. تم تصميم هذه التقارير لتوفير إمكانية الوصول آليًا إلى البيانات المتوفّرة أيضًا في التقارير التي يمكن تنزيلها يدويًا والتي يمكن الوصول إليها في قائمة التقارير في "استوديو YouTube".
ملاحظة: تتيح واجهة برمجة التطبيقات الوصول إلى مجموعة مختلفة من التقارير مقارنةً بـ "استوديو YouTube"، على الرغم من أنّ التقارير تتضمّن بيانات مشابهة. قد تتضمّن تقارير واجهة برمجة التطبيقات حقولاً مختلفة وتستخدم أيضًا أسماء حقول مختلفة عن تقارير "استوديو YouTube".
بما أنّ YouTube ينشئ تلقائيًا التقارير التي يديرها النظام، تختلف عملية استرداد هذه التقارير عن عملية استرداد تقارير البيانات المجمّعة في "إحصاءات YouTube" المتاحة من خلال واجهة برمجة التطبيقات.
استرداد التقارير
توضّح الخطوات التالية كيفية استرداد التقارير التي يديرها النظام من خلال واجهة برمجة التطبيقات.
الخطوة 1: استرداد بيانات اعتماد التفويض
يجب أن يتم السماح بإرسال جميع طلبات البيانات من YouTube Reporting API. يوضّح دليل التفويض كيفية استخدام بروتوكول OAuth 2.0 لاسترداد رموز التفويض المميزة.
تستخدم طلبات YouTube Reporting API نطاقات التفويض التالية:
| المستويات |
| https://www.googleapis.com/auth/yt-analytics.readonly |
عرض تقارير "إحصاءات YouTube" للمحتوى في YouTube يوفّر هذا النطاق إمكانية الوصول إلى مقاييس نشاط المستخدمين، مثل عدد المشاهدات وعدد التقييمات. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
عرض تقارير "إحصاءات YouTube" المالية للمحتوى في YouTube يتيح هذا النطاق الوصول إلى مقاييس نشاط المستخدمين وإلى المقاييس المقدَّرة للأرباح وأداء الإعلانات. |
الخطوة 2: استرداد معرّف مهمة التقرير المطلوب
استدعِ طريقة jobs.list لاسترداد قائمة بالمهام التي يديرها النظام. اضبط المَعلمة includeSystemManaged على true.
تحدّد السمة reportTypeId في كل مورد Job تم عرضه نوع التقرير الذي يديره النظام والمرتبط بهذه المهمة. يحتاج تطبيقك إلى قيمة السمة id من المرجع نفسه في الخطوة التالية.
يسرد مستند التقارير التقارير المتاحة ومعرّفات أنواع التقارير والحقول التي تتضمّنها. يمكنك أيضًا استخدام طريقة reportTypes.list لاسترداد قائمة بأنواع التقارير المتوافقة.
الخطوة 3: استرداد عنوان URL لتنزيل التقرير
استدعِ طريقة jobs.reports.list لاسترداد قائمة بالتقارير التي تم إنشاؤها للمهمة. في الطلب، اضبط المَعلمة jobId على معرّف مهمة التقرير الذي تريد استرداده.
يمكنك فلترة قائمة التقارير باستخدام أيّ من المَعلمات التالية أو جميعها:
-
استخدِم المَعلمة createdAfter للإشارة إلى أنّ واجهة برمجة التطبيقات يجب أن تعرض فقط التقارير التي تم إنشاؤها بعد وقت محدّد. يمكن استخدام هذه المَعلمة لضمان أنّ واجهة برمجة التطبيقات لا تعرض إلا التقارير التي لم تتم معالجتها بعد.
-
استخدِم المَعلمة startTimeBefore للإشارة إلى أنّ استجابة واجهة برمجة التطبيقات يجب أن تتضمّن التقارير فقط إذا كانت البيانات الأقدم في التقرير قبل التاريخ المحدّد. في حين أنّ المَعلمة createdAfter تتعلّق بوقت إنشاء التقرير، يشير هذا التاريخ إلى البيانات الواردة في التقرير.
-
استخدِم المَعلمة startTimeAtOrAfter للإشارة إلى أنّ استجابة واجهة برمجة التطبيقات يجب أن تحتوي على تقارير فقط إذا كانت البيانات الأقدم في التقرير في التاريخ المحدّد أو بعده. مثل المَعلمة startTimeBefore، تتوافق قيمة هذه المَعلمة مع البيانات الواردة في التقرير وليس مع وقت إنشاء التقرير.
يتضمّن الردّ من واجهة برمجة التطبيقات قائمة بموارد Report لهذا العمل. يشير كل مرجع إلى تقرير يحتوي على بيانات لفترة زمنية فريدة.
- تحدّد السمتان
startTime وendTime الخاصتان بالمرجع الفترة الزمنية التي تغطيها بيانات التقرير.
- تحدّد السمة
downloadUrl الخاصة بالمرجع عنوان URL الذي يمكن استرداد التقرير منه.
- تحدّد السمة
createTime الخاصة بالمرجع تاريخ ووقت إنشاء التقرير. يجب أن يخزّن تطبيقك هذه القيمة ويستخدمها لتحديد ما إذا كانت التقارير التي تم تنزيلها سابقًا قد تغيّرت.
الخطوة 4: تنزيل التقرير
أرسِل طلب استرداد بيانات باستخدام GET HTTP إلى downloadUrl الذي تم الحصول عليه في الخطوة 4 لاسترداد التقرير.
تقارير المعالجة
أفضل الممارسات
يجب أن تلتزم التطبيقات التي تستخدم YouTube Reporting API دائمًا بالممارسات التالية:
-
استخدِم صف العنوان في التقرير لتحديد ترتيب أعمدة التقرير. على سبيل المثال، لا تفترض أنّ المشاهدات ستكون المقياس الأول الذي يتم عرضه في التقرير لمجرّد أنّه المقياس الأول المُدرَج في وصف التقرير. بدلاً من ذلك، استخدِم صف العناوين في التقرير لتحديد العمود الذي يحتوي على هذه البيانات.
-
احتفظ بسجلّ للتقارير التي نزّلتها لتجنُّب معالجة التقرير نفسه بشكل متكرّر. تقترح القائمة التالية طريقتَين لإجراء ذلك.
-
عند استدعاء طريقة reports.list، استخدِم المَعلمة createdAfter لاسترداد التقارير التي تم إنشاؤها بعد تاريخ معيّن فقط. (احذف المَعلمة createdAfter في المرة الأولى التي تستردّ فيها التقارير).
في كل مرة تسترد فيها التقارير وتعالجها بنجاح، خزِّن الطابع الزمني الذي يتوافق مع التاريخ والوقت اللذين تم فيهما إنشاء أحدث هذه التقارير. بعد ذلك، عدِّل قيمة المَعلمة createdAfter في كل عملية استدعاء متتالية للطريقة reports.list للتأكّد من أنّك تسترد التقارير الجديدة فقط، بما في ذلك التقارير الجديدة التي تتضمّن بيانات تمت إعادة تعبئتها، في كل مرة تستدعي فيها واجهة برمجة التطبيقات.
كإجراء وقائي، قبل استرداد تقرير، تحقَّق أيضًا للتأكّد من أنّ معرّف التقرير غير مُدرَج في قاعدة البيانات.
-
احفظ المعرّف لكل تقرير نزّلته وعالجته. يمكنك أيضًا تخزين معلومات إضافية، مثل التاريخ والوقت اللذين تم فيهما إنشاء كل تقرير أو startTime وendTime للتقرير، واللذين يحدّدان معًا الفترة التي يتضمّن التقرير بياناتها. بالنسبة إلى التقارير التي تستردّ بيانات مجمّعة من "إحصاءات YouTube"، من المحتمل أن تتضمّن كل مهمة العديد من التقارير لأنّ كل تقرير يحتوي على بيانات لفترة 24 ساعة. ستتضمّن المهام التي يديرها النظام والتي تغطي فترات زمنية أطول عددًا أقل من التقارير.
استخدِم رقم تعريف التقرير لتحديد التقارير التي لا يزال عليك تنزيلها واستيرادها. ومع ذلك، إذا كان تقريران جديدان يتضمّنان قيمتَي السمتَين startTime وendTime نفسيهما، ما عليك سوى استيراد التقرير الذي يتضمّن قيمة createTime الأحدث.
خصائص التقرير
تقارير واجهة برمجة التطبيقات هي ملفات .csv (قيم مفصولة بفواصل) تتضمّن الخصائص التالية:
-
يحتوي كل تقرير على بيانات لفترة فريدة تمتد من الساعة 12:00 صباحًا بتوقيت المحيط الهادئ في تاريخ بدء التقرير إلى الساعة 11:59 مساءً بتوقيت المحيط الهادئ في تاريخ انتهاء التقرير.
-
لم يتم فرز بيانات التقرير.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة 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."]]
