Search

تحتوي نتيجة search على معلومات حول فيديو على YouTube أو قناة أو قائمة تشغيل تتطابق مع مَعلمات البحث المحدّدة في طلب البيانات من واجهة برمجة التطبيقات. على الرغم من أنّ نتيجة البحث تشير إلى مصدر يمكن التعرّف عليه بدقة، مثل فيديو، إلا أنّها لا تتضمّن بيانات ثابتة خاصة بها.

الطُرق

تتيح واجهة برمجة التطبيقات الطرق التالية للبحث:

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

تمثيل الموارد

تعرض بنية JSON التالية تنسيق نتيجة البحث:

{
  "kind": "youtube#searchResult",
  "etag": etag,
  "id": {
    "kind": string,
    "videoId": string,
    "channelId": string,
    "playlistId": string
  },
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "channelTitle": string,
    "liveBroadcastContent": string
  }
}

الخصائص

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

الخصائص
kind string
تحدّد هذه السمة نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#searchResult.
etag etag
تمثّل هذه السمة Etag الخاصة بهذا المرجع.
id object
يحتوي العنصر id على معلومات يمكن استخدامها لتحديد المورد الذي يتطابق مع طلب البحث بشكلٍ فريد.
id.kind string
نوع مورد واجهة برمجة التطبيقات.
id.videoId string
إذا كانت قيمة السمة id.type هي youtube#video، ستكون هذه السمة متوفّرة وستتضمّن قيمتها المعرّف الذي يستخدمه YouTube لتحديد فيديو بشكل فريد يتطابق مع طلب البحث.
id.channelId string
إذا كانت قيمة السمة id.type هي youtube#channel، ستكون هذه السمة متوفّرة وستتضمّن قيمتها المعرّف الذي يستخدمه YouTube لتحديد قناة بشكل فريد تتطابق مع طلب البحث.
id.playlistId string
إذا كانت قيمة السمة id.type هي youtube#playlist، ستكون هذه السمة متوفّرة وستتضمّن قيمتها المعرّف الذي يستخدمه YouTube لتحديد قائمة تشغيل بشكل فريد تتطابق مع طلب البحث.
snippet object
يحتوي العنصر snippet على تفاصيل أساسية حول نتيجة البحث، مثل عنوانها أو وصفها. على سبيل المثال، إذا كانت نتيجة البحث عبارة عن فيديو، سيكون العنوان هو عنوان الفيديو والوصف هو وصف الفيديو.
snippet.publishedAt datetime
تمثّل هذه السمة تاريخ ووقت إنشاء المرجع الذي تحدّده نتيجة البحث. يتم تحديد القيمة بالتنسيق ISO 8601.
snippet.channelId string
القيمة التي يستخدمها YouTube للتعريف بشكل فريد عن القناة التي نشرت المرجع الذي تحدّده نتيجة البحث.
snippet.title string
تمثّل هذه السمة عنوان نتيجة البحث.
snippet.description string
تمثّل هذه السمة وصفًا لنتيجة البحث.
snippet.thumbnails object
خريطة للصور المصغّرة المرتبطة بنتيجة البحث بالنسبة إلى كل عنصر في الخريطة، يكون المفتاح هو اسم الصورة المصغّرة، والقيمة هي عنصر يحتوي على معلومات أخرى حول الصورة المصغّرة.
snippet.thumbnails.(key) object
قيم المفاتيح الصالحة هي:
  • default: الصورة المصغّرة التلقائية يبلغ حجم الصورة المصغّرة التلقائية للفيديو أو المرجع الذي يشير إلى فيديو، مثل عنصر في قائمة تشغيل أو نتيجة بحث، 120 بكسل عرضًا و90 بكسل ارتفاعًا. يبلغ عرض الصورة المصغّرة التلقائية للقناة 88 بكسل وطولها 88 بكسل.
  • medium: نسخة من الصورة المصغّرة بدقة أعلى بالنسبة إلى فيديو (أو مرجع يشير إلى فيديو)، يبلغ عرض هذه الصورة 320 بكسل وارتفاعها 180 بكسل. بالنسبة إلى قناة، يبلغ عرض هذه الصورة 240 بكسل وارتفاعها 240 بكسل.
  • ‫high: نسخة عالية الدقة من الصورة المصغّرة بالنسبة إلى فيديو (أو مرجع يشير إلى فيديو)، يبلغ عرض هذه الصورة 480 بكسل وارتفاعها 360 بكسل. بالنسبة إلى القناة، يبلغ عرض هذه الصورة 800 بكسل وارتفاعها 800 بكسل.
  • ‫standard: نسخة من الصورة المصغّرة بدقة أعلى من دقة الصورة high. تتوفّر هذه الصورة لبعض الفيديوهات والمراجع الأخرى التي تشير إلى الفيديوهات، مثل عناصر قائمة التشغيل أو نتائج البحث. يبلغ عرض هذه الصورة 640 بكسل وارتفاعها 480 بكسل.
  • maxres: هي النسخة الأعلى دقة من الصورة المصغّرة. يتوفّر حجم الصورة هذا لبعض الفيديوهات والمراجع الأخرى التي تشير إلى الفيديوهات، مثل عناصر قائمة التشغيل أو نتائج البحث. يبلغ عرض هذه الصورة 1280 بكسل وارتفاعها 720 بكسل.

ملاحظة: الصور المصغّرة بدقة 1080p+‎ (fhd وqhd وuhd) غير متاحة لنتائج البحث. لاسترداد صور مصغّرة بدقة أعلى، اتّصِل بنقطة النهاية الخاصة بالمرجع (مثل videos.list) باستخدام رقم تعريف المرجع.
snippet.thumbnails.(key).url string
تمثّل عنوان URL الخاص بالصورة.
snippet.thumbnails.(key).width unsigned integer
تمثّل هذه السمة عرض الصورة.
snippet.thumbnails.(key).height unsigned integer
تمثّل هذه السمة ارتفاع الصورة.
snippet.channelTitle string
تمثّل هذه السمة عنوان القناة التي نشرت المرجع الذي تحدّده نتيجة البحث.
snippet.liveBroadcastContent string
تشير هذه السمة إلى ما إذا كان المرجع video أو channel يتضمّن محتوًى من بث مباشر. قيم الخاصية الصالحة هي upcoming وlive وnone.

بالنسبة إلى مرجع video، تشير القيمة upcoming إلى أنّ الفيديو هو بث مباشر لم يبدأ بعد، بينما تشير القيمة live إلى أنّ الفيديو هو بث مباشر نشط. بالنسبة إلى مورد channel، تشير القيمة upcoming إلى أنّ القناة لديها بث مجدول لم يبدأ بعد، بينما تشير القيمة live إلى أنّ القناة لديها بث مباشر نشط.