YouTube Reporting API
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح واجهة YouTube Reporting API للمطوّرين جدولة مهام إعداد التقارير ثم تنزيل التقارير المجمّعة التي تم إنشاؤها. تتيح واجهة برمجة التطبيقات مجموعة محدّدة مسبقًا من التقارير، يحتوي كلّ منها على مجموعة شاملة من بيانات "إحصاءات YouTube" لقناة أو مالك محتوى.
توضّح الخطوات التالية كيفية جدولة مهام إعداد التقارير واسترداد التقارير:
- استخدِم طريقة
reportTypes.list() لاسترداد قائمة بالتقارير التي يمكن لصاحب القناة أو مالك المحتوى استردادها. - استدعِ طريقة
jobs.create() لتحديد تقرير يجب إنشاؤه لقناة أو مالك محتوى. يمكنك بعد ذلك استخدام jobs.list() وjobs.delete() في واجهة برمجة التطبيقات لاسترداد أو تغيير قائمة التقارير التي يتم إنشاؤها. - استخدِم طريقة
jobs.reports.list() لاسترداد قائمة بالتقارير التي تم إنشاؤها لمهمة معيّنة. يحتوي كل مورد في الرد على السمة downloadUrl التي تحدّد عنوان URL الذي يمكن تنزيل التقرير منه. - أرسِل طلب
GET معتمدًا لاسترداد التقرير من عنوان URL الخاص بالتنزيل.
التفويض
يجب أن يتم السماح بإرسال جميع طلبات البيانات من 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 يتيح هذا النطاق الوصول إلى مقاييس نشاط المستخدمين وإلى المقاييس المقدَّرة للأرباح وأداء الإعلانات. |
أنواع الموارد
تقدّم الأقسام التالية أوصافًا عامة لموارد واجهة برمجة التطبيقات وطرقها. ترتبط جميع معرّفات الموارد المنتظمة (URI) الخاصة بالطُرق المعروضة في الجداول بالموقع الإلكتروني https://youtubereporting.googleapis.com.
| الطُرق |
create |
POST /v1/jobs
تُنشئ هذه السمة مهمة إعداد تقارير. من خلال إنشاء مهمة إعداد تقارير، أنت تطلب من YouTube إنشاء هذا التقرير بشكل يومي. يتوفّر التقرير في غضون 24 ساعة من وقت إنشاء مهمة الاستيراد. |
delete |
DELETE /v1/jobs/{jobId}
يحذف مهمة إعداد تقارير. |
get |
GET /v1/jobs/{jobId}
تستردّ هذه الطريقة معلومات حول مهمة تقارير معيّنة تم تحديد موعد لها لقناة أو مالك محتوى. |
list |
GET /v1/jobs
تعرض هذه الطريقة مهام إعداد التقارير التي تم تحديد موعد لها لقناة أو مالك محتوى. يحتوي كل مرجع في الرد على السمة id التي تحدّد المعرّف الذي يستخدمه YouTube للتعريف عن المهمة بشكل فريد. تحتاج إلى هذا المعرّف لاسترداد قائمة التقارير التي تم إنشاؤها للوظيفة أو لحذف الوظيفة. |
| الطُرق |
get |
GET /v1/jobs/{jobId}/reports/{reportId}
يستردّ البيانات الوصفية لتقرير معيّن. |
list |
GET /v1/jobs/{jobId}/reports
تعرض هذه السمة التقارير التي تم إنشاؤها لمهمة إعداد التقارير المحدّدة. |
| الطُرق |
list |
GET /v1/reportTypes
تعرض هذه الطريقة قائمة بأنواع التقارير التي يمكن للقناة أو مالك المحتوى استردادها. |
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe YouTube Reporting API allows developers to schedule and download bulk reports containing comprehensive YouTube Analytics data for channels or content owners.\u003c/p\u003e\n"],["\u003cp\u003eDevelopers can use the API to retrieve a list of available reports, create jobs to generate reports, and manage these jobs through listing and deletion.\u003c/p\u003e\n"],["\u003cp\u003eGenerated reports can be downloaded via a specified URL obtained from the API's response, after retrieving them by using the \u003ccode\u003ejobs.reports.list()\u003c/code\u003e method.\u003c/p\u003e\n"],["\u003cp\u003eThe API requires OAuth 2.0 authorization, and provides scopes for viewing user activity metrics (\u003ccode\u003ehttps://www.googleapis.com/auth/yt-analytics.readonly\u003c/code\u003e) and monetary reports (\u003ccode\u003ehttps://www.googleapis.com/auth/yt-analytics-monetary.readonly\u003c/code\u003e).\u003c/p\u003e\n"]]],["Developers use the YouTube Reporting API to schedule and download bulk reports containing YouTube Analytics data. Key actions include: listing available report types via `reportTypes.list()`, creating reporting jobs with `jobs.create()`, and managing jobs using `jobs.list()` and `jobs.delete()`. To get data, retrieve generated reports for a specific job with `jobs.reports.list()`, each with a downloadable URL. Finally, you can request the download using the given URL. All actions require authorization via OAuth 2.0.\n"],null,["# YouTube Reporting API\n\nThe YouTube Reporting API enables developers to schedule reporting jobs and then download generated bulk reports. The API supports a predefined set of reports, each of which contains a comprehensive set of YouTube Analytics data for a channel or content owner.\n\nThe steps below explain how to schedule reporting jobs and retrieve reports:\n\n1. Call the [reportTypes.list()](/youtube/reporting/v1/reference/rest/v1/reportTypes/list) method to retrieve a list of reports that a channel or content owner can retrieve.\n2. Call the [jobs.create()](/youtube/reporting/v1/reference/rest/v1/jobs/create) method to identify a report that should be generated for a channel or content owner. You can subsequently use the API's [jobs.list()](/youtube/reporting/v1/reference/rest/v1/jobs/list) and [jobs.delete()](/youtube/reporting/v1/reference/rest/v1/jobs/delete) to retrieve or change the list of reports being generated.\n3. Call the [jobs.reports.list()](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) method to retrieve a list of reports that have been generated for a particular job. Each resource in the response contains a [downloadUrl](/youtube/reporting/v1/reference/rest/v1/jobs.reports#downloadUrl) property that specifies the URL from which the report can be downloaded.\n4. Send an authorized `GET` request to retrieve the report from the download URL.\n\n\u003cbr /\u003e\n\nAuthorization\n-------------\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\nResource types\n--------------\n\nThe following sections provide general descriptions of the API's resources and methods. All method URIs shown in the tables are relative to `https://youtubereporting.googleapis.com`.\n\n### [jobs](/youtube/reporting/v1/reference/rest/v1/jobs)\n\n| Methods ||\n|---------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| [create](/youtube/reporting/v1/reference/rest/v1/jobs/create) | `POST /v1/jobs` Creates a reporting job. By creating a reporting job, you are instructing YouTube to generate that report on a daily basis. The report is available within 24 hours of the time that the job is created. |\n| [delete](/youtube/reporting/v1/reference/rest/v1/jobs/delete) | `DELETE /v1/jobs/{jobId}` Deletes a reporting job. |\n| [get](/youtube/reporting/v1/reference/rest/v1/jobs/get) | `GET /v1/jobs/{jobId}` Retrieves information about a specific reporting job that has been scheduled for a channel or content owner. |\n| [list](/youtube/reporting/v1/reference/rest/v1/jobs/list) | `GET /v1/jobs` Lists reporting jobs that have been scheduled for a channel or content owner. Each resource in the response contains an `id` property, which specifies the ID that YouTube uses to uniquely identify the job. You need that ID to retrieve the list of reports that have been generated for the job or to delete the job. |\n\n### [jobs.reports](/youtube/reporting/v1/reference/rest/v1/jobs.reports)\n\n| Methods ||\n|-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|\n| [get](/youtube/reporting/v1/reference/rest/v1/jobs.reports/get) | `GET /v1/jobs/{jobId}/reports/{reportId}` Retrieves the metadata for a specific report. |\n| [list](/youtube/reporting/v1/reference/rest/v1/jobs.reports/list) | `GET /v1/jobs/{jobId}/reports` Lists reports that have been generated for the specified reporting job. |\n\n### [reportTypes](/youtube/reporting/v1/reference/rest/v1/reportTypes)\n\n| Methods ||\n|------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|\n| [list](/youtube/reporting/v1/reference/rest/v1/reportTypes/list) | `GET /v1/reportTypes` Returns a list of report types that the channel or content owner can retrieve. |"]]
