Videos: list

فهرستی از ویدیوها را برمی‌گرداند که با پارامترهای درخواست API مطابقت دارند.

تاثیر سهمیه ای: فراخوانی به این روش هزینه سهمیه ای 1 واحدی دارد.

موارد استفاده رایج

درخواست کنید

درخواست HTTP 

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

پارامترها

جدول زیر پارامترهایی را که این کوئری پشتیبانی می کند فهرست می کند. تمام پارامترهای لیست شده پارامترهای پرس و جو هستند.

پارامترها
پارامترهای مورد نیاز
part string
پارامتر part لیستی از یک یا چند ویژگی منبع video جدا شده با کاما را مشخص می کند که پاسخ API شامل آن خواهد شد.

اگر پارامتر خاصیتی را مشخص کند که حاوی ویژگی های فرزند است، ویژگی های فرزند در پاسخ گنجانده می شود. به عنوان مثال، در یک منبع video ، ویژگی snippet حاوی ویژگی های channelId ، title ، description ، tags و categoryId است. به این ترتیب، اگر part=snippet را تنظیم کنید، پاسخ API حاوی تمام آن ویژگی ها خواهد بود.

لیست زیر شامل نام part است که می توانید در مقدار پارامتر بگنجانید:
  • 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 تنظیم کنید تا به API دستور دهید فقط ویدیوهایی را که کاربر تأیید شده پسندیده یا دوست ندارد، بازگرداند.

مقادیر قابل قبول عبارتند از:
  • dislike - فقط ویدیوهایی را برمی‌گرداند که کاربر احراز هویت آنها را دوست ندارد.
  • like - فقط ویدیوی مورد پسند کاربر تایید شده را برمی گرداند.
پارامترهای اختیاری
hl string
پارامتر hl به API دستور می دهد که ابرداده های منبع محلی را برای یک زبان برنامه خاص که وب سایت 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 را مالک و مدیریت می‌کنند. این به صاحبان محتوا امکان می‌دهد یک بار احراز هویت کنند و به تمام داده‌های ویدیویی و کانال خود دسترسی داشته باشند، بدون اینکه نیازی به ارائه اعتبارنامه احراز هویت برای هر کانال جداگانه داشته باشند. حساب CMS که کاربر با آن احراز هویت می‌کند باید به مالک محتوای YouTube مشخص شده مرتبط باشد.
pageToken string
پارامتر pageToken صفحه خاصی را در مجموعه نتایج مشخص می کند که باید برگردانده شود. در یک پاسخ API، ویژگی های nextPageToken و prevPageToken صفحات دیگری را شناسایی می کنند که می توانند بازیابی شوند.

توجه: این پارامتر برای استفاده همراه با پارامتر myRating پشتیبانی می شود، اما برای استفاده همراه با پارامتر id پشتیبانی نمی شود.
regionCode string
پارامتر regionCode به API دستور می دهد تا نمودار ویدیویی موجود در منطقه مشخص شده را انتخاب کند. این پارامتر فقط می تواند همراه با پارامتر 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
نوع منبع API را مشخص می کند. مقدار youtube#videoListResponse خواهد بود.
etag etag
Etag این منبع
nextPageToken string
نشانه ای که می تواند به عنوان مقدار پارامتر pageToken برای بازیابی صفحه بعدی در مجموعه نتایج استفاده شود.
prevPageToken string
نشانه ای که می تواند به عنوان مقدار پارامتر pageToken برای بازیابی صفحه قبلی در مجموعه نتایج استفاده شود.
pageInfo object
شی pageInfo اطلاعات صفحه‌بندی را برای مجموعه نتایج کپسوله می‌کند.
pageInfo. totalResults integer
تعداد کل نتایج در مجموعه نتایج.
pageInfo. resultsPerPage integer
تعداد نتایج موجود در پاسخ API.
items[] list
فهرستی از ویدیوهایی که با معیارهای درخواست مطابقت دارند.

خطاها

جدول زیر پیام های خطایی را مشخص می کند که API می تواند در پاسخ به تماس با این روش بازگرداند. برای جزئیات بیشتر به مستندات پیام خطا مراجعه کنید.

نوع خطا جزئیات خطا توضیحات
badRequest (400) videoChartNotFound نمودار ویدیویی درخواستی پشتیبانی نمی شود یا در دسترس نیست.
forbidden (403) forbidden درخواست به درستی برای دسترسی به فایل ویدیویی یا اطلاعات پردازش مجاز نیست. توجه داشته باشید که بخش‌های fileDetails ، processingDetails و suggestions فقط برای مالک آن ویدیو در دسترس است.
forbidden (403) forbidden درخواست نمی تواند به اطلاعات رتبه بندی کاربر دسترسی پیدا کند. این خطا ممکن است به این دلیل رخ دهد که درخواست به درستی مجوز استفاده از پارامتر myRating را ندارد.
notFound (404) videoNotFound ویدیویی که می‌خواهید بازیابی کنید پیدا نمی‌شود. مقدار پارامتر id درخواست را بررسی کنید تا مطمئن شوید که درست است.

آن را امتحان کنید!

از APIs Explorer برای فراخوانی این API و مشاهده درخواست و پاسخ API استفاده کنید.