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
علامة هذا المرجع.
nextPageToken string
الرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken لاسترداد الصفحة التالية في مجموعة النتائج.
prevPageToken string
هو الرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken لاسترداد الصفحة السابقة في مجموعة النتائج. يُرجى العلم أنّ هذا الموقع الإلكتروني لا يتم تضمينه في استجابة واجهة برمجة التطبيقات إذا تم ضبط المَعلمة managedByMe على true في طلب البيانات من واجهة برمجة التطبيقات.
pageInfo object
يحتوي الكائن pageInfo على معلومات التقسيم على صفحات لمجموعة النتائج.
pageInfo.totalResults integer
إجمالي عدد النتائج في مجموعة النتائج.
pageInfo.resultsPerPage integer
عدد النتائج المضمَّنة في ردّ واجهة برمجة التطبيقات
items[] list
قائمة بالقنوات التي تتطابق مع معايير الطلب

الأخطاء

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

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