Search: list

تعرض هذه الطريقة مجموعة من نتائج البحث التي تتطابق مع معلمات طلب البحث المحدّدة في طلب البيانات من واجهة برمجة التطبيقات. تحدّد مجموعة نتائج البحث تلقائيًا الموارد المطابقة video وchannel وplaylist، ولكن يمكنك أيضًا ضبط طلبات البحث لاسترداد نوع معيّن فقط من الموارد.

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

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

طلب

طلب HTTP

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

المعلمات

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

المعلمات
المَعلمات المطلوبة
part string
تحدّد المَعلمة part قائمة قيم مفصولة بفاصلة لسمة واحدة أو أكثر من سمات المورد search التي سيتضمّنها الردّ من واجهة برمجة التطبيقات. اضبط قيمة المَعلمة على snippet.
الفلاتر (حدِّد 0 أو 1 من المَعلمات التالية)
forContentOwner boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب مصرَّح به بشكل صحيح، وهي مخصّصة حصريًا لشركاء المحتوى في YouTube.

تفرض المَعلمة forContentOwner قيودًا على عملية البحث لاسترداد الفيديوهات التي يملكها مالك المحتوى الذي تحدّده المَعلمة onBehalfOfContentOwner فقط. إذا تم ضبط السمة forContentOwner على "صحيح"، يجب أن يستوفي الطلب أيضًا المتطلبات التالية:
  • المَعلمة onBehalfOfContentOwner مطلوبة.
  • يجب أن يستخدم المستخدم الذي يفوّض الطلب حسابًا مرتبطًا بمالك المحتوى المحدّد.
  • يجب ضبط قيمة المَعلمة type على video.
  • لا يمكن ضبط أيّ من المَعلمات الأخرى التالية: videoDefinition وvideoDimension وvideoDuration وvideoEmbeddable وvideoLicense وvideoPaidProductPlacement وvideoSyndicated وvideoType.
forDeveloper boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب مصرَّح به بشكل صحيح. يقصر المَعلمة forDeveloper البحث على استرداد الفيديوهات التي تم تحميلها من خلال تطبيق المطوّر أو موقعه الإلكتروني فقط. يستخدم خادم واجهة برمجة التطبيقات بيانات اعتماد التفويض الخاصة بالطلب لتحديد هوية المطوّر. يمكن استخدام المَعلمة forDeveloper مع مَعلمات بحث اختيارية، مثل المَعلمة q.

بالنسبة إلى هذه الميزة، يتم تلقائيًا وضع علامة على كل فيديو تم تحميله برقم المشروع المرتبط بتطبيق المطوّر في Google Developers Console.

عندما يضبط طلب بحث لاحقًا المَعلمة forDeveloper على true، يستخدم خادم واجهة برمجة التطبيقات بيانات اعتماد التفويض الخاصة بالطلب لتحديد المطوّر. لذلك، يمكن للمطوّر حصر النتائج بالفيديوهات التي تم تحميلها من خلال تطبيق المطوّر أو موقعه الإلكتروني، ولكن ليس بالفيديوهات التي تم تحميلها من خلال تطبيقات أو مواقع إلكترونية أخرى.
forMine boolean
لا يمكن استخدام هذه المَعلمة إلا في طلب معتمَد بشكل صحيح. تؤدي المَعلمة forMine إلى حصر البحث في الفيديوهات التي يملكها المستخدم الذي تمّت مصادقته. إذا ضبطت هذه المَعلمة على true، يجب أيضًا ضبط قيمة المَعلمة type على video. بالإضافة إلى ذلك، لا يمكن ضبط أي من المَعلمات الأخرى التالية في الطلب نفسه: videoDefinition وvideoDimension وvideoDuration وvideoEmbeddable وvideoLicense وvideoPaidProductPlacement وvideoSyndicated وvideoType.
المَعلمات الاختيارية
channelId string
تشير المَعلمة channelId إلى أنّ ردّ واجهة برمجة التطبيقات يجب أن يتضمّن فقط الموارد التي أنشأتها القناة.

ملاحظة: تقتصر نتائج البحث على 500 فيديو كحدّ أقصى إذا كان طلبك يحدّد قيمة للمَعلمة channelId ويضبط قيمة المَعلمة type على video، ولكنّه لا يضبط أيضًا أحد الفلاتر forContentOwner أو forDeveloper أو forMine.
channelType string
تتيح لك المَعلمة channelType حصر البحث في نوع معيّن من القنوات.

القيم المقبولة هي:
  • ‫any: لعرض جميع القنوات
  • ‫show: لاسترداد البرامج فقط
eventType string
تحدّد المَعلمة eventType البحث في أحداث البث. إذا حدّدت قيمة لهذه المَعلمة، عليك أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • ‫completed: تضمين أحداث البث المكتملة فقط
  • ‫live: تضمين أحداث البث النشطة فقط
  • ‫upcoming: تضمين أحداث البث القادمة فقط
location string
تحدّد المَعلمة location، بالاشتراك مع المَعلمة locationRadius، منطقة جغرافية دائرية، كما أنّها تحصر البحث في الفيديوهات التي تحدّد في بياناتها الوصفية موقعًا جغرافيًا يقع ضمن تلك المنطقة. قيمة المَعلمة هي سلسلة تحدّد إحداثيات خطوط العرض/الطول، مثل (37.42307,-122.08427).

  • تحدّد قيمة المَعلمة location النقطة في وسط المنطقة.
  • تحدّد المَعلمة locationRadius المسافة القصوى التي يمكن أن يبعدها الموقع الجغرافي المرتبط بالفيديو عن تلك النقطة لكي يظهر الفيديو في نتائج البحث.
تعرض واجهة برمجة التطبيقات خطأ إذا حدّد طلبك قيمة للمَعلمة location بدون تحديد قيمة للمَعلمة locationRadius.

ملاحظة: إذا حدّدت قيمة لهذه المَعلمة، عليك أيضًا ضبط قيمة المَعلمة type على video.
locationRadius string
تحدّد المَعلمة locationRadius، بالاقتران مع المَعلمة location، منطقة جغرافية دائرية.

يجب أن تكون قيمة المَعلمة رقمًا عشريًا عائمًا متبوعًا بوحدة قياس. وحدات القياس الصالحة هي m وkm وft وmi. على سبيل المثال، تشمل قيم المَعلمات الصالحة 1500m و5km و10000ft و0.75mi. لا تتوافق واجهة برمجة التطبيقات مع قيم المَعلمة locationRadius التي تزيد عن 1,000 كيلومتر.

ملاحظة: اطّلِع على تعريف المَعلمة location لمزيد من المعلومات.
maxResults unsigned integer
تحدّد المَعلمة maxResults الحد الأقصى لعدد العناصر التي يجب عرضها في مجموعة النتائج. القيم المقبولة هي من 0 إلى 50، ضمنًا. تكون القيمة التلقائية 5.

onBehalfOfContentOwner string
لا يمكن استخدام هذه المَعلمة إلا في طلب مصرَّح به بشكل صحيح. ملاحظة: هذه المَعلمة مخصّصة حصريًا لشركاء المحتوى في YouTube.

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

القيم المقبولة هي:
  • ‫date: يتم ترتيب الموارد بترتيب زمني عكسي استنادًا إلى تاريخ إنشائها. ملاحظة: بما أنّ هذه الميزة تعتمد على فهرس بحث Google، قد تواجه تأخيرات في فهرسة المحتوى الجديد أو تتلقّى مجموعات نتائج غير مكتملة. للحصول على أحدث الفيديوهات التي تم تحميلها على قناة ما بشكل موثوق، لا تستخدِم search.list. بدلاً من ذلك، استخدِم الطريقة playlistItems.list لجلب قائمة تشغيل الفيديوهات المحمّلة في القناة.
  • ‫rating: يتم ترتيب المراجع من الأعلى تقييمًا إلى الأدنى تقييمًا. ملاحظة: يتم احتساب هذا التقييم باستخدام نتيجة خوارزمية داخلية ولا يعادل تمامًا عدد المعجبين التنازلي.
  • relevance: يتم ترتيب المراجع استنادًا إلى مدى صلتها بطلب البحث. هذه هي القيمة التلقائية لهذه المَعلمة.
  • title – يتم ترتيب المراجع أبجديًا حسب العنوان.
  • ‫videoCount: يتم ترتيب القنوات تنازليًا حسب عدد الفيديوهات المحمَّلة.
  • viewCount: يتم ترتيب المراجع من الأعلى إلى الأقل حسب عدد المشاهدات. بالنسبة إلى أحداث البث المباشر، يتم ترتيب الفيديوهات حسب عدد المشاهدين المتزامنين أثناء البث.
pageToken string
تحدّد المَعلمة pageToken صفحة معيّنة في مجموعة النتائج التي يجب عرضها. في الردّ من واجهة برمجة التطبيقات، تحدّد السمتان nextPageToken وprevPageToken الصفحات الأخرى التي يمكن استردادها.
publishedAfter datetime
تشير المَعلمة publishedAfter إلى أنّ استجابة واجهة برمجة التطبيقات يجب أن تحتوي فقط على الموارد التي تم إنشاؤها في الوقت المحدّد أو بعده. القيمة هي قيمة التاريخ والوقت المنسّقة وفقًا لمعيار RFC 3339‏ (1970-01-01T00:00:00Z).
publishedBefore datetime
تشير المَعلمة publishedBefore إلى أنّ ردّ واجهة برمجة التطبيقات يجب أن يتضمّن فقط الموارد التي تم إنشاؤها قبل الوقت المحدّد أو فيه. القيمة هي قيمة تاريخ ووقت بتنسيق RFC 3339‏ (1970-01-01T00:00:00Z).
q string
تحدّد المَعلمة q عبارة طلب البحث التي تريد البحث عنها.

يمكن أن يستخدم طلبك أيضًا عاملَي التشغيل المنطقيَّين NOT (-) وOR (|) لاستبعاد فيديوهات أو للعثور على فيديوهات مرتبطة بإحدى عبارات البحث المتعددة. على سبيل المثال، للبحث عن فيديوهات تطابق "boating" أو "sailing"، اضبط قيمة المَعلمة q على boating|sailing. وبالمثل، للبحث عن فيديوهات تتطابق مع "boating" أو "sailing" ولكن ليس "fishing"، اضبط قيمة المَعلمة q على boating|sailing -fishing. ملاحظة: يجب تخطّي رمز الخط العمودي عند إرساله في طلب بيانات من واجهة برمجة التطبيقات. القيمة التي تم إلغاء ترميزها في عنوان URL لرمز الشرطة الرأسية هي %7C.
regionCode string
تطلب المَعلمة regionCode من واجهة برمجة التطبيقات عرض نتائج البحث عن الفيديوهات التي يمكن مشاهدتها في البلد المحدّد. قيمة المَعلمة هي رمز بلد ISO 3166-1 alpha-2.
relevanceLanguage string
تطلب المَعلمة relevanceLanguage من واجهة برمجة التطبيقات عرض نتائج البحث الأكثر صلة باللغة المحدّدة. عادةً ما تكون قيمة المَعلمة رمز لغة مكوّنًا من حرفَين وفقًا لمعيار ISO 639-1. ومع ذلك، يجب استخدام القيمتين zh-Hans للغة الصينية المبسَّطة وzh-Hant للغة الصينية التقليدية. يُرجى العِلم أنّه سيستمر عرض النتائج بلغات أخرى إذا كانت ذات صلة وثيقة بطلب البحث.
safeSearch string
تشير المَعلمة safeSearch إلى ما إذا كان يجب أن تتضمّن نتائج البحث المحتوى المحظور بالإضافة إلى المحتوى العادي.

القيم المقبولة هي:
  • moderate – سيقوم YouTube بفلترة بعض المحتوى من نتائج البحث، وسيتم على الأقل فلترة المحتوى المحظور في منطقتك. استنادًا إلى محتوى نتائج البحث، يمكن إزالتها من نتائج البحث أو خفض ترتيبها فيها. هذه هي قيمة المَعلمة التلقائية.
  • none – لن يفلتر YouTube مجموعة نتائج البحث.
  • strict: سيحاول YouTube استبعاد كل المحتوى المحظور من مجموعة نتائج البحث. استنادًا إلى محتوى نتائج البحث، يمكن إزالتها من نتائج البحث أو خفض ترتيبها فيها.
topicId string
تشير المَعلمة topicId إلى أنّ ردّ من واجهة برمجة التطبيقات يجب أن يحتوي فقط على المراجع المرتبطة بالموضوع المحدّد. تحدّد القيمة معرّف موضوع في Freebase.

ملاحظة مهمة: نظرًا لإيقاف Freebase وواجهة برمجة التطبيقات Freebase API نهائيًا، بدأ عمل المَعلمة topicId بشكل مختلف اعتبارًا من 27 فبراير 2017. في ذلك الوقت، بدأ YouTube في إتاحة مجموعة صغيرة من معرّفات المواضيع المنظَّمة، ويمكنك استخدام هذه المجموعة الأصغر من المعرّفات فقط كقيم لهذه المَعلمة.

type string
تحصر المَعلمة type طلب البحث على استرداد نوع معيّن من الموارد فقط. القيمة هي قائمة بأنواع الموارد مفصولة بفواصل. القيمة التلقائية هي video,channel,playlist.

القيم المقبولة هي:
  • channel
  • playlist
  • video
videoCaption string
تشير المَعلمة videoCaption إلى ما إذا كان على واجهة برمجة التطبيقات فلترة نتائج البحث عن الفيديوهات استنادًا إلى ما إذا كانت تتضمّن ترجمة وشرحًا. إذا حدّدت قيمة لهذه المَعلمة، عليك أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • any – عدم فلترة النتائج استنادًا إلى مدى توفّر الترجمة والشرح
  • ‫closedCaption: تضمين الفيديوهات التي تحتوي على ترجمة فقط
  • none – لعرض الفيديوهات التي لا تتضمّن مقاطع ترجمة وشرح فقط
videoCategoryId string
تتم فلترة نتائج البحث عن الفيديوهات حسب الفئة باستخدام المَعلمة videoCategoryId. في حال تحديد قيمة لهذه المَعلمة، يجب أيضًا ضبط قيمة المَعلمة type على video.
videoDefinition string
تتيح لك المَعلمة videoDefinition حصر البحث ليشمل الفيديوهات العالية الدقة (HD) أو الفيديوهات العادية الدقة (SD) فقط. تتوفّر فيديوهات الدقة العالية بدقة 720p على الأقل، ولكن قد تتوفّر أيضًا درجات دقة أعلى، مثل 1080p. إذا حدّدت قيمة لهذه المَعلمة، عليك أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • ‫any: لعرض جميع الفيديوهات، بغض النظر عن درجة دقتها
  • ‫high: لاسترداد الفيديوهات العالية الدقة فقط
  • ‫standard: لاسترداد الفيديوهات بدقة عادية فقط
videoDimension string
تتيح لك المَعلمة videoDimension حصر عملية البحث لاسترداد الفيديوهات الثنائية الأبعاد أو الثلاثية الأبعاد فقط. في حال تحديد قيمة لهذه المَعلمة، يجب أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • ‫2d: لحصر نتائج البحث واستبعاد الفيديوهات الثلاثية الأبعاد
  • 3d: لحصر نتائج البحث بالفيديوهات الثلاثية الأبعاد فقط
  • ‫any: لتضمين الفيديوهات الثلاثية الأبعاد وغير الثلاثية الأبعاد في النتائج المعروضة هذه هي القيمة الافتراضية.
videoDuration string
تتم فلترة نتائج البحث عن الفيديوهات استنادًا إلى مدتها باستخدام المَعلمة videoDuration. إذا حدّدت قيمة لهذه المَعلمة، عليك أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • ‫any: لا تتم فلترة نتائج البحث عن الفيديوهات استنادًا إلى مدتها. هذه هي القيمة الافتراضية.
  • ‫long: تضمين الفيديوهات التي تزيد مدتها عن 20 دقيقة فقط
  • medium – يجب تضمين الفيديوهات التي تتراوح مدتها بين أربع دقائق و20 دقيقة فقط (بما في ذلك هاتان المدتان).
  • short: تضمين الفيديوهات التي تقل مدتها عن أربع دقائق فقط
videoEmbeddable string
تتيح لك المَعلمة videoEmbeddable حصر البحث على الفيديوهات التي يمكن تضمينها في صفحة ويب فقط. إذا حدّدت قيمة لهذه المَعلمة، عليك أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • ‫any: لعرض كل الفيديوهات، سواء كانت قابلة للتضمين أم لا
  • true: لاسترداد الفيديوهات القابلة للتضمين فقط
videoLicense string
تفلتر المَعلمة videoLicense نتائج البحث لتضمين الفيديوهات التي تتضمّن ترخيصًا معيّنًا فقط. تتيح منصة YouTube للقائمين بتحميل الفيديوهات اختيار إرفاق رخصة المشاع الإبداعي أو ترخيص YouTube العادي لكل فيديو من فيديوهاتهم. في حال تحديد قيمة لهذه المَعلمة، يجب أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • ‫any: لعرض كل الفيديوهات التي تطابق معلمات طلب البحث، بغض النظر عن الترخيص الذي تملكه.
  • creativeCommon: لعرض الفيديوهات التي تتضمّن رخصة المشاع الإبداعي فقط يمكن للمستخدمين إعادة استخدام الفيديوهات التي تحمل هذه الرخصة في فيديوهات أخرى ينشئونها. مزيد من المعلومات
  • youtube: لعرض الفيديوهات التي تتضمّن ترخيص YouTube العادي فقط
videoPaidProductPlacement string
تفلتر المَعلمة videoPaidProductPlacement نتائج البحث لتشمل فقط الفيديوهات التي أشار صانع المحتوى إلى أنّها تتضمّن إعلانًا ترويجيًا مدفوعًا. في حال تحديد قيمة لهذه المَعلمة، يجب أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • ‫any: لعرض جميع الفيديوهات، بغض النظر عمّا إذا كانت تتضمّن إعلانات ترويجية مدفوعة
  • true: لاسترداد الفيديوهات التي تتضمّن إعلانات ترويجية مدفوعة فقط
videoSyndicated string
تتيح لك المَعلمة videoSyndicated حصر البحث بالفيديوهات التي يمكن تشغيلها خارج youtube.com فقط. وإذا حدّدت قيمة لهذه المَعلمة، عليك أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • ‫any: لعرض كل الفيديوهات، سواء كانت متوفرة من خلال الشركاء أو لا
  • ‫true: لاسترداد الفيديوهات المجمّعة فقط
videoType string
تتيح لك المَعلمة videoType حصر البحث بنوع معيّن من الفيديوهات. إذا حدّدت قيمة لهذه المَعلمة، عليك أيضًا ضبط قيمة المَعلمة type على video.

القيم المقبولة هي:
  • any: عرض جميع الفيديوهات
  • ‫episode: لاسترداد حلقات البرامج فقط
  • ‫movie: لاسترداد الأفلام فقط

نص الطلب

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

الردّ

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

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

الخصائص

يوضّح الجدول التالي السمات التي تظهر في نتيجة البحث:

الخصائص
kind string
تحدّد هذه السمة نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#searchListResponse.
etag etag
تمثّل هذه السمة علامة Etag الخاصة بهذا المرجع.
nextPageToken string
الرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken من أجل استرداد الصفحة التالية في مجموعة النتائج.
prevPageToken string
الرمز المميّز الذي يمكن استخدامه كقيمة للمَعلمة pageToken من أجل استرداد الصفحة السابقة في مجموعة النتائج.
regionCode string
رمز المنطقة الذي تم استخدامه في طلب البحث. قيمة السمة هي رمز بلد مكوّن من حرفَين وفقًا لمعيار ISO يحدّد المنطقة. تعرض الطريقة i18nRegions.list قائمة بالمناطق المعتمدة. تكون القيمة التلقائية US. إذا تم تحديد منطقة غير معتمَدة، قد يختار YouTube منطقة أخرى بدلاً من القيمة التلقائية لمعالجة الطلب.
pageInfo object
يحتوي العنصر pageInfo على معلومات تقسيم النتائج إلى صفحات.
pageInfo.totalResults integer
إجمالي عدد النتائج في مجموعة النتائج.يُرجى العِلم أنّ القيمة تقريبية وقد لا تمثّل قيمة دقيقة. بالإضافة إلى ذلك، الحدّ الأقصى للقيمة هو 1,000,000.

يجب عدم استخدام هذه القيمة لإنشاء روابط تقسيم إلى صفحات. بدلاً من ذلك، استخدِم قيم السمتَين nextPageToken وprevPageToken لتحديد ما إذا كان سيتم عرض روابط تقسيم الصفحات.
pageInfo.resultsPerPage integer
عدد النتائج المضمّنة في الردّ من واجهة برمجة التطبيقات.
items[] list
قائمة بالنتائج التي تطابق معايير البحث

أمثلة

ملاحظة: قد لا تمثّل عيّنات التعليمات البرمجية التالية جميع لغات البرمجة المتوافقة. يُرجى الاطّلاع على مستندات مكتبات البرامج للحصول على قائمة باللغات المتوافقة.

برمجة التطبيقات

تبحث هذه الدالة عن فيديوهات ذات صلة بالكلمة الرئيسية "كلاب". يتم تسجيل معرفات الفيديوهات وعناوينها في نتائج البحث في سجلّ برمجة تطبيقات.

يُرجى العِلم أنّ هذا النموذج يحدّ من النتائج إلى 25 نتيجة. لعرض المزيد من النتائج، مرِّر مَعلمات إضافية كما هو موضّح هنا: https://developers.google.com/youtube/data/reference/rest/v3/search/list
function searchByKeyword() {
  var results = YouTube.Search.list('id,snippet', {q: 'dogs', maxResults: 25});

  for(var i in results.items) {
    var item = results.items[i];
    Logger.log('[%s] Title: %s', item.id.videoId, item.snippet.title);
  }
}

Go

تستدعي عينة التعليمات البرمجية هذه طريقة search.list في واجهة برمجة التطبيقات لاسترداد نتائج البحث المرتبطة بكلمة رئيسية معيّنة.

يستخدم هذا المثال مكتبة برامج Go.

package main

import (
	"flag"
	"fmt"
	"log"
	"net/http"

	"google.golang.org/api/googleapi/transport"
	"google.golang.org/api/youtube/v3"
)

var (
	query      = flag.String("query", "Google", "Search term")
	maxResults = flag.Int64("max-results", 25, "Max YouTube results")
)

const developerKey = "YOUR DEVELOPER KEY"

func main() {
	flag.Parse()

	client := &http.Client{
		Transport: &transport.APIKey{Key: developerKey},
	}

	service, err := youtube.New(client)
	if err != nil {
		log.Fatalf("Error creating new YouTube client: %v", err)
	}

	// Make the API call to YouTube.
	call := service.Search.List("id,snippet").
		Q(*query).
		MaxResults(*maxResults)
	response, err := call.Do()
	handleError(err, "")

	// Group video, channel, and playlist results in separate lists.
	videos := make(map[string]string)
	channels := make(map[string]string)
	playlists := make(map[string]string)

	// Iterate through each item and add it to the correct list.
	for _, item := range response.Items {
		switch item.Id.Kind {
		case "youtube#video":
			videos[item.Id.VideoId] = item.Snippet.Title
		case "youtube#channel":
			channels[item.Id.ChannelId] = item.Snippet.Title
		case "youtube#playlist":
			playlists[item.Id.PlaylistId] = item.Snippet.Title
		}
	}

	printIDs("Videos", videos)
	printIDs("Channels", channels)
	printIDs("Playlists", playlists)
}

// Print the ID and title of each result in a list as well as a name that
// identifies the list. For example, print the word section name "Videos"
// above a list of video search results, followed by the video ID and title
// of each matching video.
func printIDs(sectionName string, matches map[string]string) {
	fmt.Printf("%v:\n", sectionName)
	for id, title := range matches {
		fmt.Printf("[%v] %v\n", id, title)
	}
	fmt.Printf("\n\n")
}

NET.

تستدعي عيّنة التعليمات البرمجية التالية طريقة search.list في واجهة برمجة التطبيقات لاسترداد نتائج البحث المرتبطة بكلمة رئيسية معيّنة.

يستخدم هذا المثال مكتبة برامج.NET.

using System;
using System.Collections.Generic;
using System.IO;
using System.Reflection;
using System.Threading;
using System.Threading.Tasks;

using Google.Apis.Auth.OAuth2;
using Google.Apis.Services;
using Google.Apis.Upload;
using Google.Apis.Util.Store;
using Google.Apis.YouTube.v3;
using Google.Apis.YouTube.v3.Data;

namespace Google.Apis.YouTube.Samples
{
  /// <summary>
  /// YouTube Data API v3 sample: search by keyword.
  /// Relies on the Google APIs Client Library for .NET, v1.7.0 or higher.
  /// See https://developers.google.com/api-client-library/dotnet/get_started
  ///
  /// Set ApiKey to the API key value from the APIs & auth > Registered apps tab of
  ///   https://cloud.google.com/console
  /// Please ensure that you have enabled the YouTube Data API for your project.
  /// </summary>
  internal class Search
  {
    [STAThread]
    static void Main(string[] args)
    {
      Console.WriteLine("YouTube Data API: Search");
      Console.WriteLine("========================");

      try
      {
        new Search().Run().Wait();
      }
      catch (AggregateException ex)
      {
        foreach (var e in ex.InnerExceptions)
        {
          Console.WriteLine("Error: " + e.Message);
        }
      }

      Console.WriteLine("Press any key to continue...");
      Console.ReadKey();
    }

    private async Task Run()
    {
      var youtubeService = new YouTubeService(new BaseClientService.Initializer()
      {
        ApiKey = "REPLACE_ME",
        ApplicationName = this.GetType().ToString()
      });

      var searchListRequest = youtubeService.Search.List("snippet");
      searchListRequest.Q = "Google"; // Replace with your search term.
      searchListRequest.MaxResults = 50;

      // Call the search.list method to retrieve results matching the specified query term.
      var searchListResponse = await searchListRequest.ExecuteAsync();

      List<string> videos = new List<string>();
      List<string> channels = new List<string>();
      List<string> playlists = new List<string>();

      // Add each result to the appropriate list, and then display the lists of
      // matching videos, channels, and playlists.
      foreach (var searchResult in searchListResponse.Items)
      {
        switch (searchResult.Id.Kind)
        {
          case "youtube#video":
            videos.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.VideoId));
            break;

          case "youtube#channel":
            channels.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.ChannelId));
            break;

          case "youtube#playlist":
            playlists.Add(String.Format("{0} ({1})", searchResult.Snippet.Title, searchResult.Id.PlaylistId));
            break;
        }
      }

      Console.WriteLine(String.Format("Videos:\n{0}\n", string.Join("\n", videos)));
      Console.WriteLine(String.Format("Channels:\n{0}\n", string.Join("\n", channels)));
      Console.WriteLine(String.Format("Playlists:\n{0}\n", string.Join("\n", playlists)));
    }
  }
}

Ruby

يستدعي هذا النموذج طريقة search.list في واجهة برمجة التطبيقات لاسترداد نتائج البحث المرتبطة بكلمة رئيسية معيّنة.

يستخدم هذا المثال مكتبة برامج Ruby.

#!/usr/bin/ruby

require 'rubygems'
gem 'google-api-client', '>0.7'
require 'google/api_client'
require 'trollop'

# Set DEVELOPER_KEY to the API key value from the APIs & auth > Credentials
# tab of
# {{ Google Cloud Console }} <{{ https://cloud.google.com/console }}>
# Please ensure that you have enabled the YouTube Data API for your project.
DEVELOPER_KEY = 'REPLACE_ME'
YOUTUBE_API_SERVICE_NAME = 'youtube'
YOUTUBE_API_VERSION = 'v3'

def get_service
  client = Google::APIClient.new(
    :key => DEVELOPER_KEY,
    :authorization => nil,
    :application_name => $PROGRAM_NAME,
    :application_version => '1.0.0'
  )
  youtube = client.discovered_api(YOUTUBE_API_SERVICE_NAME, YOUTUBE_API_VERSION)

  return client, youtube
end

def main
  opts = Trollop::options do
    opt :q, 'Search term', :type => String, :default => 'Google'
    opt :max_results, 'Max results', :type => :int, :default => 25
  end

  client, youtube = get_service

  begin
    # Call the search.list method to retrieve results matching the specified
    # query term.
    search_response = client.execute!(
      :api_method => youtube.search.list,
      :parameters => {
        :part => 'snippet',
        :q => opts[:q],
        :maxResults => opts[:max_results]
      }
    )

    videos = []
    channels = []
    playlists = []

    # Add each result to the appropriate list, and then display the lists of
    # matching videos, channels, and playlists.
    search_response.data.items.each do |search_result|
      case search_result.id.kind
        when 'youtube#video'
          videos << "#{search_result.snippet.title} (#{search_result.id.videoId})"
        when 'youtube#channel'
          channels << "#{search_result.snippet.title} (#{search_result.id.channelId})"
        when 'youtube#playlist'
          playlists << "#{search_result.snippet.title} (#{search_result.id.playlistId})"
      end
    end

    puts "Videos:\n", videos, "\n"
    puts "Channels:\n", channels, "\n"
    puts "Playlists:\n", playlists, "\n"
  rescue Google::APIClient::TransmissionError => e
    puts e.result.body
  end
end

main

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
badRequest (400) invalidChannelId تحدّد المَعلمة channelId معرّف قناة غير صالح.
badRequest (400) invalidLocation تم تنسيق قيمة المَعلمة location و/أو locationRadius بشكل غير صحيح.
badRequest (400) invalidRelevanceLanguage تم تنسيق قيمة المَعلمة relevanceLanguage بشكل غير صحيح.
badRequest (400) invalidSearchFilter يحتوي الطلب على تركيبة غير صالحة من فلاتر البحث و/أو القيود. يُرجى العِلم أنّه يجب ضبط المَعلمة type على video في حال ضبط المَعلمتَين forContentOwner أو forMine على true. يجب أيضًا ضبط المَعلمة type على video في حال ضبط قيمة للمَعلمات eventType أو videoCaption أو videoCategoryId أو videoDefinition أو videoDimension أو videoDuration أو videoEmbeddable أو videoLicense أو videoSyndicated أو videoType.

جرِّبها الآن.

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