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 CMS الذي يتصرف نيابةً عن مالك المحتوى المحدد في قيمة المعلمة. هذه المعلمة مخصصة لشركاء محتوى 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
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 لاستدعاء واجهة برمجة التطبيقات هذه والاطّلاع على طلب واجهة برمجة التطبيقات والاستجابة له.