لعرض قائمة من مقاطع الفيديو التي تطابق معلمات طلب واجهة برمجة التطبيقات.
تأثير الحصّة: إنّ استدعاء لهذه الطريقة لديه تكلفة حصة وحدة واحدة.
حالات الاستخدام الشائعة
طلب
طلب HTTP
GET https://www.googleapis.com/youtube/v3/videos
المعلَمات
يسرد الجدول التالي المعلمات التي يدعمها طلب البحث هذا. جميع المعلمات المدرجة هي معلمات طلب بحث.
المعلَمات | ||
---|---|---|
المعلّمات المطلوبة | ||
part |
string تحدّد المعلمة part قائمة مفصولة بفواصل لخاصية مورد واحدة أو أكثر من video التي ستتضمّن استجابة واجهة برمجة التطبيقات.إذا حدّدت المعلّمة موقعًا يحتوي على مواقع فرعية، سيتم تضمين الخصائص الفرعية في الاستجابة. على سبيل المثال، في مورد video ، تحتوي الخاصية snippet على السمات channelId وtitle وdescription وtags وcategoryId . وبالتالي، في حال ضبط part=snippet ، ستحتوي استجابة واجهة برمجة التطبيقات على كل هذه المواقع.تحتوي القائمة التالية على أسماء part التي يمكنك تضمينها في قيمة المعلّمة:
|
|
الفلاتر (حدد معلمة واحدة من المعلمات التالية) | ||
chart |
string تحدد المعلمة chart الرسم البياني الذي تريد استرداده.القيم المقبولة هي:
|
|
id |
string تحدّد المعلمة id قائمة بمعرّفات فيديوهات YouTube مفصولة بفواصل للموارد التي يتم استردادها. في الخاصية video ، تحدّد السمة id رقم تعريف الفيديو. |
|
myRating |
string لا يمكن استخدام هذه المعلّمة إلا في طلب مفوَّض بشكلٍ سليم. اضبط قيمة هذه المعلّمة على like أو dislike لتوجيه واجهة برمجة التطبيقات بحيث لا تعرض سوى الفيديوهات التي أبدى المستخدم الذي تمت مصادقته إعجابه أو عدم إعجابه بها.القيم المقبولة هي:
|
|
المعلّمات الاختيارية | ||
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 لاستدعاء واجهة برمجة التطبيقات هذه والاطّلاع على طلب واجهة برمجة التطبيقات والاستجابة له.