Search

نتیجه search حاوی اطلاعاتی درباره ویدیو، کانال، یا فهرست پخش YouTube است که با پارامترهای جستجوی مشخص‌شده در درخواست API مطابقت دارد. درحالی‌که نتیجه جستجو به منبعی مشخصاً شناساننده، مانند ویدیو، اشاره می‌کند، داده‌های پایدار خودش را ندارد.

روش‌ها

میانای برنامه‌سازی کاربردی از روش‌های زیر برای جستجو پشتیبانی می‌کند:

فهرست
مجموعه‌ای از نتایج جستجو را که با پارامترهای پُرسمان مشخص‌شده در درخواست میانای برنامه‌سازی کاربردی مطابقت دارد برمی‌گرداند. به‌طور پیش‌فرض، مجموعه نتایج جستجو منابع 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 – تصویر ریزعکس پیش‌فرض. ریزعکس پیش‌فرض برای یک ویدیو – یا منبعی که به یک ویدیو اشاره می‌کند، مانند یک مورد فهرست پخش یا نتیجه جستجو – ۱۲۰ پیکسل عرض و ۹۰ پیکسل ارتفاع دارد. ریزعکس پیش‌فرض برای یک کانال ۸۸ پیکسل عرض و ۸۸ پیکسل ارتفاع دارد.
  • medium – نسخه‌ای با وضوح بالاتر از تصویر ریزعکس. برای ویدیو (یا منبعی که به ویدیو ارجاع می‌دهد)، این تصویر ۳۲۰ پیکسل عرض و ۱۸۰ پیکسل ارتفاع دارد. برای کانال، این تصویر ۲۴۰ پیکسل عرض و ۲۴۰ پیکسل ارتفاع دارد.
  • high – نسخه با وضوح بالای تصویر کوچک. برای ویدیو (یا منبعی که به ویدیو اشاره می‌کند)، این تصویر ۴۸۰ پیکسل عرض و ۳۶۰ پیکسل ارتفاع دارد. برای یک کانال، این تصویر ۸۰۰ پیکسل عرض و ۸۰۰ پیکسل ارتفاع دارد.
  • standard – نسخه‌ای با وضوح حتی بالاتر از تصویر ریزعکس نسبت‌به تصویر با وضوح high. این تصویر برای برخی ویدیوها و منابع دیگری که به ویدیوها ارجاع می‌دهند، مانند موارد فهرست پخش یا نتایج جستجو، دردسترس است. این تصویر ۶۴۰ پیکسل عرض و ۴۸۰ پیکسل ارتفاع دارد.
  • maxres – نسخه با بالاترین وضوح از تصویر ریزعکس. این اندازه تصویر برای برخی ویدیوها و منابع دیگری که به ویدیوها ارجاع می‌دهند، مانند موارد فهرست پخش یا نتایج جستجو، دردسترس است. این تصویر ۱۲۸۰ پیکسل عرض و ۷۲۰ پیکسل ارتفاع دارد.

توجه: تصاویر کوچک ۱۰۸۰ پیکسل به بالا (fhd، qhd، و uhd) برای نتایج جستجو پشتیبانی نمی‌شوند. برای بازیابی ریزعکس‌های با وضوح بالاتر، بااستفاده از شناسه منبع، نقطه پایانی مختص منبع (مثل videos.list) را فراخوانی کنید.
snippet.thumbnails.(key).url string
نشانی وب تصویر.
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 نشان می‌دهد که کانال همه‌فرستی زنده فعالی دارد.