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 للمطوّرين"، اضبط قيمة المَعلمة forHandle على GoogleDevelopers أو @GoogleDevelopers.
forUsername string
تحدد المَعلمة forUsername اسم مستخدم على YouTube، ما يؤدي إلى طلب القناة المرتبطة باسم المستخدم هذا.
id string
تحدّد المَعلمة id قائمة بمعرّفات قنوات YouTube مفصولة بفواصل للموارد التي يتم استرجاعها. في مورد channel، تحدّد السمة id معرّف قناة YouTube.
managedByMe boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب مفوَّض بشكل صحيح.

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

اضبط قيمة هذه المَعلمة على true لتوجيه واجهة برمجة التطبيقات إلى عرض القنوات التي يديرها فقط مالك المحتوى الذي تحدّده المَعلمة onBehalfOfContentOwner. يجب مصادقة المستخدم كحساب على نظام إدارة المحتوى (CMS) مرتبط بمالك المحتوى المحدّد، ويجب تقديم 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 - Errors.

نوع الخطأ تفاصيل الخطأ الوصف
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 لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب البيانات والاستجابة.