Sponsors: list

ملاحظة: تم إيقاف هذه الطريقة نهائيًا اعتبارًا من 31 آذار (مارس) 2020. وقد تم استبدالها بالطريقة members.list. ويمكنك الاطّلاع على معلومات حول هذه الطريقة في مستندات YouTube Data API.

لن تكون الطريقة sponsors.list متاحة اعتبارًا من 30 أيلول (سبتمبر) 2020 أو بعد هذا التاريخ. يجب أن تعدّل برامج واجهة برمجة التطبيقات طلبات البيانات إلى الطريقة sponsors.list لاستخدام الإجراء members.list بدلاً من ذلك.

يعرض هذا القسم الأعضاء (المعروفين سابقًا باسم "الجهات الراعية") لقناة. يجب أن يكون طلب البيانات من واجهة برمجة التطبيقات معتمَدًا من مالك القناة.

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

الطلب

طلب HTTP

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

التفويض

يتطلب هذا الطلب تفويضًا باستخدام نطاق واحد على الأقل من النطاقات التالية (مزيد من المعلومات عن المصادقة والترخيص).

النطاق
https://www.googleapis.com/auth/youtube
https://www.googleapis.com/auth/youtube.force-ssl
https://www.googleapis.com/auth/youtube.readonly

المَعلمات

يسرد الجدول التالي المعلَمات التي يتيحها طلب البحث هذا. كلّ المَعلمات المدرَجة هي مَعلمات طلب بحث.

المَعلمات
المَعلمات المطلوبة
part string
تحدّد المعلَمة part أجزاء الموارد sponsor التي ستتضمّنها استجابة واجهة برمجة التطبيقات. القيمتان المسموح بإدراجهما هما id وsnippet.
المَعلمات الاختيارية
filter string
تحدّد المعلَمة filter الجهات الراعية للقناة التي تريد عرضها. القيمة التلقائية هي newest.

القيم المقبولة هي:
  • all – عرض كل الجهات الراعية، من الأحدث إلى الأقدم.
  • newest – عرض صفحة واحدة لأحدث الجهات الراعية. في حال استخدام علامة nextPageToken، يمكنك استرداد المشتركين الجُدد في الطلبات التالية عند اشتراكهم.
maxResults unsigned integer
تحدّد المعلَمة maxResults الحدّ الأقصى لعدد العناصر التي يجب عرضها في مجموعة النتائج. تتراوح القيم المقبولة بين 0 و50، بما في ذلك القيم الواقعة بينهما. القيمة التلقائية هي 5.
pageToken string
تحدِّد المعلَمة pageToken صفحة معيّنة في مجموعة النتائج يجب عرضها. في استجابة واجهة برمجة التطبيقات، تحدّد السمتان nextPageToken وprevPageToken الصفحات الأخرى التي يمكن استردادها.

نص الطلب

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

الإجابة

إذا نجحت هذه الطريقة، ستعرض هذه الطريقة نص استجابة بالبنية التالية:

{
  "kind": "youtube#sponsorListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    sponsor resource
  ]
}

أماكن إقامة

يحدد الجدول التالي الخصائص التي تظهر في هذا المورد:

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

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
forbidden (403) insufficientPermissions ليست لديك الأذونات اللازمة لمشاهدة الجهات الراعية للقناة.
invalidValue (400) invalidValueInRequest يحتوي الطلب على قيمة غير صالحة.
invalidValue (400) sponsorshipNotEnabledForChannelId لم يتمّ تفعيل ميزة "عروض الرعاية" في القناة.

تجربة

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