عرض موارد الاشتراك التي تطابق معايير طلب واجهة برمجة التطبيقات
تأثير الحصة: تتطلب أي مكالمة إلى هذه الطريقة تكلفة حصة تبلغ وحدة واحدة.
حالات الاستخدام الشائعة
الطلب
طلب HTTP
GET https://www.googleapis.com/youtube/v3/subscriptions
المَعلمات
يسرد الجدول التالي المعلَمات التي يتيحها طلب البحث هذا. كلّ المَعلمات المدرَجة هي مَعلمات طلب بحث.
المَعلمات | ||
---|---|---|
المَعلمات المطلوبة | ||
part |
string تحدّد المعلَمة part قائمة مفصولة بفواصل من سمة واحدة أو أكثر من سمات موارد subscription التي ستتضمّنها استجابة واجهة برمجة التطبيقات.إذا حدّدت المَعلمة موقعًا إلكترونيًا يحتوي على خصائص فرعية، سيتم تضمين السمات الفرعية في الاستجابة. على سبيل المثال، في مورد subscription ، تحتوي السمة snippet على خصائص أخرى، مثل العنوان المعروض للاشتراك. في حال ضبط السمة part=snippet ، ستحتوي استجابة واجهة برمجة التطبيقات أيضًا على كل هذه السمات المدمَجة.تحتوي القائمة التالية على أسماء part التي يمكنك تضمينها في قيمة المَعلمة:
|
|
الفلاتر (حدِّد إحدى المَعلمات التالية بالضبط) | ||
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 ، ولا يمكن استخدامها إلا مع تلك المعلَمة. بالإضافة إلى ذلك، يجب أن يكون الطلب مصرّحًا به باستخدام حساب "نظام إدارة المحتوى" (CMS) المرتبط بمالك المحتوى الذي تحدّده المَعلمة onBehalfOfContentOwner . أخيرًا، يجب أن تكون القناة التي تحددها قيمة المعلَمة onBehalfOfContentOwnerChannel مرتبطة بمالك المحتوى الذي تحدّده المَعلمة onBehalfOfContentOwner .هذه المَعلمة مخصّصة لشركاء المحتوى في YouTube الذين يملكون العديد من قنوات YouTube المختلفة ويديرونها. وهي تتيح لمالكي المحتوى إجراء المصادقة مرة واحدة وتنفيذ إجراءات بالنيابة عن القناة المحددة في قيمة المعلَمة، بدون الحاجة إلى تقديم بيانات اعتماد مصادقة لكل قناة منفصلة. |
|
order |
string تحدّد المعلَمة order الطريقة التي سيتم استخدامها لترتيب الموارد في استجابة واجهة برمجة التطبيقات. القيمة التلقائية هي SUBSCRIPTION_ORDER_RELEVANCE .القيم المقبولة هي:
|
|
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 علامة هذا المرجع. |
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 لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب البيانات من واجهة برمجة التطبيقات والاستجابة لها.