Videos: list

عرض قائمة بالفيديوهات التي تطابق مَعلمات طلب البيانات من واجهة برمجة التطبيقات.

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

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

الطلب

طلب HTTP

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

المَعلمات

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

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

إذا حدّدت المَعلمة موقعًا إلكترونيًا يحتوي على خصائص فرعية، سيتم تضمين السمات الفرعية في الاستجابة. على سبيل المثال، في مورد video، تتضمّن السمة snippet السمات channelId وtitle وdescription وtags وcategoryId. وبالتالي، في حال ضبط السمة part=snippet، ستحتوي استجابة واجهة برمجة التطبيقات على جميع هذه السمات.

تحتوي القائمة التالية على أسماء part التي يمكنك تضمينها في قيمة المَعلمة:
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
الفلاتر (حدِّد إحدى المَعلمات التالية بالضبط)
chart string
تحدِّد المعلَمة chart الرسم البياني الذي تريد استرداده.

القيم المقبولة هي:
id string
تحدّد المعلَمة id قائمة بمعرّفات الفيديوهات على YouTube للموارد التي يتم استردادها، ويتم الفصل بين هذه القائمة بفاصلات. في مورد video، تحدّد السمة id معرّف الفيديو.
myRating string
لا يمكن استخدام هذه المَعلمة إلا في طلب معتمد بشكل صحيح. يمكنك ضبط قيمة هذه المَعلمة على like أو dislike لتوجيه واجهة برمجة التطبيقات بحيث لا يتم عرض سوى الفيديوهات التي أبدى المستخدم إعجابه بها أو لم يعجبه.

القيم المقبولة هي:
  • dislike – لعرض الفيديوهات التي لم تعجب المستخدم الذي تمت المصادقة عليه فقط.
  • like – لعرض الفيديو الذي أبدى المستخدم إعجابه به فقط.
المَعلمات الاختيارية
hl string
توجّه المَعلمة hl واجهة برمجة التطبيقات إلى استرداد البيانات الوصفية للموارد المترجَمة إلى لغة تطبيق محدّدة يتيحها موقع YouTube الإلكتروني. يجب أن تكون قيمة المعلَمة رمزًا للغة مضمّنة في القائمة التي تعرضها طريقة i18nLanguages.list.

في حال توفّر تفاصيل الموارد المترجَمة بتلك اللغة، سيحتوي عنصر snippet.localized للمورد على القيم المترجمة. في حال عدم توفّر التفاصيل المترجَمة، سيحتوي العنصر snippet.localized على تفاصيل المورد باللغة التلقائية للمورد.
maxHeight unsigned integer
تحدّد المعلَمة maxHeight الحدّ الأقصى لارتفاع المشغّل المضمَّن الذي يتم عرضه في السمة player.embedHtml. يمكنك استخدام هذه المعلمة لتحديد أنه بدلاً من الأبعاد الافتراضية، يجب أن يستخدم رمز التضمين ارتفاعًا مناسبًا لتخطيط تطبيقك. إذا تم توفير المعلَمة maxWidth أيضًا، قد يكون المشغِّل أقصر من maxHeight حتى لا ينتهك الحد الأقصى للعرض. تتراوح القيم المقبولة بين 72 و8192، بما في ذلك القيم الواقعة بينهما.
maxResults unsigned integer
تحدّد المعلَمة maxResults الحدّ الأقصى لعدد العناصر التي يجب عرضها في مجموعة النتائج.

ملاحظة: يمكن استخدام هذه المَعلمة مع المَعلمة myRating، ولكنّها غير متاحة للاستخدام مع المَعلمة id. تتراوح القيم المقبولة بين 1 و50، بما في ذلك القيم الواقعة بينهما. القيمة التلقائية هي 5.
maxWidth unsigned integer
تحدّد المعلَمة maxWidth الحدّ الأقصى لعرض المشغّل المضمَّن الذي يتم عرضه في السمة player.embedHtml. يمكنك استخدام هذه المعلمة لتحديد أنه بدلاً من الأبعاد التلقائية، يجب أن يستخدم رمز التضمين عرضًا مناسبًا لتنسيق تطبيقك.

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

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

ملاحظة: يمكن استخدام هذه المَعلمة مع المَعلمة myRating، ولكنّها غير متاحة للاستخدام مع المَعلمة id.
regionCode string
توجّه المَعلمة regionCode واجهة برمجة التطبيقات إلى اختيار رسم بياني لفيديو متاح في المنطقة المحدّدة. لا يمكن استخدام هذه المَعلمة إلا مع المَعلمة chart. قيمة المَعلمة هي رمز بلد بصيغة ISO 3166-1 alpha-2.
videoCategoryId string
تحدّد المعلَمة videoCategoryId فئة الفيديو التي يجب استرداد الرسم البياني الخاص بها. لا يمكن استخدام هذه المَعلمة إلا مع المَعلمة chart. بشكل افتراضي، لا تقتصر المخططات على فئة معينة. القيمة التلقائية هي 0.

نص الطلب

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

الإجابة

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

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

أماكن إقامة

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

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

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
badRequest (400) videoChartNotFound مخطط الفيديو المطلوب غير متوافق أو غير متاح.
forbidden (403) forbidden الطلب غير مفوَّض بشكل صحيح للوصول إلى ملف الفيديو أو معلومات المعالجة. ملاحظة: لا تتوفّر الأجزاء fileDetails وprocessingDetails وsuggestions إلا لمالك الفيديو.
forbidden (403) forbidden يتعذّر على الطلب الوصول إلى معلومات تقييم المستخدم. قد يحدث هذا الخطأ لأنّ الطلب غير مفوَّض بشكل صحيح لاستخدام المعلَمة myRating.
notFound (404) videoNotFound يتعذر العثور على الفيديو الذي تحاول استرداده. تحقّق من قيمة معلَمة id للطلب للتأكّد من صحتها.

تجربة

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