Channels: list

ملاحظة: تم تعديل قيمة السمة statistics.subscriberCount في المورد channel لتعكس تغييرًا في سياسة YouTube يؤثر في طريقة عرض أعداد المشتركين. لمزيد من المعلومات، يُرجى الاطّلاع على سجلّ النُسخ السابقة أو مركز مساعدة YouTube.

تعرض هذه السمة مجموعة من موارد channel التي تتطابق مع معايير الطلب، وقد لا تعرض أي مورد.

التأثير في الحصة: تبلغ تكلفة الحصة لطلب البيانات من هذه الطريقة وحدة واحدة.

حالات الاستخدام الشائعة

طلب

طلب HTTP

GET https://www.googleapis.com/youtube/v3/channels

التفويض

يجب أن يقدّم الطلب الذي يسترد الجزء auditDetails من المورد channel رمز موافقة مميزًا يتضمّن النطاق https://www.googleapis.com/auth/youtubepartner-channel-audit. بالإضافة إلى ذلك، يجب إبطال أي رمز مميّز يستخدم هذا النطاق عندما تقرّر الشبكة المتعددة القنوات قبول القناة أو رفضها، أو في غضون أسبوعَين من تاريخ إصدار الرمز المميّز.

المعلمات

يعرض الجدول التالي المَعلمات التي يتيحها هذا الطلب. جميع المَعلمات المُدرَجة هي مَعلمات طلب بحث.

المعلمات
المَعلمات المطلوبة
part string
تحدّد المَعلمة part قائمة قيم مفصولة بفاصلة لسمة واحدة أو أكثر من سمات المورد channel التي سيتضمّنها الردّ من واجهة برمجة التطبيقات.

إذا كانت المَعلمة تحدّد سمة تتضمّن سمات فرعية، سيتم تضمين السمات الفرعية في الردّ. على سبيل المثال، في مورد channel، تحتوي السمة contentDetails على سمات أخرى، مثل سمات uploads. وبالتالي، إذا ضبطت part=contentDetails، سيتضمّن الردّ من واجهة برمجة التطبيقات أيضًا جميع هذه السمات المدمجة.

تحتوي القائمة التالية على أسماء part التي يمكنك تضمينها في قيمة المَعلمة:
  • auditDetails
  • brandingSettings
  • contentDetails
  • contentOwnerDetails
  • id
  • localizations
  • snippet
  • statistics
  • status
  • topicDetails
الفلاتر (يجب تحديد مَعلمة واحدة فقط من المَعلمات التالية)
categoryId string
تم إيقاف هذه المَعلمة نهائيًا. حدّدت المَعلمة categoryId فئة دليل YouTube وكان من الممكن استخدامها لطلب قنوات على YouTube المرتبطة بتلك الفئة.
forHandle string
تحدّد المَعلمة forHandle اسمًا معرِّفًا على YouTube، وبالتالي تطلب القناة المرتبطة بهذا الاسم المعرِّف. يمكن أن تبدأ قيمة المَعلمة بالرمز @. على سبيل المثال، لاسترداد المورد الخاص بقناة "Google for Developers"، اضبط قيمة المَعلمة forHandle على GoogleDevelopers أو @GoogleDevelopers.
forUsername string
تحدّد المَعلمة forUsername اسم مستخدم على YouTube، وبالتالي تطلب القناة المرتبطة باسم المستخدم هذا.
id string
تحدّد المَعلمة id قائمة قيم مفصولة بفاصلة لمعرّفات قنوات YouTube الخاصة بالمراجع التي يتم استردادها. في مورد channel، تحدّد السمة id معرّف القناة على YouTube.
managedByMe boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب مصرَّح به بشكل صحيح.

ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء المحتوى في YouTube.

اضبط قيمة هذه المَعلمة على true لإعلام واجهة برمجة التطبيقات بأنّ عليها عرض القنوات التي يديرها مالك المحتوى الذي تحدّده المَعلمة onBehalfOfContentOwner فقط. يجب مصادقة المستخدم كحساب على "نظام إدارة المحتوى" مرتبط بمالك المحتوى المحدّد، ويجب تقديم onBehalfOfContentOwner.
mine boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب معتمَد بشكل صحيح. اضبط قيمة هذه المَعلمة على true لإعلام واجهة برمجة التطبيقات بأنّ عليها عرض القنوات التي يملكها المستخدم الذي تمت مصادقته فقط.
المَعلمات الاختيارية
hl string
تطلب المَعلمة hl من واجهة برمجة التطبيقات استرداد البيانات الوصفية المترجَمة للمورد بلغة معيّنة من لغات التطبيق التي يتيحها موقع YouTube الإلكتروني. يجب أن تكون قيمة المَعلمة رمز لغة مضمّنًا في القائمة التي تعرضها الطريقة i18nLanguages.list.

إذا كانت تفاصيل المورد المترجَمة متوفّرة بهذه اللغة، سيحتوي العنصر snippet.localized الخاص بالمورد على القيم المترجَمة. ومع ذلك، إذا لم تتوفّر تفاصيل معدَّلة بما يناسب السوق المحلية، سيحتوي العنصر snippet.localized على تفاصيل المرجع باللغة التلقائية للمرجع.
maxResults unsigned integer
تحدّد المَعلمة maxResults الحد الأقصى لعدد العناصر التي يجب عرضها في مجموعة النتائج. القيم المقبولة هي من 0 إلى 50، ضِمنًا. القيمة التلقائية هي 5.
onBehalfOfContentOwner string
لا يمكن استخدام هذه المَعلمة إلا في طلب مصرَّح به بشكل صحيح.

ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء المحتوى في YouTube.

تشير المَعلمة onBehalfOfContentOwner إلى أنّ بيانات اعتماد التفويض الخاصة بالطلب تحدّد مستخدمًا لنظام إدارة محتوى YouTube يتصرّف نيابةً عن مالك المحتوى المحدّد في قيمة المَعلمة. هذه المَعلمة مخصّصة لشركاء المحتوى في YouTube الذين يملكون ويديرون العديد من قنوات على YouTube المختلفة. تتيح هذه الميزة لمالكي المحتوى المصادقة مرة واحدة والوصول إلى جميع بيانات الفيديوهات والقنوات، بدون الحاجة إلى تقديم بيانات اعتماد للمصادقة لكل قناة على حدة. يجب ربط حساب نظام إدارة المحتوى الذي يصادق عليه المستخدم بحساب مالك المحتوى المحدّد على YouTube.
pageToken string
تحدّد المَعلمة pageToken صفحة معيّنة في مجموعة النتائج التي يجب عرضها. في الردّ من واجهة برمجة التطبيقات، تحدّد السمتان nextPageToken وprevPageToken الصفحات الأخرى التي يمكن استردادها.

نص الطلب

لا تقدّم نص طلب عند استدعاء هذه الطريقة.

الردّ

في حال نجاح العملية، يعرض هذا الإجراء نص استجابة بالبنية التالية:

{
  "kind": "youtube#channelListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    channel Resource
  ]
}

الخصائص

يحدّد الجدول التالي السمات التي تظهر في هذا المورد:

الخصائص
kind string
يحدّد نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#channelListResponse.
etag etag
تمثّل هذه السمة علامة Etag لهذا المورد.
nextPageToken string
الرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken من أجل استرداد الصفحة التالية في مجموعة النتائج.
prevPageToken string
الرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken لاسترداد الصفحة السابقة في مجموعة النتائج. يُرجى العِلم أنّ هذه السمة لا يتم تضمينها في الردّ من واجهة برمجة التطبيقات إذا تم ضبط المَعلمة managedByMe على true في طلب البيانات من واجهة برمجة التطبيقات.
pageInfo object
يحتوي العنصر pageInfo على معلومات تقسيم النتائج إلى صفحات.
pageInfo.totalResults integer
تمثّل هذه السمة إجمالي عدد النتائج في مجموعة النتائج.
pageInfo.resultsPerPage integer
عدد النتائج المضمّنة في الردّ من واجهة برمجة التطبيقات.
items[] list
قائمة بالقنوات التي تتطابق مع معايير الطلب.

الأخطاء

يوضّح الجدول التالي رسائل الخطأ التي يمكن أن تعرضها واجهة برمجة التطبيقات ردًا على طلب بيانات من هذه الطريقة. لمزيد من التفاصيل، يُرجى الاطّلاع على YouTube Data API - الأخطاء.

نوع الخطأ تفاصيل الخطأ الوصف
badRequest (400) invalidCriteria يمكن تحديد فلتر واحد كحد أقصى من الفلاتر التالية:id أو categoryId أو mine أو managedByMe أو forHandle أو forUsername. في حال مصادقة مالك المحتوى من خلال المَعلمة onBehalfOfContentOwner، يمكن تحديد id أو managedByMe فقط.
forbidden (403) channelForbidden لا تتيح القناة المحدّدة بواسطة المَعلمة id الطلب أو لم يتم تفويض الطلب بشكل صحيح.
notFound (404) categoryNotFound يتعذّر العثور على الفئة التي تم تحديدها من خلال المَعلمة categoryId. استخدِم طريقة guideCategories.list لاسترداد قائمة بالقيم الصالحة.
notFound (404) channelNotFound يتعذّر العثور على القناة المحدّدة في المَعلمة id.

جرِّبها الآن.

استخدِم APIs Explorer لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب واجهة برمجة التطبيقات والاستجابة.