Videos: list

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

تأثیر سهمیه: تماس با این روش هزینه سهمیه ۱ واحدی دارد.

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

درخواست

درخواست HTTP

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

پارامترها

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

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

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

فهرست زیر حاوی نام‌های part است که می‌توانید در مقدار پارامتر اضافه کنید:
  • brandPartner
  • 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 مجموعه نتایج برگشتی را به حداکثر ۱۰۰۰ ویدیو محدود می‌کند. حتی اگر ویژگی pageInfo.totalResults پاسخ نشان‌دهنده مجموع بالاتری باشد، صفحه‌بندی بااستفاده از پارامتر pageToken فقط امکان بازیابی ۱۰۰۰ مورد اخیر را فراهم می‌کند.



این پارامتر مقادیر زیر را می‌پذیرد:

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

خطاها

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

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

امتحان کنید!

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