Playlists: list

تعرض هذه الطريقة مجموعة من قوائم التشغيل التي تتطابق مع مَعلمات طلب بيانات من واجهة برمجة التطبيقات. على سبيل المثال، يمكنك استرداد جميع قوائم التشغيل التي يملكها المستخدم الذي تم التحقّق من هويته، أو يمكنك استرداد قائمة تشغيل واحدة أو أكثر باستخدام أرقام تعريفها الفريدة.

تأثير الحصة: يؤدي طلب هذه الطريقة إلى استهلاك وحدة واحدة من الحصة.

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

طلب

طلب HTTP

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

المعلمات

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

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

إذا كانت المَعلمة تحدّد سمة تحتوي على سمات فرعية، سيتم تضمين السمات الفرعية في الردّ. على سبيل المثال، في مصدر playlist، تحتوي السمة snippet على سمات مثل author وtitle وdescription وtimeCreated. وبالتالي، إذا ضبطت part=snippet، ستتضمّن استجابة واجهة برمجة التطبيقات جميع هذه السمات.

تحتوي القائمة التالية على أسماء part التي يمكنك تضمينها في قيمة المَعلمة:
  • contentDetails
  • id
  • localizations
  • player
  • snippet
  • status
الفلاتر (يجب تحديد مَعلمة واحدة فقط من المَعلمات التالية)
channelId string
تشير هذه القيمة إلى أنّ واجهة برمجة التطبيقات يجب أن تعرض قوائم تشغيل القناة المحدّدة فقط.
id string
تحدّد المَعلمة id قائمة قيم مفصولة بفاصلة تتضمّن أرقام تعريف قوائم تشغيل YouTube للمصادر التي يتم استردادها. في مصدر playlist، تحدّد السمة id رقم تعريف قائمة تشغيل YouTube.
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.
onBehalfOfContentOwnerChannel string
لا يمكن استخدام هذه المَعلمة إلا في طلب مُفوَّض بشكل صحيح. ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء المحتوى على YouTube.

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

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

نص الطلب

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

الردّ

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

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

الخصائص

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

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

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
forbidden (403) channelClosed تم إغلاق القناة المحدّدة في المَعلمة channelId.
forbidden (403) channelSuspended تم تعليق القناة المحدّدة في المَعلمة channelId.
forbidden (403) playlistForbidden لا تتيح قائمة التشغيل المحدّدة باستخدام المَعلمة id في الطلب هذا الطلب، أو أنّ الطلب غير مُفوَّض بشكل صحيح.
notFound (404) channelNotFound يتعذّر العثور على القناة المحدّدة في المَعلمة channelId.
notFound (404) playlistNotFound يتعذّر العثور على قائمة التشغيل المحدّدة باستخدام المَعلمة id في الطلب.
invalidValue (400) playlistOperationUnsupported لا تتيح واجهة برمجة التطبيقات إمكانية إدراج قائمة التشغيل المحدّدة. على سبيل المثال، لا يمكنك إدراج قائمة التشغيل "المشاهدة لاحقًا".

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

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