Groups: list
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تُرجِع قائمة بالمجموعات التي تتطابق مع مَعلمات طلب واجهة برمجة التطبيقات. على سبيل المثال، يمكنك استرداد جميع المجموعات التي يملكها المستخدم الذي تمّت مصادقة هويته، أو يمكنك استرداد مجموعة واحدة أو أكثر من خلال أرقام تعريفها الفريدة.
الطلب
طلب HTTP
GET https://youtubeanalytics.googleapis.com/v2/groups
التفويض
يتطلب هذا الطلب تفويضًا بنطاق واحد على الأقل من النطاقات التالية (اطّلِع على مزيد من المعلومات عن المصادقة والتفويض).
| المستويات |
| https://www.googleapis.com/auth/yt-analytics.readonly |
عرض تقارير "إحصاءات YouTube" للمحتوى الخاص بك على YouTube يمنح هذا النطاق إمكانية الوصول إلى مقاييس نشاط المستخدمين، مثل أعداد المشاهدات وأعداد التقييمات. |
| https://www.googleapis.com/auth/yt-analytics-monetary.readonly |
يمكنك عرض تقارير "إحصاءات YouTube" المالية للمحتوى الخاص بك على YouTube. يمنح هذا النطاق إمكانية الوصول إلى مقاييس نشاط المستخدِم ومقاييس الأرباح المقدَّرة وأداء الإعلانات. |
| https://www.googleapis.com/auth/youtube |
إدارة حسابك على YouTube في YouTube Analytics API، يستخدم مالكو القنوات هذا النطاق لإدارة المجموعات والعناصر المجمّعة في "إحصاءات YouTube". |
| https://www.googleapis.com/auth/youtubepartner |
عرض وإدارة مواد عرض YouTube والمحتوى المرتبط بها على YouTube في YouTube Analytics API، يستخدم مالكو المحتوى هذا النطاق لإدارة مجموعات "إحصاءات YouTube" والعناصر المجمّعة. |
المعلمات
يسرد الجدول التالي المَعلمات التي يتيح طلب البحث استخدامها. جميع المَعلمات المُدرَجة هي مَعلمات طلب بحث.
| المعلمات |
| الفلاتر (حدد معلمة واحدة بالضبط من المعلمات التالية) |
id |
string
تحدّد المَعلمة id قائمة مفصولة بفواصل بمعرّفات مجموعات YouTube للموارد التي يتم استرجاعها. يجب أن تكون كل مجموعة مملوكة من المستخدم الذي تمت مصادقته. في مورد group، تحدّد السمة id معرّف مجموعة YouTube للمجموعة.
يُرجى العِلم أنّه في حال عدم تحديد قيمة للمَعلمة id، عليك ضبط المَعلمة mine على true. |
mine |
boolean
لا يمكن استخدام هذه المَعلمة إلّا في طلب مفوَّض بشكل صحيح. اضبط قيمة هذه المَعلمة على true لاسترداد جميع المجموعات التي يملكها المستخدم الذي تمت مصادقته. |
| المَعلمات الاختيارية |
onBehalfOfContentOwner |
string
لا يمكن استخدام هذه المَعلمة إلا في طلب مفوَّض بشكل صحيح. ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء المحتوى في YouTube الذين يملكون ويديرون العديد من قنوات YouTube المختلفة.
تشير المَعلمة onBehalfOfContentOwner إلى أنّ بيانات اعتماد التفويض في الطلب تحدّد مستخدمًا على YouTube يتصرّف نيابةً عن مالك المحتوى المحدّد في قيمة المَعلمة. تتيح هذه الميزة لمالكي المحتوى المصادقة مرة واحدة والوصول إلى جميع بيانات الفيديوهات والقنوات، بدون الحاجة إلى تقديم بيانات اعتماد المصادقة لكل قناة على حدة. يجب أن يكون الحساب الذي يصادق المستخدم عليه مرتبطًا بحساب مالك المحتوى المحدّد على YouTube. |
pageToken |
string
تُحدِّد المَعلمة pageToken صفحة معيّنة في مجموعة النتائج التي يجب عرضها. في استجابة واجهة برمجة التطبيقات، تحدِّد السمة nextPageToken الصفحة التالية التي يمكن استرجاعها. |
نص الطلب
لا تقدِّم محتوى طلب عند استدعاء هذه الطريقة.
الرد
أماكن إقامة
يحدد الجدول التالي الخصائص التي تظهر في هذا المورد:
| أماكن إقامة |
kind |
string
لتحديد نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#groupListResponse. |
etag |
etag
رقم تعريف Etag لهذا المورد. |
items[] |
list
قائمة بالمجموعات التي تتطابق مع مَعلمات طلب البيانات من واجهة برمجة التطبيقات. يمثّل كل عنصر في القائمة مورد group. |
nextPageToken |
string
الرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken لاسترداد الصفحة التالية في مجموعة النتائج |
الأخطاء
لا تحدِّد واجهة برمجة التطبيقات أي رسائل خطأ فريدة لهذه الطريقة. ومع ذلك، قد تؤدي هذه الطريقة إلى عرض أخطاء عامة في واجهة برمجة التطبيقات مُدرَجة في مستندات رسالة الخطأ.
جرّب الآن
استخدِم APIs Explorer لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب البيانات والاستجابة.
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eRetrieves a list of YouTube groups based on specified criteria, such as group IDs or ownership by the authenticated user.\u003c/p\u003e\n"],["\u003cp\u003eRequires authorization with specific scopes to access group data, including read-only access to YouTube Analytics reports.\u003c/p\u003e\n"],["\u003cp\u003eAllows filtering by group IDs (\u003ccode\u003eid\u003c/code\u003e parameter) or retrieving all groups owned by the authenticated user (\u003ccode\u003emine\u003c/code\u003e parameter).\u003c/p\u003e\n"],["\u003cp\u003eSupports optional parameters like \u003ccode\u003eonBehalfOfContentOwner\u003c/code\u003e for content owners managing multiple channels and \u003ccode\u003epageToken\u003c/code\u003e for pagination.\u003c/p\u003e\n"],["\u003cp\u003eReturns a response containing group details, including kind, Etag, items (list of groups), and a token for retrieving the next page of results.\u003c/p\u003e\n"]]],["This API method retrieves a list of YouTube Analytics groups. Requests are made via a `GET` request to a specified URL. Authentication requires specific scopes like `yt-analytics.readonly`. Users can filter groups by specifying group `id`s or by setting `mine` to `true` to get all groups they own. The response contains an `etag`, a list of `groups`, and potentially a `nextPageToken` for pagination. The method has the possibility to use `onBehalfOfContentOwner` for content owners.\n"],null,["# Groups: list\n\nReturns a list of groups that match the API request parameters. For example, you can retrieve all groups that the authenticated user owns, or you can retrieve one or more groups by their unique IDs.\n\nRequest\n-------\n\n### HTTP request\n\n```\nGET https://youtubeanalytics.googleapis.com/v2/groups\n```\n\n### Authorization\n\nThis request requires authorization with at least one of the following scopes ([read more about authentication and authorization](/youtube/analytics/authentication)).\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| https://www.googleapis.com/auth/youtube | Manage your YouTube account. In the YouTube Analytics API, channel owners use this scope to manage YouTube Analytics groups and group items. |\n| https://www.googleapis.com/auth/youtubepartner | View and manage YouTube assets and associated content on YouTube. In the YouTube Analytics API, content owners use this scope to manage YouTube Analytics groups and group items. |\n\n### Parameters\n\nThe table below lists the parameters that this query supports. All of the parameters listed are query parameters.\n\n| Parameters ||\n|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|\n| **Filters (specify exactly one of the following parameters)** |||\n| `id` | `string` The **id** parameter specifies a comma-separated list of the YouTube group ID(s) for the resource(s) that are being retrieved. Each group must be owned by the authenticated user. In a `group` resource, the `id` property specifies the group's YouTube group ID. Note that if you do not specify a value for the `id` parameter, then you must set the `mine` parameter to `true`. |\n| `mine` | `boolean` This parameter can only be used in a properly [authorized request](/youtube/analytics/authentication). Set this parameter's value to `true` to retrieve all groups owned by the authenticated user. |\n| **Optional parameters** |||\n| `onBehalfOfContentOwner` | `string` This parameter can only be used in a properly [authorized request](/youtube/analytics/authentication). **Note:** This parameter is intended exclusively for YouTube content partners that own and manage many different YouTube channels. The **onBehalfOfContentOwner** parameter indicates that the request's authorization credentials identify a YouTube user who is acting on behalf of the content owner specified in the parameter value. It allows content owners to authenticate once and get access to all their video and channel data, without having to provide authentication credentials for each individual channel. The account that the user authenticates with must be linked to the specified YouTube content owner. |\n| `pageToken` | `string` The `pageToken` parameter identifies a specific page in the result set that should be returned. In an API response, the `nextPageToken` property identifies the next page that can be retrieved. |\n\n### Request body\n\nDo not provide a request body when calling this method.\n\nResponse\n--------\n\nIf successful, this method returns a response body with the following structure: \n\n```objective-c\n{\n \"#kind\": \"youtube#groupListResponse\",\n \"#etag\": etag,\n \"#items[]\": [\n group Resource\n ],\n \"#nextPageToken\": string\n}\n```\n\n### Properties\n\nThe following table defines the properties that appear in this resource:\n\n| Properties ||\n|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `kind` | `string` Identifies the API resource's type. The value will be `youtube#groupListResponse`. |\n| `etag` | `etag` The Etag of this resource. |\n| `items[]` | `list` A list of groups that match the API request parameters. Each item in the list represents a [group](/youtube/analytics/reference/groups) resource. |\n| `nextPageToken` | `string` The token that can be used as the value of the `pageToken` parameter to retrieve the next page in the result set. |\n\nErrors\n------\n\nThe API does not define any error messages that are unique to this API method. However, this method could still return general API errors listed in the [error message](/youtube/analytics/reference/errors#general) documentation.\n\nTry it!\n-------\n\nUse the APIs Explorer to call this API and see the API request and response."]]
