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 التي يمكنك تضمينها في قيمة المَعلمة:
  • brandPartner
  • contentDetails
  • fileDetails
  • id
  • liveStreamingDetails
  • localizations
  • paidProductPlacementDetails
  • player
  • processingDetails
  • recordingDetails
  • snippet
  • statistics
  • status
  • suggestions
  • topicDetails
الفلاتر (يجب تحديد مَعلمة واحدة فقط من المَعلمات التالية)
chart string
تحدّد المَعلمة chart الرسم البياني الذي تريد استرداده.

القيم المقبولة هي:
id string
تحدّد المَعلمة id قائمة قيم مفصولة بفاصلة تتضمّن معرّفات فيديوهات على YouTube للمصادر التي يتم استردادها. في مصدر video، تحدّد السمة id معرّف الفيديو.
myRating string

لا يمكن استخدام هذه المَعلمة إلا في طلب مُفوَّض بشكلٍ صحيح. اضبط قيمة هذه المَعلمة على like أو dislike لتوجيه واجهة برمجة التطبيقات لعرض الفيديوهات التي أعجب بها المستخدم الذي تم التحقّق من هويته أو لم تعجبه فقط.



تحدّ واجهة برمجة التطبيقات مجموعة النتائج المعروضة بـ 1000 فيديو كحدّ أقصى. حتى إذا كانت السمة pageInfo.totalResults في الاستجابة تشير إلى إجمالي أعلى، لا يتيح الترقيم باستخدام المَعلمة pageToken استرداد آخر 1000 عنصر فقط.



تقبل المَعلمة القيم التالية:

  • 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
السمة 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 لطلب واجهة برمجة التطبيقات هذه والاطّلاع على طلب بيانات من واجهة برمجة التطبيقات والاستجابة.