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 CMS الذي يتصرف نيابةً عن مالك المحتوى المحدد في قيمة المعلمة. هذه المعلمة مخصصة لشركاء محتوى YouTube الذين يملكون ويديرون العديد من قنوات YouTube المختلفة. تتيح هذه الميزة لمالكي المحتوى المصادقة مرة واحدة والوصول إلى كل بيانات الفيديو والقناة بدون الحاجة إلى تقديم بيانات اعتماد المصادقة لكل قناة على حدة. يجب ربط حساب نظام إدارة المحتوى الذي يصادق المستخدم عليه بمالك محتوى YouTube المحدد.
onBehalfOfContentOwnerChannel string
لا يمكن استخدام هذه المعلّمة إلا في طلب مفوَّض بشكلٍ سليم. ملاحظة: هذه المعلمة مخصّصة حصريًا لشركاء محتوى YouTube.

تحدّد المعلمة onBehalfOfContentOwnerChannel معرّف قناة YouTube للقناة التي تتم إضافة الفيديو إليها. وتكون هذه المعلّمة مطلوبة عندما يحدّد الطلب قيمة للمعلمة onBehalfOfContentOwner، ولا يمكن استخدامها إلا مع هذه المعلّمة. بالإضافة إلى ذلك، يجب أن يكون الطلب مفوَّضًا باستخدام حساب نظام إدارة المحتوى (CMS) المرتبط بمالك المحتوى الذي تحدّده المعلّمة 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 لاستدعاء واجهة برمجة التطبيقات هذه والاطّلاع على طلب واجهة برمجة التطبيقات والاستجابة له.