Subscriptions: list

تعرض هذه الطريقة موارد الاشتراكات التي تطابق معايير طلب واجهة برمجة التطبيقات.

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

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

طلب

طلب HTTP

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

المعلمات

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

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

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

تحتوي القائمة التالية على أسماء part التي يمكنك تضمينها في قيمة المَعلمة:
  • contentDetails
  • id
  • snippet
  • subscriberSnippet
الفلاتر (حدِّد مَعلمة واحدة فقط من المَعلمات التالية)
channelId string
تحدّد المَعلمة channelId معرّف قناة على YouTube. ولن تعرض واجهة برمجة التطبيقات سوى اشتراكات تلك القناة.
id string
تحدّد المَعلمة id قائمة قيم مفصولة بفاصلة بمعرّفات اشتراكات YouTube للموارد التي يتم استردادها. في مورد subscription، تحدّد السمة id معرّف اشتراك YouTube.
mine boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب مُفوَّض بشكل صحيح. اضبط قيمة هذه المَعلمة على true لاسترداد خلاصة اشتراكات المستخدم الذي تمّت مصادقته.
myRecentSubscribers boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب مُفوَّض بشكل صحيح. اضبط قيمة هذه المَعلمة على true لاسترداد خلاصة بالمشتركين في قناة المستخدم الذي تمّت مصادقته بترتيب زمني عكسي (الأحدث أولاً).

يُرجى العِلم أنّ الحد الأقصى لعدد المشتركين الذين يتم عرضهم من خلال واجهة برمجة التطبيقات هذه قد يكون محدودًا.
mySubscribers boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب مُفوَّض بشكل صحيح. اضبط قيمة هذه المَعلمة على true لاسترداد خلاصة بالمشتركين في قناة المستخدم الذي تمّت مصادقته بدون ترتيب معيّن. يُرجى العِلم أنّ الحد الأقصى لعدد المشتركين الذين يتم عرضهم من خلال واجهة برمجة التطبيقات هذه قد يكون محدودًا.
المعلمات الاختيارية
forChannelId string
تحدّد المَعلمة forChannelId قائمة بمعرّفات القنوات مفصولة بفواصل. ولن تتضمّن استجابة واجهة برمجة التطبيقات سوى الاشتراكات التي تطابق تلك القنوات.
maxResults unsigned integer
تحدّد المَعلمة maxResults الحد الأقصى لعدد العناصر التي يجب عرضها في مجموعة النتائج. القيم المقبولة هي من 0 إلى 50 ضِمنًا. القيمة التلقائية هي 5.
onBehalfOfContentOwner string
ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء المحتوى على YouTube.

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

تحدّد المَعلمة onBehalfOfContentOwnerChannel معرّف قناة YouTube التي تتم إضافة فيديو إليها. تكون هذه المَعلمة مطلوبة عندما يحدّد الطلب قيمة للمَعلمة onBehalfOfContentOwner، ولا يمكن استخدامها إلا مع تلك المَعلمة. بالإضافة إلى ذلك، يجب تفويض الطلب باستخدام حساب في نظام إدارة المحتوى مرتبط بمالك المحتوى الذي تحدّده المَعلمة onBehalfOfContentOwner. أخيرًا، يجب ربط القناة التي تحدّدها قيمة المَعلمة onBehalfOfContentOwnerChannel بمالك المحتوى الذي تحدّده المَعلمة onBehalfOfContentOwner.

هذه المَعلمة مخصّصة لشركاء المحتوى على YouTube الذين يملكون ويديرون العديد من قنوات YouTube المختلفة. تسمح هذه المَعلمة لمالكي المحتوى بالمصادقة مرة واحدة وتنفيذ الإجراءات نيابةً عن القناة المحدّدة في قيمة المَعلمة، بدون الحاجة إلى تقديم بيانات اعتماد المصادقة لكل قناة على حدة.
order string
تحدّد المَعلمة order الطريقة التي سيتم استخدامها لترتيب الموارد في ردّ من واجهة برمجة التطبيقات. القيمة التلقائية هي SUBSCRIPTION_ORDER_RELEVANCE.

القيم المقبولة هي:
  • alphabetical : الترتيب أبجديًا
  • relevance : الترتيب حسب مدى الصلة بالموضوع
  • unread : الترتيب حسب ترتيب النشاط
pageToken string
تحدّد المَعلمة pageToken صفحة معيّنة في مجموعة النتائج يجب عرضها. في ردّ من واجهة برمجة التطبيقات، تحدّد السمتان nextPageToken وprevPageToken صفحات أخرى يمكن استردادها.

نص الطلب

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

الردّ

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

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

الخصائص

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

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

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
forbidden (403) accountClosed تعذّر استرداد الاشتراكات لأنّ حساب المشترك مغلق.
forbidden (403) accountSuspended تعذّر استرداد الاشتراكات لأنّ حساب المشترك معلّق.
forbidden (403) subscriptionForbidden لا يُسمح لمقدِّم الطلب بالوصول إلى الاشتراكات المطلوبة.
notFound (404) subscriberNotFound تعذّر العثور على المشترك الذي تم تحديده في الطلب.

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

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